Run P4 Code Review using a Docker container

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.

• A running P4 Server instance.

  For more information about the P4 Server, see P4 Server Administration Documentation.

P4 Code Review images

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

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.

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

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

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

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

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

  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 P4 Code Review to a Docker container

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

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.

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