PHP and Composer in container stages
Run PHP 8.5, Composer, mago, MySQL-compatible MariaDB and Redis in a container stage. Private GitLab and Packagist packages install.
A project that builds with PHP needs more than the default stage image gives it. This page shows a recipe for PHP 8.5, Composer, the mago linter, a database and Redis in a stage. It also shows how Composer reaches its packages.
The recipe has three parts. A Dockerfile fragment installs PHP. An environment tool set provisions mago. A setup script starts the database and Redis. Your repo keeps its own composer.json and composer.lock.
Status. Option A built and went
readyon one device, IAP EC2, on 2026-10-23, about 2 minutes after the layer save. The hosts werepackages.sury.org:443/connectandgetcomposer.org:443/connect, approved for build only. A stage on that image ran PHP 8.5.11 and Composer 2.9.5.magois now declared in the environment tool set rather than installed by the setup script. The historical proof below predates this provisioning change. SmartFlow EC2 is not part of this proof. Options B and C are not proven. A build rule never opens a host to a stage. A writable stage runs in strict mode and refuses the host: on IAP EC2, bothpackages.sury.organdgetcomposer.orgreturned403 not_allowlisted. A read-only stage keepsEGRESS_MODE, which is open by default, so it can reach any public host. See Isolating agents on a device. Read the build log and fix any package name that moved.
How Composer reaches its packages
A stage never points Composer at a cache or at a mirror. Composer keeps the real addresses, so composer.lock is correct on every machine.
| Source | What happens |
|---|---|
Packagist metadata, repo.packagist.org |
The stage proxy answers and serves it from the device download cache. |
| Packagist archives | Packagist lists a GitHub zipball for most packages. The proxy serves a commit zipball from the cache. Every other api.github.com request stays refused. |
| Private GitLab Composer registry on gitlab.com | CodeHerder relays GET and HEAD reads and adds a read-only token. The token never enters the stage. |
packagist.org |
The strict list of allowed hosts includes it, so composer audit works. The cache does not store it. |
Keep the GitLab registry in composer.json as you wrote it:
{
"repositories": [
{ "type": "composer", "url": "https://gitlab.com/api/v4/group/<group-id>/-/packages/composer/" }
]
}
The <group-id> is the numeric group id. A group path such as acme/tools is refused.
Private GitHub packages. The zipball cache cannot read a package from a private GitHub repo, because the stage token is stripped. Composer then falls back to a source clone. That clone works only for a repo listed on the task. Any other private GitHub package fails to install.
Do not commit a gitlab-token or an http-basic entry for it. The relay adds the credential. The setup for the token is the same as for npm. See GitLab package registry.
If the cache is down, the proxy fetches Packagist metadata from the real host. It fetches a zipball from codeload.github.com, the host that the GitHub API redirects to. The stage never reaches api.github.com itself.
Choose how PHP gets into the stage
The image build reaches only the Debian snapshot. PHP 8.5 comes from packages.sury.org, which is not in the snapshot. Each option below needs a different set of approved hosts. Only option A is proven, on one device. Options B and C are not proven.
| Option | Build hosts to approve | Notes |
|---|---|---|
| A. Fragment with PHP and Composer | packages.sury.org:443/connect and the Composer download hosts |
One image holds everything. Needs the most approvals. |
| B. Fragment with PHP only | packages.sury.org:443/connect |
Declare Composer as an environment system package and mago as an environment tool. |
C. Your own image FROM php:8.5-cli |
None | Cannot combine with system packages. |
Debian packages in a fragment resolve from the snapshot. The environment keeps the snapshot sources in place through the fragment (image template 3). You can also move them out of the fragment with ch env system add ca-certificates curl git unzip mariadb-server redis-server.
The fragment rules refuse FROM, ADD, COPY --from and a heredoc (stageenv.RefusedInstruction). See Giving stages the tools they need.
Approve the build hosts
A build that needs a host fails and files a request. The task blocker names the host. Approve exactly the targets that the denial names. They can differ from the list below. Approve them in one batch, because each approval rebuilds the image.
ch egress rules create packages.sury.org:443 --purpose build --yes
ch egress list --purpose build --status pending
ch egress approve <requestId> --scope workspace
See When a build needs another host. A rule applies to one workspace only. It does not pass down from a group.
Option A: the fragment with PHP and Composer
Set it with ch env system dockerfile --from-file php.Dockerfile. The build hosts are:
| Host | Why |
|---|---|
packages.sury.org:443/connect |
The keyring and the PHP packages. Always needed. |
getcomposer.org:443/connect |
The Composer download. This is the host of the proven run. |
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl git unzip \
&& curl -fsSLo /tmp/sury-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
&& dpkg -i /tmp/sury-keyring.deb \
&& rm /tmp/sury-keyring.deb \
&& echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ trixie main" > /etc/apt/sources.list.d/php.list \
&& apt-get update \
&& apt-get install -y --no-install-recommends php8.5-cli php8.5-bcmath php8.5-curl php8.5-gd php8.5-intl php8.5-mbstring php8.5-mysql php8.5-redis php8.5-xml php8.5-zip mariadb-server redis-server \
&& rm -rf /var/lib/apt/lists/*
RUN curl -fsSLo /usr/local/bin/composer https://getcomposer.org/download/2.9.5/composer.phar \
&& echo "c86ce603fe836bf0861a38c93ac566c8f1e69ac44b2445d9b7a6a17ea2e9972a /usr/local/bin/composer" | sha256sum -c - \
&& chmod 0755 /usr/local/bin/composer
In this option the setup script installs mago only. Drop the Composer lines from the script, and keep the mago block.
Option B: the fragment with PHP only
Use this option when you want one build host. The fragment installs PHP from sury and nothing from GitHub. Only packages.sury.org:443/connect needs approval.
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl git unzip \
&& curl -fsSLo /tmp/sury-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
&& dpkg -i /tmp/sury-keyring.deb \
&& rm /tmp/sury-keyring.deb \
&& echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ trixie main" > /etc/apt/sources.list.d/php.list \
&& apt-get update \
&& apt-get install -y --no-install-recommends php8.5-cli php8.5-bcmath php8.5-curl php8.5-gd php8.5-intl php8.5-mbstring php8.5-mysql php8.5-redis php8.5-xml php8.5-zip mariadb-server redis-server \
&& rm -rf /var/lib/apt/lists/*
For option B, add Composer to the environment with ch env system add composer. Its version comes from the pinned Debian snapshot. Use option A when you need its explicit Composer 2.9.5 pin. Declare mago in the environment tool set as shown below.
Option C: your own image
Build an image FROM php:8.5-cli and run the stage in it. The image build is yours, so the stage environment needs no build host. See Running a stage in your own container image. A stage with its own image cannot also set system packages, so add MariaDB and Redis to your image. This option is also not proven.
Reproducibility
Debian packages stay pinned to the snapshot. packages.sury.org is not pinned, so a rebuild can pick a newer PHP 8.5 patch. To pin one, name the version in the install line, as php8.5-cli=<version>. Read the exact version with apt-cache policy php8.5-cli in a built stage. Keep the sha256 beside every download.
Notes:
- The default image is Debian trixie. Its own PHP is 8.4, so the fragment adds the
packages.sury.orgrepository for PHP 8.5. - The suite name is fixed to
trixie. The fragment does not readlsb_release. - Change the extension list to what your
composer.jsonrequires. Runcomposer check-platform-reqsin a stage to see what is missing. PHP 8.5 always includes OPcache. - Composer is the release
composer.phar, with its sha256 pinned. Change both the version and the sha256 together.
MariaDB or MySQL
The recipe uses MariaDB from Debian. It needs no extra repository, and its packages are signed by Debian. It serves PHPUnit suites that use the common MySQL feature set.
A suite that needs a MySQL-only feature, such as the utf8mb4_0900_ai_ci collation, needs real MySQL. Add the MySQL APT repository from repo.mysql.com to the fragment and install mysql-server. Then change the mariadbd commands below to mysqld.
The setup script
Set it as environment.before_stage. It runs as the stage container’s entrypoint, so the services it starts stay up for the agent. It runs as the stage user, not as root. Tools must already be provisioned by the environment. See the setup script.
D=/tmp/ch-php-services
mkdir -p "$D/mysql" "$D/redis"
# Database and Redis, in user space. Nothing needs system root.
# mariadb-install-db makes a database root user. Connect as it with -u root.
mariadb-install-db --no-defaults --datadir="$D/mysql" --auth-root-authentication-method=normal --skip-test-db >"$D/install.log" 2>&1
nohup mariadbd --no-defaults --datadir="$D/mysql" --socket="$D/mysql.sock" --pid-file="$D/mysql.pid" --bind-address=127.0.0.1 --port=3306 >"$D/mysqld.log" 2>&1 &
nohup redis-server --bind 127.0.0.1 --port 6379 --dir "$D/redis" --save "" --appendonly no >"$D/redis.log" 2>&1 &
for _ in $(seq 1 60); do
mariadb-admin --no-defaults --socket="$D/mysql.sock" ping >/dev/null 2>&1 && redis-cli ping >/dev/null 2>&1 && break
sleep 1
done
mariadb --no-defaults -u root --socket="$D/mysql.sock" -e "CREATE DATABASE IF NOT EXISTS app; CREATE USER IF NOT EXISTS 'app'@'127.0.0.1' IDENTIFIED BY 'app'; GRANT ALL ON *.* TO 'app'@'127.0.0.1';"
Point your tests at 127.0.0.1:3306 with user app and password app, and at Redis on 127.0.0.1:6379. A setup step that fails does not stop the stage, so read the session.setup_script event if a service is missing.
Declare the tools in the environment
A human workspace admin pins mago once, using the version the project requires:
ch env tools add carthage-software/mago 1.30.0
ch env lock
ch env status
Wait for resolution and the device install to be ready before starting a stage. The environment lock records the download URL and checksum; the device provisions the tool on PATH. Do not download or install tool binaries in before_stage. Composer comes from option A’s environment image, option B’s environment system package, or option C’s custom image. See Giving stages the tools they need.
This environment-based mago recipe replaces the older setup-script download. The registry entry exists, but this revised recipe has not yet been verified in a live PHP stage.
Run the project
composer install
mago lint
vendor/bin/phpunit
After composer install, check that composer.lock names repo.packagist.org, api.github.com and gitlab.com, and no egress host. The device refuses to push a composer.lock that names the sandbox cache. See A push that names the cache is refused.
Trust and environment keys
PHP and Composer read SSL_CERT_FILE. The stage sets it to a bundle that holds the system roots and every run CA. Do not set it yourself. CodeHerder refuses COMPOSER_CAFILE, COMPOSER_CAPATH and COMPOSER_HOME as variables. COMPOSER_HOME can hold a global config that names a repository.
Related pages
Last updated