# Container compatibility

> Which image, Compose and listener features a container deployment supports.

Gregale's container contract is:

> A stateless Linux/amd64 OCI image that starts an HTTP server on
> `0.0.0.0:$PORT` can be deployed without rewriting it as a function.

Deploy an existing image directly:

```sh
gregale doctor --image registry.example.com/team/api@sha256:<digest>
gregale deploy --image registry.example.com/team/api@sha256:<digest>
```

Gregale preserves the OCI/Docker process model. Image metadata supplies the
entrypoint, command, environment, working directory, user, health check, stop
signal, and exposed ports. Deployment overrides can replace the start command,
port, or readiness settings. An explicit port wins; otherwise a single exposed
TCP port seeds the default.

This makes existing Go, Rust, Java, Spring, .NET, Node, Python, nginx, custom
binaries, and Docker applications portable. Images can come from a Dockerfile
or an OCI registry. A multi-platform index resolves to its Linux/amd64 image.

Images that do not share a Gregale-optimized base can use a self-contained
full-rootfs deployment. Paid plans enable that path automatically; Free plans
currently require an explicit opt-in. The resulting workload still uses the
same Firecracker isolation, snapshots, metering, routing, and scale-to-zero
lifecycle.

The portability boundary is intentionally small: Linux/amd64, a stateless HTTP
listener reachable on `0.0.0.0`, and a process that honors `PORT` (default
`8080`). The root filesystem is ephemeral. OCI volumes and host mounts do not
create durable storage, and privileged mode, host devices, host networking, and
the Docker socket are not supported.

Persistent container disks are outside Gregale's service contract. Store durable
application state in object storage or an external database. Snapshot reuse is a
startup optimization and does not guarantee filesystem persistence across
instances, cold fallback, redeployment, or node failure. The ephemeral disk
allowance includes application content and filesystem overhead, rather than
guaranteeing that amount of free scratch space.

While an image is assembled, its layers may write at most twice the plan's
ephemeral disk allowance in file content (`LayerExtractionBudgetMultiple`).
Content that a later layer replaces or deletes still counts toward this
budget. The layers may also apply at most 2,000,000 entries in total (files,
directories, links and whiteouts, `LayerExtractionMaxEntries`), twice the
1,000,000 entries the runtime scan accepts. An image that exceeds either
limit fails with `app_layer_too_large` before assembly finishes. A registry blob download may wait up to 60 seconds for
headers or for its next bytes, and may take up to 30 minutes in total.

Direct OCI images use TCP listener readiness by default; Gregale does not
invent a `/healthz` endpoint that the image never declared. An explicit
deployment health-path override selects HTTP readiness instead.

For an image with TCP readiness and no HTTP health path, the post-readiness
public smoke checks candidate route connectivity at `/`. A candidate-authored
2xx, 3xx, 401, 403, or 404 response can verify connectivity; an API does not
need to implement a successful root route. Gateway errors, missing candidate
response evidence, a different revision, 429, and 5xx still fail verification.
An explicit HTTP health path (including `/`) continues to require 2xx.

The deployment's `hosting_receipt.smoke.verification` records `http_health`
or `route_connectivity`, alongside the actual response status.
`authentication: platform_challenge` means the platform probe bypassed Gregale
customer access gates; it does not prove anonymous access or bypass
application-owned authentication. Connectivity probes record redirects without
following them.

Both candidate verification contracts require an authenticated candidate
response, including explicit HTTP health checks. A deployment header alone,
gateway error, or missing/invalid response proof cannot verify the candidate.
Candidate redirects are never followed; HTTP health requires a proven 2xx on
the configured path.

If challenge publication, the public gateway response, or the verification
transport remains unavailable, the candidate stays `snapshotting` and retries
through the durable notification outbox. A transport failure does not establish
whether the app or platform caused it. The existing serving deployment keeps
traffic. Recovery progress is
available in `stage_state.hosting_verification`: `attempts`, `deadline_at`,
`last_error_code`, and `retry_not_before` (the earliest eligible retry, not a
promised delivery time). `last_error_code` distinguishes publication, gateway,
transport, missing-proof and wrong-deployment failures. The five-minute
recovery window survives platform restarts and changes of outage reason. If it
expires, the deployment fails with `deployment_verification_unavailable`;
inspect deployment and gateway diagnostics before retrying. A proven candidate
response with an unhealthy status retains `deployment_smoke_failed`.

Roll out response-proof support to all gateways before enabling this verifier
for HTTP health checks; an older gateway cannot verify a candidate.

Gregale adds the managed infrastructure around that process: TLS, readiness,
logs and metrics, snapshots, autoscaling, and scale-to-zero.

## Runtime environment

The process starts in the environment a container runtime provides:

| | Gregale | Docker |
|---|---|---|
| `HOME` | The image or deployment value; else the user's passwd home when the user can write there; else `/tmp` | The image value, else the passwd home |
| `PATH` | The image or deployment value, else `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` | Same |
| Working directory | `WORKDIR`, created for the process user when missing | Same |
| Open files (`ulimit -n`) | 65,536 soft, 1,048,576 hard | Varies by host; Kubernetes gives 1,048,576 |
| Hostname | `gregale` | The container ID |
| `/etc/hosts` | The image's file, plus `127.0.0.1 localhost` and `10.0.0.2 <hostname>` when it lacks them | Generated; image entries ignored |
| `/tmp` | RAM-backed tmpfs, up to half the instance's RAM, starting with the image's `/tmp` files | The image's directory on the container disk |
| `/dev/shm` | tmpfs, up to half the instance's RAM | 64 MB tmpfs |
| `/dev/pts` | Mounted | Mounted |

Files in `/tmp` and `/dev/shm` use the instance's memory: filling them hits
the plan's RAM limit, not a disk-full error. Write large scratch files under
the home directory or the working directory instead; that space counts against
the ephemeral disk allowance.

## Randomness after a snapshot restore

A scaled-to-zero app wakes from a snapshot of its running process, so any
random generator the process held in memory is restored with it. The guest
kernel is reseeded on every wake, so anything that reads the kernel on each
call is always safe: `/dev/urandom`, `getrandom(2)`, Go `crypto/rand`, Python
`secrets`, `os.urandom` and `uuid.uuid4`, and Node `crypto.webcrypto`.

For Node and Python, Gregale also reseeds the process itself before a woken
instance serves traffic. It covers Node `crypto` (and the OpenSSL
state behind TLS), `crypto.randomUUID`, `crypto.randomInt` and `Math.random`,
and Python `random`, `ssl`, and numpy's global `numpy.random` functions. If a
process cannot confirm the reseed, the instance cold-boots instead of waking
from the snapshot.

Java on Java 16 or newer is reseeded the same way:
Gregale adds a small agent to `JAVA_TOOL_OPTIONS`, which resets `Math.random`,
`ThreadLocalRandom`, `SplittableRandom` and the seed that a `new Random()`
draws from. Every JVM then prints `Picked up JAVA_TOOL_OPTIONS: …` on stderr
when it starts. Java's default `SecureRandom` reads the kernel and needs
nothing.

A JVM built with `jlink` cannot load any agent unless it includes the
`java.instrument` module, and it would not start with one named. When the
image holds such a JVM, Gregale leaves the agent out, so the app starts but
its JVMs are not reseeded and Gregale warns on each wake. Add
`--add-modules java.instrument` to the `jlink` command to keep the reseed.

Go cannot be reseeded from outside the program. Use `crypto/rand` for anything
that must be unique. To reseed generators your program owns, import
`github.com/gregale-dev/gregale-go/reseed` and register a callback with
`reseed.OnRestore`; Gregale runs it after each restore, before the instance
serves traffic.

Reseed these yourself, or avoid keeping them across a snapshot:

- Go `math/rand` and `math/rand/v2` global functions, Ruby `Random`, and PHP
  `mt_rand`. Two restores of one snapshot return the same Go values
  (measured);
- a Java `Random` object, or a `SecureRandom` you seed yourself or create as
  `SHA1PRNG`, that your code created before the snapshot, and any JVM older
  than Java 16;
- generator objects your code created before the snapshot, such as Python
  `random.Random()` or `numpy.random.default_rng()`;
- values your code generated before the snapshot, such as a secret, nonce or
  instance ID drawn once at startup: every instance restored from that snapshot
  holds the same value. Draw them per request or per use, and take the serving
  instance from the `X-Faas-Instance-Id` request header or, outside a request,
  from the file named by `FAAS_INSTANCE_IDENTITY_FILE`, which Gregale rewrites
  on every wake ([trace propagation](https://gregale.dev/docs/trace-propagation.md#deployment-identity));
- `Math.random` inside Node worker threads;
- sidecars that run from their own root filesystem;
- Bun and Deno, which do not load the Node reseed; Python started with `-S`,
  `-E` or `-I`, which skips the Python reseed; and any Node, Python or Java
  process started with a cleared environment. Gregale logs a warning on each
  wake when it finds such a process running, or a Go program that does not
  import the `reseed` package;
- OpenSSL copies bundled inside Python packages, such as `psycopg2-binary` and
  `cryptography` wheels: the reseed reaches only the standard library's `ssl`;
- ID libraries that keep a random pool or per-process state, other than the
  ones Gregale resets: instances restored from one snapshot can generate the
  same IDs. Gregale resets npm `uuid` (its random pool and its v1, v6 and v7
  state), `nanoid` and `bson` `ObjectId` in Node, and `bson` `ObjectId` in
  Python, on every restore.
  Copies bundled into one file by esbuild or webpack, ES modules on Node older
  than 22.15, and Go libraries are not reset: Go `rs/xid`, the MongoDB Go
  driver's `ObjectID` and the OpenTelemetry Go SDK's trace IDs repeat, and
  Gregale logs a warning on each wake of a Go app that uses them.

A restore moves the app's clock forward by the time it spent parked. gunicorn
would read that as hung workers and restart one on every wake; Gregale's
Python preload stops that, and a worker that really hangs is still restarted
after `--timeout`. Set `GREGALE_GUNICORN_FREEZE_GUARD=off` to turn this off.

Setting `GREGALE_RESTORE_RESEED=off` in the app's environment disables the
Node, Python and Java reseed. Only do that for an app that never generates tokens,
keys, nonces or identifiers.

## Support boundaries

Compose project services may use prebuilt `image:` references without a build
context. Stateless images join the deployment and dependency graph; database
and cache images remain managed-resource requirements. Scan plans display the
image declaration, and the image worker resolves tags to immutable references
before materialization. The first published TCP container target selects the
main port, and Compose commands retain the image ENTRYPOINT. Image workloads
return a deployment ID without a build ID. Source-defined operations on these
workloads currently require an atomic image admission path and are rejected.
After CI pushes an image, the [image-published trigger](https://github.com/poyrazK/faas/blob/main/docs/image-published-deployments.md)
deploys its exact digest with durable per-workload and scope deduplication.
New project image deployments also capture their accepted Compose CMD contract;
queued images and retries retain it after app configuration changes. Historical deployments without
that record keep their existing command behavior.

Compose `depends_on: {backend: {condition: service_healthy}}` now holds the
dependent workload's initial release until the captured backend deployment is
live with traffic in the same environment. A failed dependency or a fixed
15-minute wait deadline fails the candidate while the previous release keeps
serving. `gregale release get` and the dashboard stage summary show the
blocker. This gates release activation; candidate processes can boot while
waiting. Declarations allow at most 100 dependency conditions per workload.
Optional healthy dependencies and healthy job targets are rejected. A healthy
gate on a Compose datastore such as `postgres` is accepted as a plain
dependency, and a `service_completed_successfully` dependency runs as the
release command of the waiting service that shares its build
([multi-service apps](https://gregale.dev/docs/multi-service.md#start-order-and-migrations)).

Compose `healthcheck:` overrides are also retained for prebuilt image workloads:

```yaml
services:
  api:
    image: ghcr.io/team/api:production
    healthcheck:
      test: [CMD-SHELL, 'curl -f http://localhost:$${PORT}/ready || exit 1']
      interval: 15s
      timeout: 250ms
      start_period: 20s
      start_interval: 500ms
      retries: 3
```

String tests use `CMD-SHELL`; list tests accept `CMD`, `CMD-SHELL`, or `NONE`.
`disable: true` disables an inherited image check. Omitted or zero timing/retry
values and empty tests inherit image settings. Durations preserve exact timing;
positive values must be at least 1ms. `$$` preserves a dollar for the guest
command; scanning does not read the host environment to interpolate variables.
The check runs inside the image and requires its executable or shell to exist.
Accepted overrides, including the choice to inherit, survive app edits, retries,
and rollback. JSON scan plans expose them as `image_healthcheck`.

Newly assembled image deployments require a fresh successful command check
before serving readiness, alongside the existing network or worker readiness
and public-route verification. Startup grace, retries, and command timeouts
apply within the startup deadline. A failed or missing result blocks promotion;
boot, restore, and warm-pool resume cannot reuse a previous pass. `NONE` and
absent checks retain ordinary readiness. Redeploy to add this gate to an
existing deployment. Compose dependency release gates are described above. A Compose
healthcheck on a source-built service is merged onto the built image's
HEALTHCHECK and enforced the same way.
A Dockerfile `HEALTHCHECK` on its own is enforced too:
a source build's next deployment waits for its command check to pass, and
recovers from repeated failures, like a pushed image. The check runs inside the
built image, so the tools it calls (`curl`, `wget`) must be installed there. To
keep ordinary readiness, use `HEALTHCHECK NONE`, drop the instruction, or set
`healthcheck: {disable: true}` on the Compose service. Deployments built before
this change keep their readiness until they are redeployed.

A Compose healthcheck that only fetches the service's own serving port with
`curl` or `wget` (`curl -f http://localhost:8080/actuator/health || exit 1`,
or the `CMD` list form) runs from the platform instead: it becomes the
service's HTTP readiness check on that path, with the same interval, timeout,
retries and start period, and the command check (including an inherited image
`HEALTHCHECK`) is set to `NONE`. The image then needs no `curl` or `wget`. A
check of another port, with headers, a method other than GET, or any other
shell syntax stays a command check. The plan notes each conversion.

Required primary image checks also drive runtime recovery. Each serving
instance executes fresh command attempts using the effective interval, timeout,
startup grace, and consecutive failure threshold. Repeated command failures
request scheduler-owned teardown and cold recovery, even if HTTP stays open.
The declared command replaces implicit HTTP liveness, so the image does not
need a /healthz endpoint. Explicit HTTP/gRPC liveness remains additional.
Successful checks clear the failure streak; process replacement and serving
resume start fresh monitoring. Missing or invalid transport proof requests
infrastructure recovery without consuming the app's permanent restart budget.
The existing restart circuit limits repeated confirmed failures. Failure
diagnostics use image_healthcheck_unhealthy without publishing command output.
Image health checks are not enabled for every account yet.

Automatic image promotion also checks for newer accepted releases in the same
app and environment scope. Older in-flight candidates become superseded, and
GitHub-triggered images recheck their recorded source branch before cutover.
Explicit rollback retains its existing behavior.

Prebuilt image services can also override the image's process:

```yaml
services:
  api:
    image: ghcr.io/team/api:production
    entrypoint: [tini, --]
    command: [node, server.js]
    user: "1000:1000"
    working_dir: /srv/app
    stop_signal: SIGINT
    stop_grace_period: 20s
    env_file: [.env.production]
```

`entrypoint` replaces the image ENTRYPOINT and, as in Docker, drops its CMD, so
`command` supplies the arguments; `entrypoint: []` clears the ENTRYPOINT and
needs a `command`. String entrypoints are split on spaces; anything with quotes
or shell syntax must use the list form. `user` takes a name or id with an
optional `:group`, resolved against the image's `/etc/passwd` and `/etc/group`.
`working_dir` must be an absolute path. `stop_signal` accepts the signals
guest-init delivers (SIGTERM, SIGINT, SIGQUIT, SIGHUP, SIGUSR1, SIGUSR2), and
`stop_grace_period` is capped by the plan. Like commands, these overrides are
captured per deployment, so queued deployments and rollbacks keep them.
Source-built services take the same overrides:
an `entrypoint` is folded into the service's start command (the entrypoint,
then the command), and `user`, `working_dir` and the stop contract are applied
to the built image as a Dockerfile's USER, WORKDIR and STOPSIGNAL would be.

`env_file` contributes variable names only. The scan lists them as required
environment keys, exactly like `environment:`; values never leave the source,
so set them with `gregale env set` or secrets. The project plan shows, per
service, each name that will have no value in the target environment under
**Needs a value**: names already configured on the app, supplied by
`--secrets-file`, or set by Gregale itself (`PORT`, `GREGALE_*`) are left out.

Three more Gregale keys shape the apps a Compose file creates:

```yaml
x-gregale-slug-prefix: shop-    # new apps are shop-ui, shop-cart, ...
x-gregale-public-auth: open     # or bearer; per service too
services:
  ui:
    build: ./ui
    x-gregale-startup-deadline: 90s
```

- `x-gregale-slug-prefix` (top level) names each new app `<prefix><service>`,
  so short service names need not be unique across Gregale. Service names, and
  the `<service>.svc.gregale` addresses built from them, do not change; an app
  that already exists keeps its name. `gregale deploy --project --prefix P`
  does the same and wins over the file.
- `x-gregale-startup-deadline` (seconds or a duration, at most 120 s) is how
  long a new instance may take to become ready. Without it, a healthcheck with
  a `start_period` sets it to `start_period` plus `retries` × `interval`
  (Docker's defaults: 3 and 30 s) when that is longer than the default 30 s. A
  `lifecycle.startup_deadline_s` in `gregale.yaml` takes precedence over the
  derived value. Either is capped at the plan's maximum (Free and Hobby 30 s,
  Pro 60 s, Scale 120 s).
- `x-gregale-public-auth` (`open` or `bearer`, top level or per service) sets
  who may call a new app's public URL instead of the plan default; `bearer`
  needs Hobby or above.

The deadline and auth keys apply when an app is created; change an existing
app with `gregale app update`.

A Compose file can opt in to importing the plain values of `environment:`:

```yaml
x-gregale-env-import: true
services:
  api:
    build: ./api
    environment:
      LOG_LEVEL: info                   # imported
      STRIPE_KEY: sk_test_example       # not imported: looks like a secret
      BILLING_URL: http://billing:8080  # not imported: Docker service address
```

A reviewed project apply (`gregale deploy`, the dashboard, or
`gregale deploy --repo … --project`) writes each imported value into the
service's app, in the deploy's environment, before any build starts; a GitHub
push imports only the addresses of sibling services. Values are written only where the key is still unset: a
value configured on the app, as a variable or a secret, is never replaced. The
plan lists imported names under **Imported from Compose** and gives the reason
for each value it skips: a secret-looking key or value, an address of another
Compose service or the local machine, `$` interpolation, an entry read from the
host, or an empty value. Values never appear in the plan, logs or audit events.
`env_file` values are never imported. `compose.override.yaml` is part of the
Compose model, so its values are imported too; keep local-only settings out of
an opted-in project. Without the opt-in the plan marks importable values as
"plain value in Compose" and shows the line that imports them. An env file missing from the
source (for example a git-ignored `.env`) is a warning, or silent with
`required: false`. Quoted values, including multi-line double- or
single-quoted ones, are read to their closing quote; a malformed line is
reported with its file and line number and skipped.

Source-built services pass `build.args` and `build.target` to their Dockerfile
build, as `docker compose build` does:

```yaml
services:
  api:
    build:
      context: ./api
      target: production
      args:
        NODE_VERSION: 22
        APP_VERSION: ${APP_VERSION:-dev}
        SENTRY_RELEASE:
```

`args` takes the map or the list form. `${VAR}` reads the source's `.env`, like
the rest of the file; `$VAR` without braces is passed literally and warns. A name
without a value (`SENTRY_RELEASE:`, or `- SENTRY_RELEASE` in the list form) also
reads `.env`; when `.env` does not set
it, the argument is left out and the Dockerfile's `ARG` default applies, with a
warning. `target` must name a stage the Dockerfile declares with `FROM … AS`;
an unknown stage fails the scan. A service whose build context has no Dockerfile
builds with Railpack, so its `args` and `target` are warned and ignored. Up to
64 arguments of at most 4 KiB each are accepted (`DockerfileBuildArgsMax`,
`DockerfileBuildArgValueMaxBytes`).

Each deployment keeps the arguments and target it was planned with, and changing
either rebuilds instead of reusing a cached image. A public build URL with the
same name as an argument wins. Build arguments end up in the image history, so
keep secrets out of them and set those with `gregale env set`. Plans show the
target and the argument names, not their values.

Build-time secrets use `build.secrets`:

```yaml
services:
  api:
    build:
      context: ./api
      secrets: [npm_token]          # RUN --mount=type=secret,id=npm_token ...
secrets:
  npm_token:
    environment: NPM_TOKEN          # gregale env set NPM_TOKEN
```

Each entry names a top-level secret declared with `environment: NAME`; the
build mounts the secret the app receives as `NAME` at runtime, under the id the
entry gives (`{source, target}` sets the id to `target`). That is the app's own
secret in the deployment's scope, an environment reference that points `NAME`
at another secret, or a project environment secret the app inherits.
A deployment with an explicit secret selection inherits no project secrets, at
build or at runtime. `file:` and
external secrets are not uploaded and are left out with a warning. The value is
opened only inside the builder VM, mounted with BuildKit's secret mount, and
never stored in the image, its cache or Gregale's records; a build whose
secret is not set fails with its name. Builds with secrets run on a fresh
builder. At most 16 secrets per build (`DockerfileBuildSecretsMax`).

A service's own `secrets` become files in `/run/secrets`:

```yaml
services:
  db-client:
    image: example/app:1
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password                 # /run/secrets/db_password, mode 0444
      - source: api_key
        target: api.key             # /run/secrets/api.key
        mode: 0400
secrets:
  db_password:
    environment: DB_PASSWORD        # gregale env set DB_PASSWORD
  api_key:
    environment: API_KEY
```

Each entry names a top-level secret declared with `environment: NAME`; the file
holds the secret the app receives as `NAME`, which is also in its environment.
`target` is a file name in `/run/secrets` (an absolute path there is the same);
a target elsewhere, a `file:` or external source is left out with a warning,
and an undeclared name fails the scan. `mode` defaults to `0444`; the file is
owned by the user the service runs as, and `uid`/`gid` are ignored. The files
live in a memory-backed `/run/secrets` written before the service starts. An
image that opts into live secret reload gets them rewritten with each new
value; otherwise they change on the next start. A secret that is not set has
no file. Only the service's main process gets the files, not sidecars, jobs or
app tasks. At most 16 files per service (`SecretFilesMax`).

A service's size and count set its app's settings:

```yaml
services:
  api:
    image: example/api:1
    deploy:
      replicas: 3                   # max_concurrency 3 (instances still park when idle)
      resources:
        limits:
          memory: 512M              # ram_mb 512
          cpus: "0.5"               # cpu_millicores 500
```

`memory` (or `mem_limit`) takes bytes or a `k`, `m`, `g` suffix in powers of
1024 and is rounded up to whole MiB; more than the plan's RAM per app fails the
plan. `cpus` (or the service-level `cpus`) is rounded up to an app CPU share,
0.25, 0.5 or 1, with a warning; more than 1 is lowered to 1. `replicas` (or
`scale`) caps a request-mode app's instances and fixes a worker's or service's
replica count, within the plan's cap for that mode; it does not apply to jobs,
and `replicas: 0` is ignored with a warning. Declared values are written on
every apply and replace values set with `gregale app <slug> --ram` and the like; settings the
file does not declare keep the app's. Reservations and the other `deploy` keys
are warned.

A new service whose file declares no memory starts with 128 MB
(`ProjectWorkloadDefaultRAMMB`), not the default a standalone app gets (the
plan's RAM, at most 1024 MB). The
project plan marks such services `memory=128MB (default)` and lists them under
"Starts with the default 128 MB". Node and Python services often need more, so
declare `memory`, or raise it with `gregale app <slug> --ram` after the deploy.

`extends` and top-level `include` are resolved as Compose resolves them:

```yaml
include:
  - services/api/compose.yaml        # build: . there builds services/api
services:
  worker:
    extends: {file: common/base.yaml, service: node}
    command: [node, worker.js]
```

A service is merged onto its base with the override-file rules: mappings merge,
`ports`, `env_file`, `profiles`, `depends_on` and `environment` append, and
other values are replaced. Build contexts and `env_file` paths in another
directory stay relative to their own file. Included services join the project;
a service defined in two files, an unknown base, a cycle or a missing file fails
the scan, as in Compose. Remote includes are not loaded and warn. An included
file is interpolated with its own values: the
including project's, overlaid by the files its `env_file` option names (from
the including file's directory; a missing one fails the scan), or else by the
`.env` beside the included file. `COMPOSE_PROFILES` is read from the root `.env`
only. An include's `project_directory` is not applied and warns; paths resolve
from the included file's directory. At most 32 files are linked in one scan.

A service with `profiles:` is deployed only when one of its profiles is active.
Activate profiles with `COMPOSE_PROFILES` in the source's `.env`, as Compose
reads it there: comma-separated names, or `*` for every profile. Other services
are skipped with a warning naming their profiles.

The scan reports every other Compose key instead of dropping it silently:

| Keys | Result |
|---|---|
| `build` (`context`, `dockerfile`, `args`, `target`, `secrets`), `command`, `cpus`, `depends_on`, `deploy` (`replicas`, `resources.limits.memory`, `resources.limits.cpus`), `entrypoint`, `expose`, `healthcheck`, `image`, `mem_limit`, `ports`, `profiles`, `scale`, `secrets` (`environment:` sources), `stop_grace_period`, `stop_signal`, `user`, `working_dir`, `x-gregale-*` | Applied. |
| `environment`, `env_file` | Names applied: the plan lists each one without a value under **Needs a value**. Plain `environment:` values are imported only with `x-gregale-env-import: true`, on a reviewed deploy; `env_file` values are never imported. See above. |
| `container_name`, `init`, `stdin_open`, `tty`, `platform: linux/amd64`, `x-*` extensions | Ignored without a warning; they have no effect on a microVM service. |
| `volumes`, `tmpfs` | Warning: no persistent volumes or bind mounts; each start gets a fresh filesystem. |
| Other `deploy` keys (`restart_policy`, `placement`, `update_config`, `resources.reservations`, …), `cpu_shares`, `cpu_quota`, `cpuset`, `mem_reservation`, `memswap_limit` | Warning, with the reason for each. |
| `restart` | Warning: the platform starts, parks and restarts services. |
| `configs` | Warning: build the file into the image or use environment variables. |
| `networks`, `network_mode`, `links`, `external_links` | Warning: services reach each other through `depends_on` service bindings. |
| `cap_add`, `privileged`, `devices`, `security_opt`, `ulimits` and other kernel controls | Warning: each service runs in its own microVM. |
| `dns`, `extra_hosts`, `hostname` and other guest networking keys | Warning: guest networking is managed by the platform. |
| `labels`, `logging`, `pull_policy`, any other `platform` | Warning. |
| `build.ssh`, `build.dockerfile_inline`, other `build.*` keys | Warning: the builder uses only `build.context`, `build.dockerfile`, `build.args`, `build.target` and `build.secrets`. |
| Any other service key | Warning: not supported. |

Managed database and cache services (for example `postgres`) do not report
their keys: the managed resource replaces the container.

| Concern | Current contract | Qualification boundary |
|---|---|---|
| Image platform | Linux/amd64; compatible child selected from an OCI or Docker index. A lone child without a platform annotation is selected and its config's platform checked. | Other architectures and operating systems are rejected. |
| Process | Image ENTRYPOINT + CMD, environment, working directory, and user. As under Docker, an image without `USER` runs as root, and a numeric UID absent from the image's passwd runs with GID 0. Root-owned image files stay root-owned in the guest. | Metadata inspection cannot prove executables or users exist in the layers. Numeric or named `USER user:group` is preserved; explicit missing identities fail launch. Supplementary memberships are not imported. Redeploy older deployments to pick up root ownership. |
| Main listener | Explicit deployment port, otherwise one exposed TCP port, otherwise 8080. Port 80 is supported: when a workload in the VM declares it, the in-guest metadata endpoint moves from `169.254.169.254:80` to `169.254.169.254:8775`. | Multiple TCP declarations do not select the main port. Bind to `0.0.0.0`. Read the metadata URLs from `FAAS_EVENT_PUBLISH_ENDPOINT`, `FAAS_METADATA_ENV_ENDPOINT` and `FAAS_SECRETS_RELOAD_ACK_ENDPOINT` instead of hardcoding the address. |
| Additional listeners | Declared TCP listeners use `<slug>--port-<name>.<apps-domain>` selectors through the gateway | These are HTTP gateway selectors. Raw TCP uses separately configured app-owned listeners; UDP uses the separate opt-in listener service below. |
| Raw TCP ingress | Opt-in public edge binds stable app-owned TCP listener ports and forwards bytes to the app; optional per-listener TLS termination | Not enabled for every account yet. TLS defaults to passthrough; termination requires a verified app-owned hostname. |
| Private TCP between services | Same-account services dial `<name>.svc.gregale:<port>`, or the bare Compose name (`orders:8080`, which the guest resolver searches under `svc.gregale`), on any declared TCP listener or the serving port; compose `expose:` declares internal-only listeners | Not enabled for every account yet; until it is, service names answer HTTP only. Internal listeners never get public selectors or raw TCP listeners. Ports 10080, 10081 and 443 stay on the HTTP mesh. See [networking](https://gregale.dev/docs/networking.md#private-tcp-between-services). |
| Raw UDP ingress | Opt-in public edge reserves app-owned UDP endpoints and forwards framed datagrams to the app | Not enabled for every account yet; requires IPv4 source CIDRs. |
| Host ports | Durable per-node TCP/UDP lease allocation | A lease does not bind a socket or enable direct ingress. |
| Readiness | TCP by default for direct images; explicit health path selects HTTP | Image HEALTHCHECK metadata is separate from verifying public-route readiness. |
| Image healthchecks | CMD/CMD-SHELL polling with image identity, environment, working directory, and exact nanosecond timing; StartInterval is retained | CMD-SHELL requires the image to contain its shell. Not enabled for every account yet. |
| Filesystem | Compatible shared-base layering or full-rootfs fallback; ephemeral writable state | VOLUME does not provision persistent storage; no host mounts or Docker socket. |
| Lifecycle | Request, service, worker, and job modes with validated restart policies | Free is request-only; quotas and availability remain plan-controlled. |
| Companions | Separate image roots and resource controls, shared guest kernel and loopback | Use separate deployments for mutually untrusted workloads. |
| Snapshot restore | Restorable cache with cold-boot fallback; optional lifecycle callbacks | External connections and durable state require application recovery handling. |

Availability is defined by the [capability matrix](https://github.com/poyrazK/faas/blob/main/docs/capabilities.md), not by this
compatibility table. In particular, container deployment is generally
available while companions and worker pools are preview.

## Image preflight

During self-contained full-rootfs assembly, Gregale checks the effective startup
command after applying all image layers and deployment command overrides. An
explicit command path must resolve to a regular file with an execute bit;
relative paths resolve from the image working directory. Shell-form startup
commands therefore require their selected shell (usually `/bin/sh`) in the
image. Missing commands, invalid symlinks, directories, and non-executable files
fail the deployment with `image_manifest_invalid` before ext4 publication or VM
boot. The failure identifies the command without exposing arguments or
environment values.

For bare commands, assembly uses the image/deployment `PATH` plus the current
scoped app environment, with the same absolute-directory lookup as guest-init.
A sealed `PATH` or unavailable runtime environment defers that lookup to the
guest. Assembly never decrypts secrets or copies runtime `PATH` into the image.
Later environment changes remain subject to guest launch validation.
Commands under guest-provided mounts (`/dev`, `/proc`, `/sys`, `/tmp`, and
companion roots), including image symlinks to those paths, also defer to launch
because their contents are supplied or replaced at boot.

This check does not run image code or prove ELF/script interpreter compatibility,
user permissions, healthcheck execution, shell command contents, or readiness.
It applies to the complete full-rootfs main image; the shared-base upper-layer
path cannot prove whether a command exists in its base and retains its guest
validation. The metadata-only doctor command below retains its fast path.

`gregale doctor --image REF --json` reports `image.serving_port` as inferred
from image metadata before deployment overrides. Human output shows the same
port. A listener finding warns when multiple TCP ports leave the default
ambiguous or when only UDP ports are declared. `--strict` makes those warnings
fail the preflight; normal mode reports them without rejecting the image.
An image exceeding the workload listener cap fails runtime-contract validation.
Declared volume paths appear in `image.volume_paths` and human output, with an
explicit warning that they remain ephemeral and do not provision durable storage.
UDP-only images receive guidance for configuring app-owned UDP endpoints and
source CIDRs; a declaration alone does not enable ingress or
provide the main HTTP readiness listener.

Preflight does not download layers, execute image commands, prove that the
server binds its port, or validate account policy. A successful metadata check
does not prove the image runs.

Source: https://gregale.dev/docs/container-compatibility
