Helix Core is now P4 and Helix Swarm is now P4 Code Review. Product user interfaces will be updated soon. Learn more >>

Documentation | 2025.5

# Run P4 Code Review 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 Docker.

This section details how to use a Docker container to run P4 Code Review either in a test environment or a production environment.

- Prerequisites

- P4 Code Review images

- Running the Docker container

- Persisting Docker containers for a production environment

- Restarting the Docker container

- Migrating P4 Code Review 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 P4 Code Review in a production environment:

1. Start P4 Code Review using a Docker container with the .env configuration file and a mounted P4 Code Review 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 P4 Code Review or data directory without the .env configuration options. The stored configurations in the config.php file are used.

## Prerequisites

To run P4 Code Review using a Docker container, you must have the following:

- An environment capable of running Docker images. For more information about Docker images, see Docker.

- 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 Docker. By default, the PHP memory limit of the Docker container is set to 2 gigabytes (GB).

- Access to a running P4 Server instance. For more information about the P4 Server, see P4 Server Administration Documentation.

- You must be a super user if you are configuring P4 Code Review for the first time. If you are re-using an existing config.php file, this is not necessary.

- The P4 Code Review Docker container can run on any host operating system that supports Docker, with official support for RHEL and Ubuntu hosts. The P4 Code Review container is built and delivered with Ubuntu 22.04 (Jammy) as its base image.

## P4 Code Review images

To access the P4 Code Review images on Docker Hub, see Helix Swarm Docker Container.

There is a tag for each major version of P4 Code Review, for example, 2022.2. These images are updated for every patch release.

The latest tag points to the very latest released version of P4 Code Review. The major version number of P4 Code Review used by the latest tag will change when new major versions are released, this includes the patches for the latest version.

## Running the Docker container

This section details how you can configure a fresh installation of P4 Code Review against a P4 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.

When running Swarm in a Docker container for production systems, your configuration must persist data when it is shutdown.

### Create a configuration file

In this section, we create an example .env configuration file which is then used to configure a Docker container.

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

- P4D_PORT

  The P4D_PORT value must be set to the P4 Server instance.

  Ensure that the Docker image is able to communicate with the P4 Server instance.

- P4D_SUPER and P4D_SUPER_PASSWD

  The P4D_SUPER user must be an existing P4 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 P4 Server password.

  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.

- SWARM_HOST

  The hostname set by SWARM_HOST should be reachable by the P4 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 P4 Code Review.

  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 P4 Code ReviewP4 Serverextension configuration is overwritten.

### Start a single Docker container

Running the following command will start a single instance of P4 Code Review running that uses the .env configuration file. It assumes that there is a Redis server and P4 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 P4 Code Review 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 P4 Code Review instance as follows:

    docker stop helix-swarm

You can delete the P4 Code Review 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 P4 Code Review. This makes the Redis server private to P4 Code Review.

The Redis configurables in the .env file created in the Create a configuration file section is used in the example code below. 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 P4 Code Review 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 P4 Code Review 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.

P4 Code Review 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

When you restart a Docker container, the /opt/perforce/swarm/data/config.php file is used to configure the system.

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, P4 Code Review 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.

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 P4 Code Review installation. The Docker directory includes the Apache site configuration files, P4 Code Review configuration files, P4 Code Review 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. 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.

  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.

To enable HTTPS, you must setup a new Apache Virtual Host.

## Migrating P4 Code Review to a Docker container

When migrating a P4 Code Review 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 P4 Code Review installation uses the default Redis server, then you must configure a new Redis instance for the dockerised P4 Code Review. To configure a new Redis instance, see Create a configuration file.

You can migrate an existing P4 Code Review 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 Redis connection configuration is defined correctly in the config.php file. Below is an example of the Redis connection configuration.

       <?php
           // this block should be a peer of 'p4'
           'redis' => array(
               'options' => array(
                   'password' => null, // Defaults to null
                   'namespace' => 'Swarm',
                   'server' => array(
                       'host' => 'localhost', // Defaults to 'localhost' or enter your Redis server hostname
                       'port' => '7379', // Defaults to '7379' or enter your Redis server port
                   ),
               ),
           ),

   You can configure additional Redis parameters such as items_batch_size, check_integrity and population_lock_timeout. See Redis server.

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

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 P4 Code Review 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 P4 Server (P4D).
SWARM_USER | swarm | Name of the P4 Code Review user.
SWARM_PASSWD | no default | Password of the P4 Code Review user.
SWARM_MAILHOST | localhost | Mail server address
SWARM_HOST | helix-swarm | Hostname of the P4 Code Review server.
SWARM_FORCE_EXT | n | To overwrite P4 Code Review 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 P4 Code Review setup is complete, you can edit the config.php file to include support for Email configuration, JIRA integration, and for Multiple P4 (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 P4 Code Review.

- 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 P4 tickets unless they are host unlocked. Generally, the Apache server forwards the IP address of the client to P4 Code Review. This allows a ticket that is obtained on a client machine to work with P4 Code Review, even though P4 Code Review is on a different machine.

If P4 Code Review 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`. 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 P4 Code Review 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

Your search for returned results