Manual installation
Preparation
Introduction
Before starting the installation, it is strongly recommended to familiarize yourself with the architecture, technical requirements, and operation schemes.
All further actions require root user privileges.
Instructions for configuring replications can be found on the Cluster Configuration, Replication page.
For passwords and secret combinations, a set of characters is used - abcdefghijklmnopqrstuvwxyzABCDEF. Be sure to generate a more complex password consisting of at least 32 characters.
Archive Loading
All clients are provided with a compressed archive with the extension .tar.gz. Unpack the archive and move its contents to the /opt/akd directory:
{
tar xzf <archive_name>.tar.gz
mv ak /opt/akd
}
Checking the Server Time
Time synchronization between servers is critical: discrepancies can lead to malfunction and incorrect statistics. Configure an NTP server and verify synchronization:
timedatectl status
Setting System Limits
Add the following limits in the /etc/security/limits.conf file:
* - nofile 1048576
root - nofile 1048576
root - memlock unlimited
Then reconnect to the server and verify that the limits have been updated:
ulimit -n
Installing Dependencies
Installate the followibg dependencies:
{
apt update
apt install --no-install-recommends xvfb cutycapt unzip gcc g++ libsnappy-dev make autoconf libpcre3-dev libgomp1
}
Installation of MongoDB or Percona Server for MongoDB
MongoDB is used to store system settings and user data.
Additional materials:
The platform supports two MongoDB options:
- Standard MongoDB Community Edition — the basic version from MongoDB Inc.
- Percona Server for MongoDB — a compatible replacement from Percona with additional features: enhanced data-at-rest encryption, extended auditing, improved diagnostics, and performance optimization.
For production environments, Percona Server for MongoDB is recommended as a more secure and performant solution. At the same time, all instructions for user creation and connection configuration remain the same for both options.
Choose one of the installation options:
- MongoDB Community Edition
- Percona Server for MongoDB
Go to the download page, select version 8.0, your OS version, and the .tgz archive. Copy the link and download the archive:
wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2404-8.0.10.tgz
Extract the archive to /usr/local and create a symbolic link:
{
tar xzf mongodb-linux-x86_64-ubuntu2404-8.0.10.tgz -C /usr/local
ln -s /usr/local/mongodb-linux-x86_64-ubuntu2404-8.0.10 /usr/local/mongodb
}
Install the dependencies:
{
apt update
apt install -y gnupg curl
}
Create the user, group, and working directories:
{
groupadd mongodb
useradd -r -g mongodb -s /bin/false mongodb
mkdir -p /var/{lib,log}/mongodb
chown -R mongodb:mongodb /var/{lib,log}/mongodb
}
Create the configuration file /etc/mongod.conf:
# mongod.conf
# for documentation of all options, see:
# http://docs.mongodb.org/manual/reference/configuration-options/
storage:
dbPath: /var/lib/mongodb
wiredTiger:
engineConfig:
directoryForIndexes: true
systemLog:
destination: file
logAppend: true
logRotate: reopen
path: /var/log/mongodb/mongod.log
net:
port: 27017
bindIp: 127.0.0.1
Create the file /etc/systemd/system/mongod.service:
[Unit]
Description=MongoDB Database Server
Documentation=https://docs.mongodb.org/manual
After=network.target
[Service]
User=mongodb
Group=mongodb
ExecStart=/usr/local/mongodb/bin/mongod --config /etc/mongod.conf
PIDFile=/run/mongod.pid
Restart=always
LimitFSIZE=infinity
LimitCPU=infinity
LimitAS=infinity
LimitNOFILE=256000
LimitNPROC=256000
LimitMEMLOCK=infinity
TasksMax=infinity
TasksAccounting=false
[Install]
WantedBy=multi-user.target
Enable the service at startup, start it, and check its status:
{
systemctl enable mongod.service
systemctl start mongod.service
systemctl status mongod.service
}
Download and install MongoDB Shell.
Add the official Percona repository and update the package list:
{
wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
dpkg -i percona-release_latest.generic_all.deb
percona-release setup psmdb80
apt update
}
Install Percona Server for MongoDB. The package will create the required directories (/var/lib/mongodb, /var/log/mongodb), the mongodb user and group, and install additional utilities, including mongosh.
{
apt install -y percona-server-mongodb
}
Installing a specific version of Percona Server for MongoDB
If you need to install a specific release instead of the latest available version, first list the available versions:
apt-cache madison percona-server-mongodb
Example output:
percona-server-mongodb | 8.0.10-5.jammy | http://repo.percona.com/psmdb-80/apt jammy/main amd64 Packages
percona-server-mongodb | 8.0.9-4.jammy | http://repo.percona.com/psmdb-80/apt jammy/main amd64 Packages
Then install the required version by specifying the package version explicitly:
apt install \
percona-server-mongodb=<version> \
percona-server-mongodb-server=<version> \
percona-server-mongodb-shell=<version> \
percona-server-mongodb-mongos=<version> \
percona-server-mongodb-tools=<version>
Create or edit the configuration file /etc/mongod.conf:
storage:
dbPath: /var/lib/mongodb
engine: wiredTiger
wiredTiger:
engineConfig:
directoryForIndexes: true
systemLog:
destination: file
logAppend: true
logRotate: reopen
path: /var/log/mongodb/mongod.log
net:
port: 27017
bindIp: 127.0.0.1
Percona Server for MongoDB supports data-at-rest encryption. To enable it, set the enableEncryption parameter and specify how the master key will be stored. This guide covers two master key storage options: a local key file and HashiCorp Vault.
Encryption can only be enabled on an empty database. If the database already contains data, use a separate migration procedure.
Generate a key file:
openssl rand -base64 32 > /etc/mongodb-encryption-keyfile
chown mongod:mongod /etc/mongodb-encryption-keyfile
chmod 600 /etc/mongodb-encryption-keyfile
The key file must contain a 32-byte base64 string. Access permissions to the file must be restricted.
Edit /etc/mongod.conf:
storage:
dbPath: /var/lib/mongodb
engine: wiredTiger
wiredTiger:
engineConfig:
directoryForIndexes: true
systemLog:
destination: file
logAppend: true
logRotate: reopen
path: /var/log/mongodb/mongod.log
net:
port: 27017
bindIp: 127.0.0.1
security:
enableEncryption: true
encryptionKeyFile: /etc/mongodb-encryption-keyfile
Using HashiCorp Vault instead of a local key file
HashiCorp Vault is the preferred way to store the master key. Percona Server for MongoDB uses KV Secrets Engine v2 with versioning enabled. On first startup, the server generates a new random master key and stores it in Vault at the specified path.
In this case, use the following configuration instead of the encryptionKeyFile parameter:
security:
enableEncryption: true
vault:
serverName: VAULT_HOST
port: 8200
tokenFile: /etc/mongodb-vault-token
secret: secret/data/mongodb/node1
serverCAFile: /etc/ssl/certs/vault-ca.crt
The tokenFile must contain the Vault token without any extra lines or parameters.
chown mongod:mongod /etc/mongodb-vault-token
chmod 600 /etc/mongodb-vault-token
Restart MongoDB and check the service status:
{
systemctl enable mongod.service
systemctl restart mongod.service
systemctl status mongod.service
}
Verify that encryption is enabled:
mongosh --eval "db.serverCmdLineOpts()"
If a local key file is used, verify the file permissions:
ls -la /etc/mongodb-encryption-keyfile
If HashiCorp Vault is used, verify the Vault parameters in the runtime configuration:
mongosh --eval "db.serverCmdLineOpts()" | grep -A 10 vault
Connect to the database using mongosh and create a user:
mongosh
Run the following commands in the MongoDB shell:
use admin;
db.createUser({
"user": "altcraft",
"pwd": "abcdefghijklmnopqrstuvwxyzABCDEF",
"roles": [{
"role": "root",
"db": "admin"
}]
})
exit
The password abcdefghijklmnopqrstuvwxyzABCDEF is provided only as an example. Be sure to generate your own strong password with a minimum length of 32 characters.
Configuring the platform connection
Update the connection parameters in main.json:
{
"MONGO_AUTH_DB": "admin",
"CONTROLDB_IP": "127.0.0.1",
"CONTROLDB_PORT": 27017,
"CONTROLDB_NAME": "control",
"CONTROLDB_USER": "altcraft",
"CONTROLDB_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"FILEDB_ENABLE": true,
"FILEDB_IP": "127.0.0.1",
"FILEDB_NAME": "filedb",
"FILEDB_USER": "altcraft",
"FILEDB_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"FILEDB_PORT": 27017
}
-
Authentication: By default, authentication is disabled in MongoDB. To improve security, you can use the SCRAM mechanism supported by the platform (see the documentation).
-
TLS: To enable secure connections, add the following parameters to the configuration:
net:
tls:
mode: requireTLS
certificateKeyFile: <path to the PEM file>
CAFile: <path to the CA certificate>
Installation of ClickHouse
ClickHouse database is used for storing history, statistics, and forming user reports. Below is the installation guide using DEB packages.
Install dependencies and add the official repository:
{
apt update
apt install -y apt-transport-https ca-certificates dirmngr gnupg
apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754
echo "deb https://packages.clickhouse.com/deb stable main" | tee /etc/apt/sources.list.d/clickhouse.list
}
Install Clickhouse:
{
apt update
apt install -y clickhouse-server clickhouse-client
}
Add the service to autostart and start it:
```bash
{
systemctl enable clickhouse-server.service
systemctl start clickhouse-server.service
systemctl status clickhouse-server.service
}
Create the user configuration file altcraft at the path /etc/clickhouse-server/users.d/altcraft.xml:
<yandex>
<users>
<altcraft>
<password>abcdefghijklmnopqrstuvwxyzABCDEF</password>
<networks>
<ip>::/0</ip>
</networks>
<profile>default</profile>
<quota>default</quota>
<access_management>1</access_management>
<database>
<name>altcraft_system</name>
<access>
<all/>
</access>
</database>
</altcraft>
</users>
</yandex>
Update the connection parameters in the configuration file main.json:
{
"CLICKHOUSE_SYSTEM": {
"HOST": "localhost",
"PORT": 9000,
"USER": "altcraft",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"DATABASE_NAME": "altcraft_system"
}
}
Installation of SSDB
SSDB databases are used for system notifications and storing hardbounce (non-existent) email addresses.
Install dependencies, clone the Git repository, then build and install:
{
apt update
apt install -y git build-essential cmake autoconf
git clone https://github.com/ideawu/ssdb.git /usr/local/ssdb
cd /usr/local/ssdb
make
}
Create the working directories:
mkdir -p /var/lib/ssdb/{hardbounces,notifications} /var/{log,lib}/ssdb /etc/ssdb
Create the configuration file /etc/ssdb/hardbounces.conf:
Note: The configuration file should use a tab character for indentation instead of spaces.
# hardbounces.conf
# MUST indent by TAB!
work_dir = /var/lib/ssdb/hardbounces
pidfile = /run/ssdb@hardbounces.pid
server:
ip: 127.0.0.1
port: 4420
auth: abcdefghijklmnopqrstuvwxyzABCDEF
leveldb:
cache_size: 500
write_buffer_size: 64
compaction_speed: 1000
compression: yes
logger:
level: error
output: /var/log/ssdb/hardbounces.log
rotate:
size: 1000000000
Create the configuration file /etc/ssdb/notifications.conf:
Note: The configuration file should use a tab character for indentation instead of spaces.
# notifications.conf
# MUST indent by TAB!
work_dir = /var/lib/ssdb/notifications
pidfile = /run/ssdb@notifications.pid
server:
ip: 127.0.0.1
port: 4430
auth: abcdefghijklmnopqrstuvwxyzABCDEF
leveldb:
cache_size: 500
write_buffer_size: 64
compaction_speed: 1000
compression: yes
logger:
level: error
output: /var/log/ssdb/notifications.log
rotate:
size: 1000000000
Create a systemd service at the path /etc/systemd/system/ssdb@.service:
[Unit]
Description=High performance NoSQL database
After=network.target
[Service]
User=root
Group=root
WorkingDirectory=/var/lib/ssdb/%i
ExecStart=/usr/local/ssdb/ssdb-server /etc/ssdb/%i.conf -s start -d
ExecStop=/usr/local/ssdb/ssdb-server /etc/ssdb/%i.conf -s stop -d
PIDFile=/run/ssdb@%i.pid
Restart=always
LimitFSIZE=infinity
LimitCPU=infinity
LimitAS=infinity
LimitNOFILE=256000
LimitNPROC=256000
Type=forking
[Install]
WantedBy=multi-user.target
Add the services to autostart and start them:
{
systemctl enable ssdb@hardbounces
systemctl enable ssdb@notifications
systemctl start ssdb@hardbounces
systemctl start ssdb@notifications
systemctl status ssdb@hardbounces
systemctl status ssdb@notifications
}
Update the connection parameters in the configuration file main.json:
{
"SSDB_HBSUPP_IP": "127.0.0.1",
"SSDB_HBSUPP_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"SSDB_HBSUPP_PORT": 4420,
"SSDB_NOTIFY_IP": "127.0.0.1",
"SSDB_NOTIFY_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"SSDB_NOTIFY_PORT": 4430
}
Installation of RabbitMQ
RabbitMQ message broker is used for various interactions between platform services. Below is the instruction for installing from DEB packages hosted on Cloudsmith.
Add the required repositories to the system:
{
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/setup.deb.sh | bash
curl -1sLf https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/setup.deb.sh | bash
}
Install RabbitMQ:
{
apt update
apt install -y --fix-missing rabbitmq-server
}
Add the service to autostart and start it:
{
systemctl enable rabbitmq-server.service
systemctl start rabbitmq-server.service
systemctl status rabbitmq-server.service
}
Increase the default disk space limit (Learn more):
rabbitmqctl set_disk_free_limit 5GB
Create a user, virtual host, and assign permissions:
{
rabbitmqctl add_user "altcraft" "abcdefghijklmnopqrstuvwxyzABCDEF"
rabbitmqctl set_user_tags "altcraft" administrator
rabbitmqctl add_vhost "altcraft"
rabbitmqctl set_permissions -p "altcraft" "altcraft" ".*" ".*" ".*"
}
Update the connection parameters in the configuration file main.json:
{
"RABBITMQ_HOST": "127.0.0.1",
"RABBITMQ_VHOST": "altcraft",
"RABBITMQ_USER": "altcraft",
"RABBITMQ_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF"
}
Installing Kvrocks
Kvrocks is an alternative to Redis, built on RocksDB. Unlike Redis, it stores data on disk, making it suitable for handling large volumes of data. In Altcraft, starting from version v2025.2.72, Kvrocks is used for deduplication in mailings. Install the dependencies for the build:
{
apt update
apt install -y git build-essential cmake libtool python3
}
Go to the project's releases page on GitHub, download the latest version, and extract the archive:
{
wget https://github.com/apache/kvrocks/archive/refs/tags/v2.12.1.tar.gz
tar xzf v2.12.1.tar.gz
}
Build and install:
{
cd kvrocks-2.12.1
./x.py build -DPORTABLE=1 -DCMAKE_BUILD_TYPE=Release -j $(nproc)
mv build/kvrocks /usr/local/bin/
}
Create the user and directories:
{
groupadd kvrocks
useradd -r -g kvrocks -s /bin/false kvrocks
mkdir -p /var/{lib,log}/kvrocks /etc/kvrocks
chown -R kvrocks:kvrocks /var/{lib,log}/kvrocks
}
Create the configuration file /etc/kvrocks/kvrocks.conf:
# kvrocks.conf
bind 0.0.0.0
port 6666
db-name altcraft.db
dir /var/lib/kvrocks
log-dir /var/log/kvrocks
log-retention-days 7
backup-dir /var/lib/kvrocks/backup
requirepass abcdefghijklmnopqrstuvwxyzABCDEF
supervised systemd
workers 8
Create a systemd service file named kvrocks.service in the /etc/systemd/system directory:
[Unit]
Description=kvrocks SSD key-value database
Documentation=https://github.com/apache/kvrocks
Wants=network-online.target
After=network-online.target
[Service]
User=kvrocks
Group=kvrocks
Type=notify
ExecStart=/usr/local/bin/kvrocks -c /etc/kvrocks/kvrocks.conf
WorkingDirectory=/var/lib/kvrocks
Restart=on-failure
ExecStop=/bin/kill -s TERM $MAINPID
RestartSec=10s
LimitNOFILE=100000
LimitNPROC=4096
TimeoutSec=300
NoNewPrivileges=yes
[Install]
WantedBy=multi-user.target
Alias=kvrocks.service
Enable the service to start automatically and launch it:
{
systemctl enable kvrocks.service
systemctl start kvrocks.service
systemctl status kvrocks.service
}
Update the connection parameters in the configuration file main.json:
{
"CAMP_DUPLICATESDB": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
},
"PROCWORKFLOW_DISTRIBUTED_CACHE_DB": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
}
}
Platform Launch
Before launching the platform, make sure you have completed the main.json configuration file. A description of all parameters is available on the Configuration File page. Example:
{
"BASEDIR": "/opt/akd",
"MONGO_AUTH_DB": "admin",
"CONTROLDB_IP": "127.0.0.1",
"CONTROLDB_PORT": 27017,
"CONTROLDB_NAME": "control",
"CONTROLDB_USER": "altcraft",
"CONTROLDB_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"FILEDB_ENABLE": true,
"FILEDB_IP": "127.0.0.1",
"FILEDB_PORT": 27017,
"FILEDB_USER": "altcraft",
"FILEDB_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"FILEDB_NAME": "filedb",
"DEFAULT_LOG_LEVEL": "INFO",
"PRIVATE_KEY": "abcdefghijklmnopqrstuvwxyzABCDEF",
"PRODUCT_NAME": "Altcraft Platform",
"SYSTEM_REDIS": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
},
"CAMP_DUPLICATESDB": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
},
"PROCWORKFLOW_DISTRIBUTED_CACHE_DB": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
},
"LOYALTY_CACHE": {
"MODE": "standalone",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"NODES": [
{
"HOST": "127.0.0.1",
"PORT": 6666
}
]
},
"CLICKHOUSE_SYSTEM": {
"HOST": "127.0.0.1",
"PORT": 9000,
"USER": "altcraft",
"DATABASE_NAME": "altcraft_system",
"PASSWORD": "abcdefghijklmnopqrstuvwxyzABCDEF",
"IS_DEBUG": false
},
"SSDB_HBSUPP_IP": "127.0.0.1",
"SSDB_HBSUPP_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"SSDB_HBSUPP_PORT": 4420,
"SSDB_NOTIFY_IP": "127.0.0.1",
"SSDB_NOTIFY_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"SSDB_NOTIFY_PORT": 4430,
"RABBITMQ_HOST": "127.0.0.1",
"RABBITMQ_VHOST": "altcraft",
"RABBITMQ_USER": "altcraft",
"RABBITMQ_PASS": "abcdefghijklmnopqrstuvwxyzABCDEF",
"WEBAPI_PRIVATE_KEY": "abcdefghijklmnopqrstuvwxyzABCDEF",
"WEBCONTROL_HOSTNAME": "altcraft.domain.com",
"WEBCONTROL_PUBLIC_IP": "192.168.0.1",
"WEBCONTROL_PUBLIC_PORT": 80,
"TRACKING_CRYPT_KEY": "abcdefghijklmnopqrstuvwxyzABCDEF",
"TRACKING_HOSTNAME": "click.domain.com",
"TRACKING_PREFIX": "click",
"TRACKING_PUBLIC_IP": "192.168.0.2",
"TRACKING_PUBLIC_PORT": 80,
"COOKIESAVER_PUBLIC_HOSTNAME": "pxl.domain.com",
"COOKIESAVER_PUBLIC_IP": "192.168.0.3",
"COOKIESAVER_PUBLIC_PORT": 80,
"COOKIESAVER_SSL_ON": false
}
To manage platform services, use the akd executable. Command reference:
Usage:
akd [flags]
akd [command]
Available Commands:
list List platform information
start Start platform services
stop Stop platform services
restart Restart platform services
reload-nginx Reload nginx configuration
help Help about any command
completion Generate the autocompletion script for the specified shell
Flags:
--appname show application full name
--config string config path (default "/opt/akd/config/main.json")
--debug debug mode (for development purposes)
-h, --help help for akd
-v, --version version for akd
Use "akd [command] --help" for more information about a command.
his completes the installation. The platform is ready to launch and further configuration. To continue setup, follow the guide on the [Getting Started](/admin-guide/how-to-begin) page.