For customers who prefer to use Docker Compose rather than the standard Docker Image install, Sandfly supports generating Docker Compose files as an alternative installation option.

Docker Compose is a tool for defining and running multi-container Docker applications. It simplifies the process of managing the entire Sandfly application stack (PostgreSQL, Sandfly Server, Sandfly Nodes) by using a single, declarative YAML configuration file.

Podman is not supported with this Compose-based installation method. If Podman must be used, use the Docker Image installation process instead.

Complete Prerequisites

Ensure that the installation prerequisites (Install Container Tool and Download Setup Archive) are completed before following the steps on this page.

Install Compose Version 2

For deployments using Docker Compose, first ensure that there is a supported Compose package installed and that it is version 2. The docker-compose command (with the hyphen) is version 1, which is at its End-Of-Life (EOL) and not officially supported with this installation method.

Command to check for a supported version:

docker compose version

The next action depends on the output:

Docker Compose version 2.x.x - Proceed to the next step.
Any form of command error message. In this case, a version 2 Compose package needs to be installed that is compatible with the Docker version on the Sandfly hosts. Package names vary depending on the configured package repository (e.g., official Docker repo vs. OS default). Check vendor documentation for the appropriate package names and install the latest supported version. Once installed, run the command again to verify the version. Common command error messages include:
- docker: unknown command: docker compose
- exec: "docker-compose": executable file not found in $PATH

Run the Generate Compose Script

The generate compose script will create a set of YAML files that can then be used to start/stop the Sandfly services using the standard Docker Compose commands.

It is recommended to run the setup on the system where the Sandfly server will be running in order to correctly define the startup parameters for the PostgreSQL database.

Go to the setup directory:

cd ~/sandfly-setup/setup

Run the generate compose script. If you run it without any arguments, you will be prompted for the information required for the Sandfly setup. Alternatively, you can supply the information as arguments to the script.

./generate_compose.sh

Usage:
  generate_compose.sh [options]

Options:
  -admin-password <password>    Admin user initial password
  -hostname <hostname>          Hostname or IP Address used to access the server UI
  -tls-mode <mode>              TLS Certificate mode: self_signed | acme | user_managed | none
  -acme-email <email-address>   Email address for the ACME directory service account
  -acme-directory <URL>         Specific ACME directory service URL

Loading the Docker Image

To begin, the install script will automatically load the containers, downloading them if they are not available in the local archive included with the setup package.

Installing Sandfly server version 5.7.0.

Copyright (c) Sandfly Security Ltd.

Welcome to the Sandfly 5.7.0 server setup. This script will generate
Docker Compose files for deploying Sandfly.

** Loading images from local archive:
** ../../docker_images/sandfly-docker-images-5.7.0.tgz
** There will be a slight delay before further output...
Loaded image: postgres:14.21
Loaded image: postgres:18.2
Loaded image: quay.io/sandfly/sandfly:5.7.0
Sandfly Setup Helper
Copyright (c) Sandfly Security Ltd.
Sandfly version: 5.7.0

Server Hostname

Enter the IP address or hostname of the system hosting the server and database.

If this host is not resolvable by DNS, enter the external interface IP address. Otherwise, enter the server's DNS resolvable, fully qualified domain name.

❗️
IMPORTANT: Do Not Use Localhost (127.0.0.1) as the Server Address
Do not enter localhost (127.0.0.1), or any other loopback interface, for the server address as the application will not work. It must be a valid, external interface such as an ethernet IP address or fully qualified domain name the system uses for connectivity.

Example:

****************************************************************************
*                             Server Hostname                              *
****************************************************************************

Please enter the fully qualified domain name (FQDN) or the IP address
of the Sandfly server. It is important that the address supplied is
reachable by your web browser and the scanning nodes.

If you choose to use a Let's Encrypt HTTPS certificate on the Sandfly
server, this is the address that the certificate request will use, so
it must match the internet-accessible FQDN of the server.

Do NOT use localhost (127.0.0.1) as the address; the address must be
one that is reachable from the scanning nodes and from users' web
browsers to access the Sandfly UI.

--> Enter server hostname (e.g. sandfly.example.com): myhost.mycompany.com

Alternatively, enter an externally reachable IP address if DNS is not available for this host:

 ...

--> Enter server hostname (e.g. sandfly.example.com): 198.51.100.100

TLS (HTTPS Certificate) Mode

This installation script will prompt you to select how to generate the TLS certificate for the Sandfly server. The default option is to automatically generate a self-signed certificate.

The second option is to use Let's Encrypt (or another ACME certificate service) to request a signed certificate. To use Let's Encrypt, the Sandfly server must be accessible from the internet on port 443, and the hostname from the previous step must be the internet-facing FQDN of the server.

The third mode is to provide your own TLS certificates that are mounted into the Docker container. Choose "user_managed" mode and then place your certificates in the setup_data/server_ssl_cert folder. See Installing a Custom SSL Certificate for more information.

The last option is to disable TLS on the server, but only use this option if an external load balancer or ingress controller terminates the TLS connection.

 ...

****************************************************************************
*                       TLS (HTTPS Certificate) Mode                       *
****************************************************************************

Select the TLS mode for the Sandfly server:

  1) self_signed    - Auto-generate a self-signed certificate
                      (default)
  2) acme           - Use Let's Encrypt to request a signed
                      certificate
  3) user_managed   - Provide your own certificate files
                      (mount into the container)
  4) none           - Disable TLS on the server (use when an
                      external load balancer or ingress
                      controller terminates TLS)

Choice [1]: 1

Option 2: ACME Certificate Service

If you choose option 2, acme (Let's Encrypt), some additional details are required.

❗️
IMPORTANT: Port 443 Must Be Visible from the Internet During Signing!
Make sure the server has a legitimate hostname that is reachable from the internet and resolves correctly. Port 443 will need to be open for the Let's Encrypt server to validate the host.

Ensure that the hostname is publicly resolvable and port 443 can be reached from the internet. The ACME service will not sign any certificates for servers that are not reachable on the internet.

 ...

Choice [1]: 2

Let's Encrypt requires an email address. By configuring Sandfly to
use Let's Encrypt to generate a server certificate and providing an
email address, you are indicating acceptance of the current Let's
Encrypt terms of service. For more information, see
https://letsencrypt.org/

--> Enter Let's Encrypt contact email:

Enter the Let's Encrypt contact email. We recommend entering a valid email in case there is a security alert regarding the certificates.

When starting the server, the scripts prioritize signed versions over unsigned ones.

If the process is successful, the browser will not display warnings about invalid certificates when connecting to the UI.

If an internal server is used to host Sandfly, this method may not be possible. The server certificate would then need to be signed in another way. If you choose to use a self-signed certificate, accept the warning in the browser and then skip this step.

Admin Password

You may set an initial password for the admin user account. Alternatively, to have Sandfly automatically generate the admin password, press <Enter> at the prompt.

 ...

****************************************************************************
*                              Admin Password                              *
****************************************************************************

Please set an initial password for the "admin" user account.

Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password: 
--> Confirm admin password:

If you generate a random password, record the new password, as it will not be displayed again. You must then enter the password to confirm and continue the setup.

 ...

****************************************************************************
*                              Admin Password                              *
****************************************************************************

Please set an initial password for the "admin" user account.

Passwords must be at least 12 characters long.
To generate a random password, leave blank and press enter.
--> Enter admin password:

**********************************************************************
*** MAKE NOTE OF YOUR NEW PASSWORD. IT WILL NOT BE DISPLAYED AGAIN ***
coveted-retrain-clapping-dastardly-flaring-uselessly-mulch
**********************************************************************

--> Enter generated password to confirm:

Setup Complete

When the install script finishes, the following output will be displayed:

 ...

Docker Compose files generated:
  /home/sandfly/sandfly-setup/setup/setup_data/docker-compose.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/docker-compose-server_only.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/docker-compose-node_only.yaml
  /home/sandfly/sandfly-setup/setup/setup_data/config.postgres.env
  /home/sandfly/sandfly-setup/setup/setup_data/config.server.env
  /home/sandfly/sandfly-setup/setup/setup_data/config.node.env


Docker Compose and environment files generated in
  /home/sandfly/dev/sandfly-source/_dist/sandfly-setup/setup/setup_data

To start Sandfly, navigate to the directory ./setup_data

To run both the Sandfly server and nodes on this system, use the default
'docker-compose.yaml' file:
  cd ./setup_data
  docker compose up -d

To run just the Sandfly server on this system, use the server only
'docker-compose-server_only.yaml' file:
  cd ./setup_data
  docker compose -f docker-compose-server_only.yaml up -d

To run the Sandfly nodes on a different system, copy the node only
'docker-compose-node_only.yaml' file and the 'config.node.env' file
to the target system and use the command:
  docker compose -f docker-compose-node_only.yaml up -d

For more information see the documentation at the following URL:
  https://docs.sandflysecurity.com/

Start the Containers

There are two options for running the Sandfly containers. To run under the Standard Security mode with both the server and nodes on the same system, use the default docker-compose.yaml file. To run under the Maximum Security mode with the nodes separate system(s), use the docker-compose-server_only.yaml and docker-compose-node_only.yaml files.

For more information on the security modes, see the Standard Security vs Maximum Security Install documentation.

Standard Security Mode

To run under the Standard Security mode, use the default docker-compose.yaml file. This will start the PostgreSQL database server, the Sandfly server, and the Sandfly nodes. By default, the Docker Compose file will run 2 Sandfly node containers. To change the number of nodes, edit the docker-compose.yaml file, find the sandfly-node section and change replicas: 2 to the desired number.

cd ~/sandfly-setup/setup/setup_data/
docker compose up -d

Maximum Security Mode

To run under the Maximum Security mode, use the docker-compose-server_only.yaml file on the server. This will start the PostgreSQL database and the Sandfly server.

Start the Server

cd ~/sandfly-setup/setup/setup_data/
docker compose -f docker-compose-server_only.yaml up -d

Prepare the Node(s)

To run the Sandfly nodes on separate host(s) from the server, perform these additional steps:

Complete the same installation prerequisites on each node host.
By default, the node-only Docker Compose file will run 2 Sandfly node containers per system. To change the number of nodes, edit the docker-compose-node_only.yaml file and change replicas: 2 to the desired number of nodes. If available resources differ between multiple hosts, this value can be adjusted individually as needed.
Copy the following files from the server's sandfly-setup/setup_data directory to the same directory on all of the node hosts:
1. config.node.env - Defines the configuration options and keys for Sandfly nodes.
2. docker-compose-node_only.yaml - The Docker Compose file for Sandfly nodes.
Delete config.node.env from the server, preferably with the shred -u command; this ensures full security of the SSH credentials within Sandfly. Do not delete this file if using the Standard Security mode.

🚧
CAUTION: Confirm That a Valid Key Is on a Node
Before deleting the SSH key on the server, ensure that there is a valid copy of it on at least one of the nodes. Once the key is deleted, it cannot be regenerated or restored. Sandfly would need to be reinstalled to generate another working key pair.

Start the Node(s)

cd sandfly-setup/setup/setup_data/
docker compose -f docker-compose-node_only.yaml up -d