Welcome to the Perforce Software Swarm Docker environment. This environment is built for public use and is for customers that want to test Swarm in a pre-setup environment.
This Docker environment is built using Helix Swarm 2021.2, Docker 20.10.5, and docker-compose 1.28.4. It is recommended that at least these versions of the tools are used.
This is a TECHNICAL PREVIEW and not tested for production use. It's purpose is to gain feedback from our customers so that we can determine the use cases to which it would be put, and tweak the configuration in order to improve its usability.
This does mean that there is a chance the configuration will change dramatically over the next few releases, and we do not guarantee backwards compatibility.
There are two use cases that are supported, starting up Swarm against a clean P4D system (one which has not had Swarm configured against it), and starting Swarm using an existing configuration. These are described below.
Note that the provided Makefile is for use on Linux, and may work on Mac. These images have not been tested on Windows.
Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. If you want to find out more about what these containers are, try the documentation at docker.com:
https://www.docker.com/resources/what-container
- Internet access
- Docker-compose
By default, the following port must be free to enable connection to the containers from the outside world or local machine.
- 80 (Swarm HTTP)
These can be changed if you don't want to use these default ports. By default, Swarm is not configured to use HTTPS.
These containers are setup to be used with Docker Compose, however it should be possible to run them without the use of Docker Compose. In this first technical preview this hasn't been tested.
Based on a Ubuntu 20.04 container, sets up the Perforce package repository and installs the Helix command line client. Used as a base by helix-swarm.
Contains the Swarm and Apache server, can be configured to talk to an existing P4D instance.
It exposes port 80 by default for access externally. If you want to use HTTPS, then manual configuration of the container is required.
Based on the standard redis container, used by helix.swarm by default as the local redis cache. Note that this version of redis uses the standard default port of 6379, whereas the one shipped with Swarm uses a default port of 7379. This means we need to specify the port on the command line when the server starts.
Since Docker containers can be temporary, both the Swarm and Redis containers
store their data outside of the containers on the local file system in the
storage directory.
The simplest configuration is to run up a new Swarm against an existing P4D server. If Swarm has been used against this P4D (Helix Server) in the past, then some parts of the configuration may need to be manually done.
We recommend a Unicode enabled P4D for use with Swarm. If P4D is running on Microsoft Windows, then you will also need to configure the triggers.
First configure the .env file to be suitable for your environment. Setup the following variables:
| Config | Default | Description |
|---|---|---|
| P4D_SUPER | super | Name of the super user |
| P4D_SUPER_PASSWD | HelixDockerBay94 | Super user password |
| P4D_PORT | ssl:perforce:1666 | Port for the P4D server |
| SWARM_USER | swarm | Name of the swarm user |
| SWARM_PASSWD | HelixDockerBay94 | Swarm user password |
| SWARM_MAILHOST | localhost | Mail server address |
| SWARM_HOST | helix.swarm | Hostname of Swarm server |
| PUBLIC_HTTP | 80 | Port Swarm is exposed on |
| SWARM_FORCE_EXT | n | Set to 'y' to overwrite extensions |
| SWARM_VER | latest | Only 'latest' supported |
Once these have been set, then the Docker containers can be built and started with the following commands:
docker-compose build
docker-compose up -d
Or alternatively, you can use the Makefile to do the same:
make clean build up
This will clean down the system, build the base Docker images, then
bring them up. You can then use make log to see how the configuration
is progressing.
If there is an existing config.php file in the data directory, then
configuration will be skipped, and we assume that Swarm is already
configured.
The following steps are followed when Swarm is configured:
- Check for a running P4D server against {P4D_PORT}.
- Check that we can log into it with {P4D_SUPER} and {P4D_SUPER_PASSWD}.
- Check to see that there is a {SWARM_USER}. If there is, we don't create one, otherwise we will create one with the given {SWARM_PASSWD}
Once the Swarm container is up and running, and Swarm is working, the
only entry in the .env file that is still needed is PUBLIC_HTTP. At the
very least, you may want to remove the passwords from this file.
If the P4D server is a Linux server, and there are no Swarm triggers and no Swarm extensions are configured on it, then Swarm extensions will be automatically installed.
Server side extensions are a new feature of P4D which are more efficient than triggers, and don't require an external language environment such as Perl. They are not currently supported on Windows versions of P4D.
If the SWARM_FORCE_EXT environment variable is set to "y", then any existing Swarm extensions will be removed, and new ones always installed.
You can stop and start the container with:
docker-compose stop
docker-compose up -d
Alternatively, using the included Makefile:
make stop
make up
You can also gain access to a running Swarm container with make bash
Since the container will not perform any reconfiguration if the config.php file already exists, if a new container is started after the previous has been stopped or even deleted then it will simply pick up the previous configuration and continue from where it left off.
The exception is that if there is a perforce-swarm-site.conf in the external data/etc directory, then this will be copied into place for use by the running Apache server if it isn't there already.
If you already have a Swarm installation, then you may want to just move it into Docker. We don't recommend this for production servers at the moment (by this, we mean that we haven't yet performed extensive testing of Swarm in Docker, and we don't have built in support for HTTPS).
- Copy the contents of the
datadirectory into theswarm-datadirectory. - Start the docker containers
Swarm will automatically pick up the config.php and use it 'as is'. No
changes will be made to it. This may mean that you need to configure the Redis
configuration if you want to use the Dockerised Redis server. In which case
point the Swarm redis configuration at helix.redis:
'redis' => [
'options' => [
'server' => [
'host' => 'helix.redis',
],
],
],
You may also need to change the host name in the env file.
If you have triggers already installed on your P4D, then you will need to make sure that they are configured to point at the new Swarm location.
As above, if there is a perforce-swarm-site.conf file in the data/etc directory, then this will be copied and used by Apache. Otherwise a new Apache config will be created using the SWARM_HOST from the env file.
@copyright 2021 Perforce Software. All rights reserved.
@license Please see LICENSE in top-level folder of this distribution.