Run Swarm using a Docker container
This section assumes that you have basic knowledge of how to use a Docker container. There are numerous ways of configuring a Docker environment, and the examples outlined in this section are only to get you started. For more information on all of the options for Docker configurations, see https://www.docker.com/.
You must be a super user if you are configuring Helix Swarm for the first time. If you are re-using an existing config.php file, this is not necessary.
You need access to the internet to download the docker image. You can download an image and transfer it to a machine with no internet access. To do this, use the docker save and docker load commands. For more information on how to use these commands, see https://www.docker.com/.
This section details how to use a Docker container to run Helix Swarm either in a test environment or a production environment.
Here is an overview of setting up a Docker container to run Helix Swarm in a production environment:
Start Helix Swarm using a Docker container with the .env configuration file and a mounted Swarm or data directory.
This stores all the .env configuration options into the data directory in the correct format.
Stop the Docker container.
Start a Docker container using the mounted Swarm or data directory without the .env configuration options. The stored configurations in the config.php file are used.
To run Helix Swarm using a Docker container, you must have the following:
An environment capable of running Docker images.
For more information about Docker images, see https://www.docker.com.
A running Helix Core Server instance.
For more information about the Helix Core Server, see https://www.perforce.com/manuals/p4sag/Content/P4SAG/Home-p4sag.html.
Helix Swarm images
There is a tag for each major version of Helix Swarm, for example, 2022.2. These images are updated for every patch release.
The latest tag points to the very latest released version of Helix Swarm. The major version number of Helix Swarm used by the latest tag will change when new major versions are released, this includes the patches for the latest version.
You can access the Helix Swarm images on Docker Hub here:
The following Helix Swarm images are available on the Docker Hub:
Helix Swarm image source
You can access the source code for all Helix Swarm images here:
Running the Docker container
When running Swarm in a Docker container for production systems, your configuration must persist data when it is shutdown. For more information about persisting data and configuration in a production environment, see Persisting Docker containers for a production environment.
This section details how you can configure a fresh installation of Helix Swarm against a Helix Core Server to get a test instance running. It does not specify how to persist data on an external volume, so should not be used for a production environment. For more information about persisting data and configuration in a production environment, see Persisting Docker containers for a production environment.
Create a configuration file
In this section, we create an example .env configuration file which is then used to configure a Docker container.
The P4D_SUPER_PASSWD and SWARM_PASSWD configurables in the .env configuration file must be a password, not ticket. The SWARM_PASSWD is converted into a host locked ticket before it is stored.
If the /opt/perforce/swarm/data directory is mapped outside the Docker container, after the initial configuration run, you can remove the configuration options from the .env configuration file as they are stored in config.php file.
Create a .env configuration file in the current directory as follows:
P4D_PORT=ssl:myperforce:1666 P4D_SUPER=super P4D_SUPER_PASSWD=HelixDockerBay94 SWARM_USER=swarm SWARM_PASSWD=HelixDockerBay94 SWARM_HOST=mymachine SWARM_REDIS=helix-redis SWARM_REDIS_PORT=7379 # If set to 'y', then extensions will be installed even if they already # exist, overwriting existing configuration. SWARM_FORCE_EXT=y
The P4D_PORT value must be set to the Helix Core Server instance.Important
Ensure that the Docker image is able to communicate with the Helix Core Server instance.
P4D_SUPER and P4D_SUPER_PASSWD
The P4D_SUPER user must be an existing Helix Core Server user with super privileges. The P4D_SUPER_PASSWD must be a password and cannot be a ticket.
SWARM_USER and SWARM_PASSWD
The SWARM_USER is created if it does not already exist. If it already exists, the SWARM_USER must have at least admin privileges. The SWARM_PASSWD must be set to the existing password if the SWARM_USER already exists or you can use it to set a new password. The SWARM_PASSWD must obey the normal rules for a Helix Core Server password.
The hostname set by SWARM_HOST should be reachable by the Helix Core Server. In this example setup, we assume that the hostname is the name of the host running the Docker image, rather than the Docker image itself. When the Docker image is started, port 80 (and, optionally, port 443) are mapped to the host's port. This way anything that can reach the host can reach Helix Swarm.Note
With this example setup, the IP address or hostname of the actual Docker image does not matter.
SWARM_REDIS and SWARM_REDIS_PORT
This is the hostname and port for the Redis server. This example setup assumes that Redis server is running in a Docker container as setup in Start a single Docker container.
When set to y, SWARM_FORCE_EXT will force the extensions to be installed or reinstalled. The existing SwarmHelix Core Serverextension configuration is overwritten.
Start a single Docker container
Running the following command will start a single instance of Helix Swarm running that uses the .env configuration file. It assumes that there is a Redis server and Helix Core Server to connect to. The Redis configurables in the .env file in Create a configuration file section will not work in this example. You must ensure that Helix Swarm points to an existing Redis instance.
docker run -d --name helix-swarm --network-alias helix-swarm \ --env-file .env -p 80:80 perforce/helix-swarm
You can shut down the Helix Swarm instance as follows:
docker stop helix-swarm
You can delete the Helix Swarm instance as follows:
docker rm helix-swarm
Setup a local private network
A simplified option is to run Redis server as a Docker container. You can setup a local private network to run both, the Redis server and Helix Swarm. This makes the Redis server private to Helix Swarm.
Use the following docker commands to setup a local private network:
The Redis configurables in the .env file created in the Create a configuration file section is used in the example code below:
docker network create helix docker run -d --name helix-redis --network helix --network-alias helix-redis \ redis redis-server --protected-mode no --port 7379 docker run -d --name helix-swarm --network helix --network-alias helix-swarm \ --env-file .env -p 80:80 perforce/helix-swarm
Persisting Docker containers for a production environment
For a production environment, the Helix Swarm and Redis server cache data should persist even after the Docker container has stopped and deleted. You can do this by using bind mount or volume mount when starting the Docker containers.This mounts the contents of /opt/perforce/swarm/data directory outside the Docker container.
To preserve the Helix Swarm configuration and Redis server cache data outside the Docker container, use the following:
docker network create helix mkdir -p storage/redis-data docker run -d --name helix-redis --network helix --network-alias helix-redis \ -v $PWD/storage/redis-data:/data redis \ redis-server --protected-mode no --port 7379 --appendonly yes mkdir -p storage/swarm-data docker run -d --name helix-swarm --network helix --network-alias helix-swarm \ -p 80:80 -v $PWD/storage/swarm-data:/opt/perforce/swarm/data \ --env-file .env perforce/helix-swarm
The --appendonly yes option for the Redis server will cause it to write its cache data to disc. The /data directory can then be mounted externally to persist it beyond the lifetime of the Docker container.
Helix Swarm log files, the worker queue, tokens, and workspaces are also preserved because they are part of the /opt/perforce/swarm/data directory.
Restarting the Docker container
If there is no config.php file in the /opt/perforce/swarm/data/ directory, the .env configuration file is used.
When you make any changes to the config.php file , you must reload the configuration cache for Swarm to use the updated configurations. If you restart a Docker container, Helix Swarm will not use the updated configuration until the configuration cache has been reloaded. For more information on how to restart configuration cache, see Reload Configuration button section.
Once you have restarted the Docker container, you must be a root user to access files in the /opt/perforce/swarm/data/ directory.
When you restart a Docker container, the /opt/perforce/swarm/data/config.php file is used to configure the system. You can restart the Docker container as follows:
docker run -d --name helix-swarm --network helix --network-alias helix-swarm \ -p 80:80 -v $PWD/storage/swarm-data:/opt/perforce/swarm/data \ perforce/helix-swarm
When you restart the Docker container, a Docker directory is created /opt/perforce/swarm/data/docker for your Swarm installation. The Docker directory includes the Apache site configuration files, Swarm configuration files, Swarm version file, and the Docker container version. All the files in the Docker directory are linked to the original files in their original locations. This allows you to edit files outside the Docker container. Any change to any file in the Docker directory is preserved between restarts.
/etc/apache2/sites-available -> docker/sites-available
The entire /etc/apache2/sites-available directory is soft linked to the /opt/perforce/swarm/data/docker/sites-available directory.
All the configuration files have a2ensite run against them. This allows you to automatically run multiple Apache site configurations.
/opt/perforce/swarm/public/custom -> docker/custom
The entire /opt/perforce/swarm/public/custom directory is soft linked to the docker/custom directory.
/opt/perforce/etc/swarm-cron-hosts.conf -> docker/swarm-cron-hosts.conf
/opt/perforce/etc/swarm-cron-hosts.conffile is soft linked to the
If a docker/sites-available file exists instead of the directory, then no soft link is created. This allows you to mount the Apache directory outside the Docker container.
To enable HTTPS, you must setup a new Apache Virtual Host.
Migrating Swarm to a Docker container
When migrating a Swarm installation to a Docker installation on the same system, you must do the following:
Use a host unlocked ticket.
- Stop the host cron jobs and use the cron jobs available in the Docker container.
If your Helix Swarm installation uses the default Redis server, then you must configure a new Redis instance for the dockerised Helix Swarm. To configure a new Redis instance, see Create a configuration file.
If your Helix Swarm installation uses a remote Redis server, you can continue using the remote Redis server or you can configure a new Redis instance. The Redis server configurations are stored in the config.php file. To configure a new Redis instance, see Create a configuration file.
You can migrate an existing Swarm server setup into a Docker container. To do this, you must copy the /opt/perforce/swarm/data directory to a location that is accessible for the Docker container as follows:
Create a ./storage directory.
Copy contents of the /opt/perforce/swarm/data/ directory to ./storage/swarm-data directory.
Ensure that the network connections configuration are defined correctly in the config.php file.
Ensure that there is an Apache site configuration file at swarm-data/etc/perforce-swarm-site.conf. This Apache site configuration file is copied into the Docker when it starts.
docker network create helix mkdir -p storage/redis-data docker run -d --name helix-redis --network helix --network-alias helix-redis \ -v $PWD/storage/redis-data:/data redis \ redis-server --protected-mode no --port 7379 --appendonly yes mkdir -p storage/swarm-data docker run -d --name helix-swarm --network helix --network-alias helix-swarm \ -p 80:80 -v $PWD/storage/swarm-data:/opt/perforce/swarm/data \ perforce/helix-swarm
A docker directory is created in the /opt/perforce/swarm/data/ location. During the initial configuration, the docker directory includes the following files:
Apache site configuration file
List of cron worker configuration
Directory which contains any custom configurations for Swarm
Advanced configuration options
When a config.php file exists, all configurations in the .env configuration file are ignored.
When no Apache site configuration file is available, the SWARM_HOST parameter in the .env configuration file is used to configure the Apache server.
We recommend that the /opt/perforce/swarm/data/docker directory is mounted outside the Docker container. So changes to any files in the Docker directory are preserved between restarts.
To modify the configuration of the Helix Swarm docker image, you can edit the following parameters in the .env configuration file:
|P4D_SUPER||super||Name of the super user.|
|P4D_SUPER_PASSWD||no default||Password of the super user.|
|P4D_PORT||ssl:perforce:1666||Port for the Helix Core Server (P4D).|
|SWARM_USER||swarm||Name of the Swarm user.|
|SWARM_PASSWD||no default||Password of the Swarm user.|
|SWARM_MAILHOST||localhost||Mail server address|
|SWARM_HOST||helix-swarm||Hostname of the Swarm server.|
|SWARM_FORCE_EXT||n||To overwrite Swarm Extensions, set SWARM_FORCE_EXT = 'y'.|
|SWARM_REDIS||helix-redis||Hostname of the Redis server.|
|SWARM_REDIS_PORT||7379||Port number of the Redis server.|
|SWARM_REDIS_PASSWD||Password for the Redis server.|
|SWARM_REDIS_NAMESPACE||Namespace for the Redis server.|
After the Swarm setup is complete, you can edit the config.php file to include support for Email configuration, JIRA integration, and for Multiple Helix Core (P4D) instances.
Apache server configuration
By default, the mod_rewrite and mod_ssl modules are enabled for Apache server. The SSL module is required to run HTTPS from within the docker container.
When using SSL, ensure that you have defined a location for the SSL key and the SSL certificate file. Do this in one of the following ways:
Save the SSL key and certificate file in the /opt/perforce/swarm/data/docker directory and add a reference to them in the Apache site configuration file perforce-swarm-site.conf.
Save the SSL key and certificate file in a different location and mount that location externally. This ensures that the private key file is outside Swarm.
Save the SSL key and certificate file externally to the docker container. Use a web server as a proxy for the docker container. Enable the proxy web server to provide any HTTPS functionality.
In cases where the Docker container is behind another web server, you may run into issues with Helix tickets unless they are host unlocked. Generally, the Apache server forwards the IP address of the client to Helix Swarm. This allows a ticket that is obtained on a client machine to work with Helix Swarm, even though Helix Swarm is on a different machine.
If Helix Swarm is behind a web proxy (such as a second Apache server, running SSL), the IP address of the client is lost. In this scenario, host unlocked tickets must be used that can be obtained using
p4 login -ap.
Alternatively, you can use the
remoteip_module to allow the container Apache to trust the proxy that enables forwarding the client IP addresses. To do this, add the following code into the
perforce-swarm-site.conf file, at the same level as the
RemoteIPInternalProxy should be the IP address of the host, as seen by the container.
RemoteIPHeader X-Forwarded-For RemoteIPInternalProxy 172.19.0.1/24
Example of running Swarm using docker-compose
This section details an example usage of the docker-compose command. In the following example:
The docker-compose.yml file is setup in a directory from where the commands are run.
Creates a network for the two containers to run in.
Sets up a Redis container to run Redis in, with external storage in the storage directory.
Sets up a Swarm container with external storage for the data directory and the /var/www directory.
# ========================================================================= # # This compose file runs a migrated Swarm instance. Redis and Swarm are in # # containers, p4d is on the host machine. # # ========================================================================= # version: '2.2' networks: default: driver: bridge ipam: driver: default config: - subnet: 172.19.0.0/16 gateway: 172.19.0.1 name: swarm-net services: helix.swarm: image: perforce/helix-swarm:latest hostname: helix-swarm domainname: helix volumes: - ./storage/swarm-data:/opt/perforce/swarm/data - ./storage/www:/var/www ports: - 127.0.0.1:80:80 working_dir: /opt/perforce/swarm depends_on: - helix.redis tty: false helix.redis: image: "redis" hostname: helix.redis domainname: helix command: redis-server --protected-mode no --port 7379 --appendonly yes volumes: - ./storage/redis-data:/data