Skip to main content

Deploying Salt.Box Server

Prepare​

  1. Clone the salt-box-compose project into your working directory:

    git clone https://dev.saltbox.pro/salt.box/salt-box-compose.git

  2. Change the current working directory:

    cd ./salt-box-compose/

  3. Initially some secrets need to be created in the ./secrets/ subdirectory.
    This may be done with helper script:

    python3 ./bin/make_secrets.py

  4. Make a copy of example.env file named .env in the project root.
    Tune it before run building.

    Below is a description of some variables in the .env file that the user may need to redefine to ensure that Salt.Box works correctly in his network environment.

    1. If you plan to deploy Salt.Box server on a virtual machine or on a host other than localhost, then the .env file must override variables whose default value is 'localhost':

      The host system port that will be mapped to the port of the Docker container serving the Salt.Box web interface, for example:

      WEB_SERVER_PORT=80

      The WEB_SERVER_OUTER_SOCKET variable must be assigned the network address or hostname of the host on which the Salt.Box web interface will be accessible to the user. Optionally, the port number can also be specified:

      WEB_SERVER_OUTER_SOCKET=<HOST> | <HOST>:<PORT>

      If Salt.Box is accessed without a reverse proxy, then WEB_SERVER_OUTER_SOCKET must be set to the same port as WEB_SERVER_PORT. If the port is not explicitly specified, the default value for the protocol will be used (80/TCP for HTTP, 443/TCP for HTTPS).

    2. Redis server socket (for connecting the master to it).
      To connect external masters, specify 0.0.0.0:6379 (all network interfaces) or specify the address of one of the network interfaces:

      REDIS_SALT_EXPOSE_SOCKET=<IP_ADDRESS>:6379

    3. Switching the Salt.Box web interface to use the SSL protocol.
      SSL encapsulation is performed by an external web server (reverse proxy server).

      WEB_SERVER_SCHEME=https
      WEB_SERVER_WS_SCHEME=wss

      To connect to the web interface from an external host without using SSL, you must specify exceptions for unsafe sources in the browser you are using.
      Below is an example of the required setting for Chrome/Chromium browsers:

      • Go to chrome://flags/#unsafely-treat-insecure-origin-as-secure
      • Enable the option "Insecure origins treated as secure"
      • In the input field, enter the URL with the web interface address: http://<IP_ADDRESS>
      • Restart the browser

    4. Tags of images from which Salt.Box is deployed:

      CORE_AUTOTESTS_TAG=<vX.Y.Z>
      CORE_IMAGE_TAG=<vX.Y.Z>
      FRONTEND_IMAGE_TAG=<vX.Y.Z>
      KEYCLOAK_IMAGE_TAG=<vX.Y.Z>
      NGINX_IMAGE_TAG=<vX.Y.Z>
      OPA_IMAGE_TAG=<vX.Y.Z>
      REDIS_IMAGE_TAG=<vX.Y.Z>
      SALT_MASTER_IMAGE_TAG=<vX.Y.Z>
      SSHFS_IMAGE_TAG=<vX.Y.Z>

      whewe <vX.Y.Z> is the version number of Salt.Box

    5. Container shutdown waiting time before forced shutdown:

      STOP_GRACE_PERIOD=5s

      Decreasing this value may speed up the shutdown, but increases the risk of losing temporary data.

    6. Logging level of the SaltStack master's container:

      SALT_MASTER_LOG_LEVEL='warning'
      SALT_MINION_LOG_LEVEL='warning'

      Logging level designations:

      LevelNumeric valueDescription
      critical50Critical errors
      error40Errors
      warning30Warnings
      info20Normal log information
      debug10Information useful for debugging both salt implementations and salt code
      all0Everything
      caution

      Any log level below "info" is NOT SECURE and may log sensitive data.
      For more information on log levels, see the SaltStack project documentation.

    7. Paths to directories in the file system of the Docker host where client configurations will be stored.
      Directories can be moved, for example, to a mounted storage:

      SSHFS_STORAGE_PATH='./_sshfs-storage/'

      SSHFS storage is intended for storing templates and some other types of files used in the operation of Salt.Box.

Use helper script to start​

Easy way to run the system is execute:

sudo ./bin/update_and_run.sh

Helper script:

  • merges example.env and override.env (if exists) into .env config.
  • makes secrets
  • updates images
  • runs the Salt.Box instance

Use override.env to redefine example.env default values.
Use -h or --help flag to look script options.

Another way is to go step-by-step.

Run step-by-step​

  1. While in the ./salt-box-compose/ directory, start the build process:

    sudo docker compose up --build -d
    caution

    Check there are no warnings on non-set variables to avoid confusing errors.

  2. To update outer images:

    sudo docker compose pull

    then restart e.g. with:

    sudo docker compose down && sudo docker compose up -d

    It is possible to pull images on start with an additional flag --pull=always:

    sudo docker compose up --build --pull=always

    For production use following commands are recommended:

    sudo sh -c "echo 'vm.overcommit_memory=1' > /etc/sysctl.d/salt-box.conf"
    sudo sysctl -p /etc/sysctl.d/salt-box.conf

    vm.overcommit_memory=1 is a Redis requirement.

Docker objects that are being created during installation​

Once the build process has completed successfully, a number of Docker objects are created, as shown in the tables 1, 2, 3.

Table 1. Downloaded Docker images
Docker ImageSizeDescription
saltbox-proxy208 MBNginx reverse proxy
saltbox-make-redis-salt-certs109 MBCertificate issue service for Redis auth.
registry.saltbox.pro/saltbox/saltbox-compose/keycloak-init820 MB
registry.saltbox.pro/saltbox/saltbox-compose/keycloak808 MBKeyCloak IdAM server
registry.saltbox.pro/saltbox/saltbox-compose/sshfs357 MBMountable SSHFS file system
registry.saltbox.pro/saltbox/saltbox-compose/opa84 MBOpen Policy Agent
registry.saltbox.pro/saltbox/saltbox-compose/redis61 MBRedis server
registry.saltbox.pro/saltbox/saltbox-core488 MBServer components (core) of the Salt.Box
registry.saltbox.pro/saltbox/saltbox-bridge/salt-master336 MBСервер SaltStack (Salt Master)
registry.saltbox.pro/saltbox/saltbox-frontend215 MBUser interface of the Salt.Box
postgres394 MBPostgreSQL DBMS
mongo1.1 GBMongoDB DBMS
rabbitmq389 MBRabbitMQ message broker
Table 2. Docker containers created during installation
Docker ContainerStateDescription
saltbox-mongo-1UpMongoDB DBMS.
It is used by the Salt.Box backend.
The DB stores entities such as clients, collections, etc.
saltbox-sshfs-1UpSSH server.
It is used to mount the sshfs file systems on minions
saltbox-opa-1UpOpen Policy Agent.
OPA is used to create access policies for the components of the web application
saltbox-keycloak-db-1UpKeyCloak service.
It provides centralized authentication in the Salt.Box web interface
saltbox-saltbox-frontend-1UpSalt.Box user interface (frontend)
saltbox-make-redis-salt-certs-1ExitedA module that issues certificates for Redis Certificate Based Authentication
saltbox-saltbox-core-tasks-watcher-1UpA module waiting for tasks to appear on the SaltStack exchange bus
saltbox-saltbox-core-taskiq-scheduler-1UpModule responsible for working with a distributed asynchronous task queue
saltbox-saltbox-core-taskiq-worker-1UpTaskiq worker process.
It is responsible for receiving, sending, and executing tasks from the queue
saltbox-rabbitmq-1UpRabbitMQ service.
It is a message broker.
It is responsible for collecting data from multiple sources and sending it to services of the Salt.Box system for further processing
saltbox-redis-taskiq-1UpRedis server used as a message broker and a result store for Taskiq
saltbox-saltbox-core-faststream-redis-1UpRedis server used as a message broker for Faststream
saltbox-redis-salt-1UpRedis server.
It works with key-value data structures.
It is used to store the results of SaltStack-related processes
saltbox-keycloak-1UpKeyCloak service.
IdAM subsystem of Salt.Box
saltbox-saltbox-core-1UpMain server component of Salt.Box (backend)
saltbox-salt-master-1UpSaltStack Master server, used to control minions
saltbox-keycloak-init-1Exited
saltbox-proxy-1UpNginx reverse proxy.
Redirects client requests to internal services in containers

Container statuses specified in the table 2:
Up — Container is running
Exited — Container was successfully started and then stopped normally until needed


Table 3. Docker volumes created during installation
Docker VolumeInitial sizeDescription
<256-битное имя в 16-ричной записи>< 1 MBRabbitMQ service data
(Container in-use: saltbox-rabbitmq-1)
saltbox_saltbox_core_var< 1 MBGPG keys
(Containers in-use:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1)
saltbox_keycloak-db_data67 MBKeyCloak service data
(Container in-use: saltbox-keycloak-db-1)
saltbox_salt_master_pki< 1 MBKeystore of the salt-master service
(Container in-use: saltbox-salt-master-1)
saltbox_redis_taskiq_data< 1 MBTaskiq service data
(Container in-use: saltbox-redis-taskiq-1)
saltbox_mongo_config< 1 MBMongoDB configuration data
(Container in-use: saltbox-mongo-1)
saltbox_mongo_data311 MBMongoDB data
(Container in-use: saltbox-mongo-1)
saltbox_redis_salt_data< 1 MBRedis server data
(Container in-use: saltbox-redis-salt-1)
saltbox_redis_salt_certs< 1 MBRedis server certificate store
(Containers in-use:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1,
saltbox-redis-salt-1,
saltbox-make-redis-salt-certs-1,
saltbox-salt-master-1)
saltbox_salt_master_saltbox_var< 1 MB(Container in-use: saltbox-salt-master-1)
saltbox_salt_repos< 1 MBJSON schemas for various SaltStack functions
(Containers in-use:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1,
saltbox-sshfs-1)

Images​

Below is an example of the output of the docker image ls command.

REPOSITORY                                                     TAG            IMAGE ID       CREATED        SIZE
registry.saltbox.pro/salt.box/salt-box-bridge/salt-master      master         6e6a65ae6d5c   14 hours ago   305MB
registry.saltbox.pro/salt.box/salt-box-core                    master         dc990973edb6   15 hours ago   486MB
registry.saltbox.pro/salt.box/salt-box-frontend                master         cb046f5104d3   22 hours ago   215MB
salt-box-proxy                                                 latest         0a7a69e50215   9 days ago     208MB
registry.saltbox.pro/salt.box/salt-box-compose/keycloak-init   master         c3ad347807b2   11 days ago    819MB
registry.saltbox.pro/salt.box/salt-box-compose/keycloak        master         cce07c6262d2   11 days ago    808MB
registry.saltbox.pro/salt.box/salt-box-compose/sshfs           master         6d4bced308df   11 days ago    218MB
registry.saltbox.pro/salt.box/salt-box-compose/opa             master         9f4e528e02fb   11 days ago    82.6MB
registry.saltbox.pro/salt.box/salt-box-compose/redis           master         2cb6940da7ee   11 days ago    60.7MB
mongo                                                          7              8c30f14b362a   2 weeks ago    1.1GB
postgres                                                       16-alpine      3b057e1c2c6d   6 weeks ago    394MB
salt-box-make-redis-salt-certs                                 latest         f82ed3daf965   6 weeks ago    109MB
rabbitmq                                                       3-management   49895caee5d3   6 months ago   389MB

Volumes​

Below is an example of the output of the docker volume ls command.

DRIVER    VOLUME NAME
local     f85f6baa5742b4b1bf7b3b7ca86929361c529aee6e06bff9b1a5208d76469345
local     salt-box_keycloak-db_data
local     salt-box_mongo_config
local     salt-box_mongo_data
local     salt-box_redis_salt_certs
local     salt-box_redis_salt_data
local     salt-box_redis_taskiq_data
local     salt-box_salt_box_core_var
local     salt-box_salt_master_pki

Containers​

Below is an example of the output of the docker compose ls -a command.

NAME                STATUS                   CONFIG FILES
salt-box            exited(2), running(16)   root/salt-box-compose/compose.yaml

Below is an example of the output of the docker container ls -a command.

CONTAINER ID   IMAGE                                                                 COMMAND                  CREATED          STATUS                      PORTS                                                                  NAMES
88dc531cc401   salt-box-proxy                                                        "/docker/entrypoint.…"   22 minutes ago   Up 21 minutes               0.0.0.0:80->80/tcp                                                     salt-box-proxy-1
9027787dcf67   registry.saltbox.pro/salt.box/salt-box-core:master                    "entrypoint.sh salt-…"   22 minutes ago   Up 22 minutes               8000/tcp                                                               salt-box-salt-box-core-faststream-redis-1
372acea8af4a   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/uvic…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-1
04ccd3ce9c7c   registry.saltbox.pro/salt.box/salt-box-bridge/salt-master:master      "/usr/local/bin/entr…"   22 minutes ago   Up 22 minutes               0.0.0.0:4505-4506->4505-4506/tcp, 8000/tcp                             salt-box-salt-master-1
a864aec0556a   registry.saltbox.pro/salt.box/salt-box-core:master                    "entrypoint.sh salt-…"   22 minutes ago   Up 22 minutes               8000/tcp                                                               salt-box-salt-box-core-tasks-watcher-1
8ed8856d31c1   registry.saltbox.pro/salt.box/salt-box-compose/keycloak-init:master   "/usr/local/bin/crea…"   22 minutes ago   Exited (0) 21 minutes ago                                                                          salt-box-keycloak-init-1
332bc7787b30   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/task…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-taskiq-scheduler-1
140c425ca829   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/task…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-taskiq-worker-1
f8b895c79ec2   registry.saltbox.pro/salt.box/salt-box-compose/redis:master           "entrypoint.sh '--sa…"   22 minutes ago   Up 22 minutes (healthy)     127.0.0.1:6379->6379/tcp                                               salt-box-redis-salt-1
05bb59635b38   registry.saltbox.pro/salt.box/salt-box-compose/keycloak:master        "/usr/local/bin/star…"   22 minutes ago   Up 21 minutes (healthy)     8080/tcp                                                               salt-box-keycloak-1
b68811fa1e30   postgres:16-alpine                                                    "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes (healthy)     5432/tcp                                                               salt-box-keycloak-db-1
e7091bac8749   rabbitmq:3-management                                                 "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes (healthy)     4369/tcp, 5671-5672/tcp, 15671-15672/tcp, 15691-15692/tcp, 25672/tcp   salt-box-rabbitmq-1
6673e7cb5a06   mongo:7                                                               "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes               127.0.0.1:27017->27017/tcp                                             salt-box-mongo-1
8cd31f8c27ad   salt-box-make-redis-salt-certs                                        "entrypoint.sh /root…"   22 minutes ago   Exited (0) 22 minutes ago                                                                          salt-box-make-redis-salt-certs-1
b1ba6ea04662   registry.saltbox.pro/salt.box/salt-box-compose/redis:master           "entrypoint.sh '--sa…"   22 minutes ago   Up 22 minutes               6379/tcp                                                               salt-box-redis-taskiq-1
77199f687853   registry.saltbox.pro/salt.box/salt-box-frontend:master                "/docker/entrypoint.…"   22 minutes ago   Up 22 minutes               80/tcp                                                                 salt-box-salt-box-frontend-1
c727e1df0c0b   registry.saltbox.pro/salt.box/salt-box-compose/sshfs:master           "/usr/local/bin/sshd…"   22 minutes ago   Up 22 minutes               0.0.0.0:1022->1022/tcp                                                 salt-box-sshfs-1
53f1daabbebd   registry.saltbox.pro/salt.box/salt-box-compose/opa:master             "/opa run --server -…"   22 minutes ago   Up 22 minutes               0.0.0.0:8181->8181/tcp                                                 salt-box-opa-1

Dev mode​

info

The information provided in this section is intended for software developers and is not important for standard deployment of the Salt.Box server.

Synopsis​

Dev mode allows to build images instead of pulling pre-built ones, and also adds a few useful overrides.

Look at Dev options section of your example.env file copy.
To enable dev options uncomment required COMPOSE_FILE= lines.
Then run compose as usual.

Use --watch flag or toggle watch with w in attached mode to rebuld dev-services on changes.

caution

Do not use development mode on production environments because it may change the data.

Build images in dev mode​

To build clean images use command with enabled COMPOSE_FILE overrides:

sudo docker compose build --no-cache

--no-cache guarantees build with latest dependencies.

Connect to redis-salt instance​

Dev mode allows to connect to the Redis instance by URL rediss://localhost:6379 (SIC!).
Since TLS is enabled client may skip a certificate validation (option like --insecure) or use a CA certificate.
The last may be obtained with command:

sudo docker compose exec redis-salt cat /etc/redis/certs/ca.crt

Dev minions​

Dev mode provides amount of impersistent minions in replica mode.
Look for options in the example.env file.

Dev minions do not keep their keys between restarts so keys will be dropped on the master.
Some operations may result in the loss of minions.
In that case try the following command, which should reconnect minions:

sudo docker compose restart salt-master
info

docker compose up --force-recreate salt-master command does not regenerate minions.

Cleanup​

Cleanup data​

After changes made, created containers and volumes may become incompatible with current code without special migrations.
To fix startup problems on developement environment stop containters with Control-c and make them down:

sudo docker compose -f compose.yaml -f compose-dev-override.yaml down --volumes
info

The --volumes flag will purge attached volumes and result in data loss.
Make sure not to lose production data.

Cleanup stale Docker stuff​

When code and configs change, new layers and other objects are created. To free up resources, run the following command from time to time:

sudo docker system prune --force

This is usually safe and only removes outdated data.

Software development agreements​

Redis: channels​

Hash name should be in form of OBJ_TYPE:{ID}:DATA_TYPE e.g. minion:{MID}:grains.
Use the singular form for the OBJ_TYPE and the plural form for the DATA_TYPE because there are multiple values ​​for an object.

Keycloak​

Keycloak for admin user (password in file ./secrets/keycloak_admin_password): http://localhost/auth/keycloak/