Container images #

This page is for bundlers who publish Exponential as a container image. The Exponential repository contains no Dockerfile or compose file; the guidance below is generic and built on what the documentation states. Velocity, the web server that is part of Exponential, does publish images you can build on.

Contents #

1. What the sources say
2. Choosing a base
3. Image or volume
4. An entry point
5. Secrets and the database
6. Image checklist

What the sources say #

• "Docker and Podman (Linux containers) are tier 2, known to work" (Operating system support).
• "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" (4.5).

Choosing a base #

Source: Containers: Docker and Podman. Whichever base, run php bin/php/console exp:velocity ext check inside the built image in your pipeline.

A generic build, in words rather than a Dockerfile:

1. Start from the pinned base.
2. Copy your bundle's composer.json and composer.lock; run composer install --no-dev --no-interaction as the user the site will run as.
3. Add your site package files and import them, or plan to import at first start (Offline bundles).
4. Regenerate autoloads (Caches and autoloads after building).
5. Set ownership of the writable directories (File permissions).
6. Add the entry point below; do not run the installer during the build.

Steps 4 and 5 are also the place for .htaccess (when the image runs Apache) and config.php. The commands ask nothing, end with PASS: or FAIL: and change nothing on a second run; a build step usually runs as root, so give --allow-root-user and the site's user:

php bin/php/console exp:setup:htaccess --apply --allow-root-user --owner=www-data:www-data
php bin/php/console exp:setup:config --apply --allow-root-user --owner=www-data:www-data
php bin/php/console exp:config:set EZP_INI_FILEMTIME_CHECK false --apply --allow-root-user

Never bake a password into config.php in the image. Set such values at start, in the entry point, from the container's environment:

php bin/php/console exp:config:set CLUSTER_STORAGE_HOST "$CLUSTER_DB_HOST" --apply --allow-root-user
php bin/php/console exp:config:set CLUSTER_STORAGE_PASS --value="$CLUSTER_DB_PASS" --apply --allow-root-user

(Setting up .htaccess and config.php from the console).

Image or volume #

"Never bake settings/override into an image: it holds the database credentials" (Containers). Decide the user ID once for the image and the volume, and keep it.

An entry point #

The documented minimal entry point "installs once, then starts the server and stays in the foreground while it runs" (4.6):

#!/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

• Pass EXP_INSTALL_DB_PASSWORD in the container's environment.
• "If the entry point runs as root, add --allow-root-user to the two exp:velocity commands."
• Change --db to the database of your bundle (sqlite is the default, pgsql the recommended server).
• Without --password, a 24-character password is generated and written to var/log/initial-admin-password; tell the recipient how to read it once.

Secrets and the database #

• SQLite: one writing container per database file; "SQLite's WAL needs shared memory on one host".
• Several replicas: a database server ("PostgreSQL first"), shared storage for var/storage, and sessions every container can read (Kubernetes).
• Cron still has to run: a scheduler container sharing the volumes, as the same user (Containers).

Image checklist #

• To do: Base image pinned by tag or digest; Composer from the lock file; --no-dev.
• To do: exp:velocity ext check passes in the image.
• To do: No settings/override, settings/siteaccess, kickstart.ini, logs or caches from the build in the image.
• To do: config.php in the image holds no secret (set at start with exp:config:set); exp:config:list --only-set --format=json checked in CI.
• To do: Volumes documented: var/, settings/override, settings/siteaccess.
• To do: The entry point installs once and keeps the main process alive.
• To do: The source of every GPL component is offered (GPL obligations).
• To do: Labels or notes name the Exponential version and your bundle version.

Related pages #

• Containers: Docker and Podman
• First boot and install once
• Velocity in a bundle
• 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.