Run Swarm using a Docker container

This section details how to use a Docker container to run Helix Swarm either in a test environment or a production environment.

• Prerequisites

• Helix Swarm images

• Running the Docker container

• Persisting Docker containers for a production environment

• Restarting the Docker container

• Migrating Swarm to a Docker container

• Advanced configuration options

• Example of running Swarm using docker-compose

Here is an overview of setting up a Docker container to run Helix Swarm in a production environment:

1. 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.

2. Stop the Docker container.

3. 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.

Prerequisites

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

You can access the Helix Swarm images on Docker Hub here:

https://hub.docker.com/r/perforce/helix-swarm

The following Helix Swarm images are available on the Docker Hub:

• perforce/helix-swarm:latest

• perforce/helix-swarm:2022.2

Helix Swarm image source

You can access the source code for all Helix Swarm images here:

https://github.com/perforce/helix-swarm-docker

Running the Docker container

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

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

• P4D_PORT

  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.

• SWARM_HOST

  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.

  • To run Swarm on a different port than port 80, you must add the port number to the SWARM_HOST parameter.

• 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.

• SWARM_FORCE_EXT

  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:

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

Restarting the Docker container

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

Docker directory

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.

For example,

• /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

  The entire /opt/perforce/etc/swarm-cron-hosts.conf file is soft linked to the docker/swarm-cron-hosts.conf file.

Migrating Swarm to a Docker container

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:

1. Create a ./storage directory.

2. Copy contents of the /opt/perforce/swarm/data/ directory to ./storage/swarm-data directory.

3. Ensure that the network connections configuration are defined correctly in the config.php file.

4. 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

  perforce-swarm-site.conf

• List of cron worker configuration

  swarm-cron-hosts.conf

• Directory which contains any custom configurations for Swarm

  custom

Advanced configuration options

To modify the configuration of the Helix Swarm docker image, you can edit the following parameters in the .env configuration file:

Configuration	Default	Description
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.

Apache proxy

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 DocumentRoot.

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