Skip to content
PREFLIGHT 0.9.0
Menu

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 sessions table before it serves. setup_command runs php artisan migrate --force once, in its own container, before either replica starts, the way a release migrates once before the web pods start. Use it instead of start_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.4 is; mysql:5.6 is 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:

  1. Builds the image with buildah bud, from dockerfile in context, with build_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.
  2. Reads the image's ENTRYPOINT and CMD, makes two copies of its filesystem (replicas A and B) and runs the static parts of strict-boot and env-only on them.
  3. Runs setup_command once, 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.
  4. Starts both replicas with buildah run --user <uid>:0 --cap-drop=ALL and the env input, each through a small launcher that gives it its own stdio and session; B gets port + 1 through port_env.
  5. Waits up to boot_timeout seconds for each replica's health path, then runs health, env-only, forwarded-headers, session-hop, logs and sigterm with curl, and healthcheck with the image's own command.
  6. Stops both replicas and compares what changed on disk against writable_paths and runtime_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 run starts 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 run has no no-new-privileges flag. 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 run differs 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 with could not open error log file /proc/self/fd/2). And it starts no session, so the app shares a process group with buildah-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 through cat, on a pipe the uid owns, then execs the app through setsid, keeping its pid, so the sigterm check still signals the app itself. The launcher uses the Buildah image's own bash, setsid and cat (its /usr, bind-mounted read-only at /.preflight/usr for 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.