Containers: Docker and Podman #

This page is for hosting companies and platform teams that run Exponential sites in Linux containers with Docker or Podman. It answers what the project's sources say about containers, what must live on a persistent volume, how many containers may write a SQLite database, how an entry point installs a site once and keeps the server running, and how to keep secrets out of images.

Contents #

1. What the sources say
2. Images
3. Volumes: what must persist
4. The database and the one-writer rule
5. An entry point that installs once
6. Secrets
7. Operations inside containers
8. Checklist

What the sources say #

• Docker and Podman (Linux containers) are tier 2, known to work: "Velocity publishes images on ghcr.io/se7enxweb/exponential-velocity for amd64 and arm64, one per PHP version and variant" (Tier 2).
• "Any image with PHP 8 and the extensions above runs Exponential ... Keep var/ (storage, logs, the SQLite database) and settings/override on a persistent volume. With SQLite, run one container that writes" (Containers, cloud and hosting panels).
• exp:install is the method for "CI pipeline, container image, automated test environment": options or environment variables, exit status (4.6 Unattended installs).

Images #

Two routes:

Velocity's images are tagged by release, PHP version and variant (Velocity packages, Docker images and binaries):

ghcr.io/se7enxweb/exponential-velocity:<release>-php<version>-<variant>   fixed
ghcr.io/se7enxweb/exponential-velocity:php<version>-<variant>             moves with each release
ghcr.io/se7enxweb/exponential-velocity:latest                             newest PHP, standard variant

<version> is 8.2, 8.3, 8.4 or 8.5; <variant> is mini, lite, standard or full. "Pin a fixed tag in production." The standard variant is "the default; what the documentation assumes".

Volumes: what must persist #

The backup set is the same as everywhere: the database and var/storage, settings/override and settings/siteaccess (Backup and restore).

The database and the one-writer rule #

In the official order: 1. SQLite 3 (the default) · 2. PostgreSQL · 3. MongoDB · 4. MariaDB · 5. Oracle · 6. MySQL. Microsoft SQL Server is known to be possible with additional work at this time.

• 1. SQLite 3 works in a container when one container writes the database: "SQLite's WAL needs shared memory on one host, so several replicas cannot share one database file over a network volume."
• Several containers serving one site need a database server ("PostgreSQL first") and shared storage for var/storage (Containers, cloud and hosting panels). They also need sessions every container can read; see Kubernetes.
• The database server usually runs in its own container or as a managed service of your platform, with its own volume and its own backups (Database backups per engine).

An entry point that installs once #

Chapter 4 gives "a minimal container entry point" that installs once, then starts Velocity and stays in the foreground while it runs:

#!/usr/bin/env bash
set -euo pipefail
cd /srv/exponential
if ! grep -q '^\[DatabaseSettings\]' settings/override/site.ini.append.php 2>/dev/null; then
    php bin/php/console exp:install --apply \
        --db=mysql --db-host="${DB_HOST}" --db-name="${DB_NAME}" --db-user="${DB_USER}" \
        --url="${SITE_URL}" --email="${ADMIN_EMAIL}" --password="${ADMIN_PASSWORD}"
fi
php bin/php/console exp:velocity start
# exp:velocity start runs the server in the background and returns; status exits 0 while it runs
while php bin/php/console exp:velocity status >/dev/null 2>&1; do sleep 30; done
echo "Velocity stopped" >&2
exit 1

What the chapter explains about it:

• The grep "is the same test exp:install itself uses to decide that a directory already holds an installation".
• "exp:velocity start detaches the server and returns as soon as it answers", so the loop keeps the container's main process alive and ends it when the server stops, "so the container runtime can restart it".
• "If the entry point runs as root, add --allow-root-user to the two exp:velocity commands."
• The example uses --db=mysql; the other values are sqlite (the default), pgsql, mongodb, mariadb and oracle (Database support, At a glance).

Secrets #

• Pass the database password in EXP_INSTALL_DB_PASSWORD; exp:install reads it "when --db-password is not given; that keeps it out of the process list and the shell history".
• Without --password, exp:install generates a 24-character administrator password and writes it to var/log/initial-admin-password (mode 0600); read it from there and rotate it, or pass one from your secret store (First sign-in and default passwords).
• Never bake settings/override into an image: it holds the database credentials (13.3 Secrets in settings/override).
• config.php can be made in the image (exp:setup:config --apply --allow-root-user --owner=www-data:www-data in the build step), but a password in it, such as CLUSTER_STORAGE_PASS, is set at start from the environment: php bin/php/console exp:config:set CLUSTER_STORAGE_PASS --value="$CLUSTER_DB_PASS" --apply --allow-root-user. The output shows it as ********. In CI, exp:config:list --only-set --format=json shows what an image or a running container sets (Setting up .htaccess and config.php from the console).

Operations inside containers #

• Cron. runcronjobs.php still has to run on a schedule: from a scheduler container that shares the volumes and the database, or from your platform's scheduler, as the same user as the web process (Cron jobs).
• Logs. Exponential writes its logs under var/log (and per site under var/<site>/log); keep them on the volume or collect them from there (Request logs).
• Code changes reach Velocity's workers only after a restart; exp:velocity deploy runs the steps in order (8.3.14). In containers the usual equivalent is a new image and a new container.

Checklist #

• To do: Image with PHP 8.0+ and every required extension; exp:velocity ext check passes in the pipeline.
• To do: Fixed image tags in production.
• To do: var/, settings/override, settings/siteaccess on persistent volumes, owned by the container's PHP user.
• To do: One writing container for SQLite, or a database server for more.
• To do: Entry point with the "already installed" test; secrets from the environment, not the image.
• To do: Cron, logs and backups defined.

A public demo in a container. Give the demo service EXP_DEMO_MODE=1 (-e, --env-file or env_file:; docker-demo.env), never a base image other sites use. With PHP-FPM inside, keep clear_env = no or set env[EXP_DEMO_MODE] = 1 in the pool. Demo mode for hosts.

Related pages #

• Kubernetes, Platform as a service
• exp:install, Automating provisioning
• Installing in one command
• Setting up .htaccess and config.php from the console
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.