The portability component#
The portability component proves your app image runs anywhere a container platform runs it: OpenShift, Coolify, plain Docker, and Citadel too. It builds the image, boots it twice side by side as a stranger (an arbitrary uid with no name, in group 0, with no capabilities), and runs the six checks from ADR-0010 plus the image's own HEALTHCHECK. Like the real pre-flight, it is a list you finish on the ground: if one light is red, nobody taxis.
What it checks#
The strict boot comes first, because every other check stands on it. Then the seven checks, each reported on its own line.
| Check | What it does | What a failure usually means |
|---|---|---|
strict-boot |
Starts the image as uid:0 (default 100123:0) with no /etc/passwd entry and every capability dropped. Fails if the app root is writable by that user, if a writable path is missing or not writable by group 0, if the second replica does not listen on the port its port_env variable names, or if the app wrote anywhere outside writable_paths and runtime_paths while it ran (what a read-only root filesystem would refuse). |
The image expects root, a named user, a fixed port, or writes caches next to the code. |
health |
Asks for health_path with a bare IP address in Host (Host: <ip>:<port>), no forwarded headers, at the job's own address, and expects 200. That is what a platform's probe sends. |
Trusted-host lists, HTTPS redirects, sessions or auth run before the health route. |
env-only |
Fails on a .env file or a Laravel config cache (bootstrap/cache/config.php) baked into the image; the app must boot on the env input alone. |
Config was copied or cached at build time. |
forwarded-headers |
Requests probe_path twice: plain, then with forged X-Forwarded-Host, -Proto, -Port and the identity_header, sent from an untrusted peer. Fails if the status or Location changes or a forged value shows up in the answer. |
The app trusts every proxy, so anyone can set its host, scheme or user. |
logs |
Fails if nothing reached stdout or stderr during the run, or if anything was written under logs_path (default storage/logs). |
Logs go to files that vanish with the container. |
session-hop |
Signs in on replica A with session_login_path, then sends that cookie to replica B's session_check_path and expects 200. The replicas have separate disks. |
Sessions live in local files instead of a shared store or a signed cookie. |
sigterm |
Sends SIGTERM to the main process and expects it to exit by itself within stop_timeout seconds, as PID 1 must. |
The process has no SIGTERM handler (PID 1 ignores the signal by default), or the handler hangs. |
healthcheck |
Runs the image's own HEALTHCHECK command, if it declares one, inside replica A as the app's uid with the same environment, up to three times two seconds apart, and expects exit 0. Fails when the command exits non-zero, or when the image declares no HEALTHCHECK and require_healthcheck is true. |
The image's own health command fails, so Docker and Coolify would mark the container unhealthy. |
The job prints one portability: <check>: problem: ... line per problem as it finds it, then a summary with pass, FAIL or skipped for every check, and passes only when every check that ran passed.
Add the include#
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/portability@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
env: ["APP_KEY=${PORTABILITY_APP_KEY}", "APP_URL=https://myapp.example.edu", "SESSION_DRIVER=cookie", "LOG_CHANNEL=stderr"]
session_login_path: /_portability/login
session_check_path: /_portability/me
With no start_command, the job runs the image's own ENTRYPOINT and CMD, exactly as the platforms do. An Apache image (Squire's portable image, a Sourdough or WELD app) needs no start_command shim for Buildah: the job gives each replica stdio its uid owns and a process group of its own, as a container runtime does (see What the job emulates). Put secrets such as APP_KEY in CI/CD variables and name them in env: $NAME and ${NAME} in env and build_args values are replaced from the job's variables.
A sign-in route for session-hop#
session-hop needs a GET route that signs in a test user and one that answers 200 only when signed in. Enable them with an environment variable that only this job sets, so they never exist in production. In Laravel (and a Sourdough or WELD app):
if (env('PORTABILITY_PROBE') === 'yes') {
Route::middleware('web')->group(function () {
Route::get('/_portability/login', function () {
Auth::login(User::firstOrCreate(['email' => 'portability@example.invalid'], ['name' => 'Portability', 'password' => Str::random(40)]));
return 'signed in';
});
Route::get('/_portability/me', fn () => Auth::check() ? 'ok' : abort(401));
});
}
Add "PORTABILITY_PROBE=yes" to env. An app with no sign-in leaves session-hop out of checks on purpose; the other checks still run.
A shared database for session-hop#
An app that keeps its sessions in a database (WELD does) needs both replicas to reach the same store. The services input starts one as a GitLab service container, which the replicas reach by its alias exactly as the job script does:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/portability@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
services: [{ name: "mysql:8.4.7@sha256:<digest>", alias: db, variables: { MYSQL_ROOT_PASSWORD: "portability", MYSQL_DATABASE: "app" } }]
env: ["APP_KEY=${PORTABILITY_APP_KEY}", "DB_CONNECTION=mysql", "DB_HOST=db", "DB_DATABASE=app", "DB_USERNAME=root", "DB_PASSWORD=portability", "SESSION_DRIVER=database", "LOG_CHANNEL=stderr"]
setup_command: "php artisan migrate --force"
session_login_path: /_portability/login
session_check_path: /_portability/me
Replace <digest> with the digest of the image you actually pull; never copy a placeholder pin into a pipeline. Two things to know about the service:
- A Laravel app needs its
sessionstable before it serves.setup_commandrunsphp artisan migrate --forceonce, in its own container, before either replica starts, the way a release migrates once before the web pods start. Use it instead ofstart_command, which runs in both replicas at once and replaces the image's own entrypoint. - The service may take a few seconds to accept connections. If the first migrate fails with a connection error, wrap it in a short retry, for example
for i in 1 2 3 4 5 6 7 8 9 10; do php artisan migrate --force && exit 0; sleep 3; done; exit 1. - The runner is arm64, so the service image must be multi-arch.
mysql:8.4is;mysql:5.6is not.
How the job works#
The component is one job, named by job_name (default portability). It runs in the Buildah image, pinned by digest, with STORAGE_DRIVER=vfs and BUILDAH_ISOLATION=chroot, interruptible: true and timeout: 30 minutes. In order, it:
- Builds the image with
buildah bud, fromdockerfileincontext, withbuild_args. It builds with--format docker, because Buildah's default OCI format drops the image's HEALTHCHECK and the docker format keeps it. Nothing is pushed: the image stays in the job's own storage. - Reads the image's
ENTRYPOINTandCMD, makes two copies of its filesystem (replicas A and B) and runs the static parts ofstrict-bootandenv-onlyon them. - Runs
setup_commandonce, in a fresh container of the built image, as the same uid with the same env as replica A will get, when it is set. A non-zero exit stops the job before any replica starts. - Starts both replicas with
buildah run --user <uid>:0 --cap-drop=ALLand theenvinput, each through a small launcher that gives it its own stdio and session; B getsport + 1throughport_env. - Waits up to
boot_timeoutseconds for each replica's health path, then runshealth,env-only,forwarded-headers,session-hop,logsandsigtermwith curl, andhealthcheckwith the image's own command. - Stops both replicas and compares what changed on disk against
writable_pathsandruntime_paths.
The probe is templates/portability/probe.sh, inlined in the template byte for byte, because a component ships only its template.yml. The inputs reach it through a quoted heredoc as data; nothing in them is run except start_command.
Why Buildah#
The old runner allowed no Docker-in-Docker, and a privileged runner is a key to the building. Buildah is maintained by Red Hat, builds from a Dockerfile with no daemon, and can also run the image it built, as any uid, with no capabilities, inside an ordinary job. kaniko builds but cannot run a container, and Google archived it in 2025. A GitLab services: entry runs an image but cannot set its uid or drop its capabilities, and needs the image pushed to a registry first. Buildah needs neither a push nor a second job.
What the job emulates#
The checks run in an unprivileged job, so a few things are emulated rather than enforced by a kernel. Each one fails the same apps the real thing would.
- Read-only root. The image is not mounted read-only; the job looks for files written outside the allowed paths after the run. A write is caught, not refused.
- PID 1.
buildah runstarts no PID namespace, so the main process is not PID 1. The job checks that it handles SIGTERM, and fails it when it dies of the signal's default action, which PID 1 would ignore. - No new privileges. Every capability is dropped, but
buildah runhas nono-new-privilegesflag. The uid has no passwd entry, so set-uid tools have little to grab. - Networking. Both replicas share the job's network namespace; the second one listens on
port + 1. - Stdio and process group. On its own,
buildah rundiffers from every container runtime twice. It hands the app stdout and stderr pipes owned by root, so an app running as the uid cannot reopen them (Apache fails withcould not open error log file /proc/self/fd/2). And it starts no session, so the app shares a process group withbuildah-chroot-exec, which runs as the same uid and SIGKILLs the app when the app signals its own group on SIGTERM (Apache's graceful stop does). runc and CRI-O do neither. So the job starts each replica through a launcher: it pipes stdout and stderr throughcat, on a pipe the uid owns, then execs the app throughsetsid, keeping its pid, so thesigtermcheck still signals the app itself. The launcher uses the Buildah image's ownbash,setsidandcat(its/usr, bind-mounted read-only at/.preflight/usrfor the run only), so the app image needs none of them and nothing is written into it.
Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
stage |
string | test |
Pipeline stage for the portability job. |
job_name |
string | portability |
Name of the job. Set it when you include this component more than once. |
image |
string | quay.io/buildah/stable:v1.45.1-immutable@sha256:e5a33092657823b0830186ea525054cf4cdeef29b6a44833444c59d86f561f29 |
Buildah image the job runs in. It builds the app image and runs the probe, so it needs buildah, curl, awk and find. |
dockerfile |
string | Dockerfile |
Dockerfile to build, relative to the context. |
context |
string | . |
Build context, relative to the project root. |
build_args |
array | [] |
Build arguments as NAME=value. $NAME and ${NAME} in a value are replaced from the job's variables. |
app_root |
string | /app |
Directory inside the image where the app lives. |
writable_paths |
array | ["storage", "bootstrap/cache"] |
Paths the app may write to, relative to app_root. Each must be writable by the uid in group 0. |
runtime_paths |
array | ["/tmp", "/var/tmp", "/run", "/var/run"] |
Absolute paths the platform mounts as tmpfs. Writes there are allowed. |
port |
number | 8080 |
Port the app listens on by default. The second replica gets port + 1 through port_env. |
port_env |
string | PORT |
Environment variable that sets the app's listen port. |
health_path |
string | /up |
Path that must answer 200 for any Host, before trusted hosts, HTTPS redirects, sessions and auth. |
uid |
number | 100123 |
Numeric uid the app runs as, with no /etc/passwd entry. The gid is always 0. |
start_command |
string | "" |
Command that starts the app, run with sh -c. Empty runs the image's own ENTRYPOINT and CMD. |
setup_command |
string | "" |
Command run once with sh -c before either replica starts, in a fresh container of the built image, as the same uid (gid 0) with the same env as replica A. Use it for one-time work a release does, such as php artisan migrate --force against a database in services. Empty runs nothing. A non-zero exit fails the job and no replica starts. |
env |
array | [] |
Environment for both replicas, as NAME=value (or NAME to pass the job's variable through). Keep secrets in CI/CD variables. |
services |
array | [] |
Service containers for the job, as GitLab's services: keyword takes them (an image string, or a map with name, alias and variables). A database or cache the replicas share lets session-hop pass for an app that keeps sessions there. Pin each image by digest. |
boot_timeout |
number | 60 |
Seconds each replica has to answer the health path. |
stop_timeout |
number | 10 |
Seconds the main process has to exit after SIGTERM. |
probe_path |
string | / |
Page probed with and without forged forwarded headers; one that redirects or builds absolute URLs shows the most. |
identity_header |
string | X-Forwarded-User |
Identity header a gateway would set (forged in forwarded-headers). |
session_login_path |
string | "" |
GET path that signs in a test user and sets the session cookie. Needed by session-hop. |
session_check_path |
string | "" |
Path that answers 200 only for a signed-in user. Needed by session-hop. |
session_header |
string | "" |
Optional Name: $VARIABLE header sent on every session-hop request, for example session_header: "X-Portability-Token: $PORTABILITY_PROBE_TOKEN". The job reads the variable at run time and never prints it. Use it when the sign-in route needs a secret. |
logs_path |
string | storage/logs |
Directory, relative to app_root, where nothing may be written. |
require_healthcheck |
boolean | false |
Fail when the image declares no HEALTHCHECK. Docker and Coolify use it; OpenShift and Kubernetes use their own probes. |
checks |
array | ["health", "env-only", "forwarded-headers", "logs", "session-hop", "sigterm", "healthcheck"] |
The checks to run. Leave one out only on purpose; the strict boot always runs. |
The image default is an immutable tag (-immutable) pinned by digest, because the plain version tag can be re-pushed and its old digest removed.
Verify locally#
tests/check-portability.sh (and its .ps1 twin) run the same probe in the same Buildah image against tests/portability/app: once clean, where every check must pass, and once per flaw (needs root, writes outside its paths, fixed port, host-bound health, a baked .env, trusts any proxy, file logs, file sessions, no SIGTERM handler, a failing HEALTHCHECK), where the targeted check must fail. Two more builds must pass every check: one reopens /proc/self/fd/2 and one signals its whole process group on SIGTERM, as Apache does; they fail without the launcher. Preflight's own pipeline runs the component on the clean fixture and this check as must-fail-portability. See Local checks for the commands.
Related#
- Include a component twice: the
job_nameinput. - Same instance only: components run only inside the GitLab instance that hosts this project.
- When the components run: the
workflow:rulesblock that belongs in the app's own file. - Reference: every component, with its inputs and defaults.