zenith-compose.yml reference

zenith-compose.yml is a Compose file with an x-zenith section. This page lists the fields Zenith accepts and explains how they behave when you deploy an app. The CLI’s zenith check and zenith up also enforce the preview source-build policy. The quickstart and manifest guide cover setup, testing, and publishing.

File requirements

Requirement	Value
File name	`zenith-compose.yml`
Location	Repository root
Dockerfile for publishing	A root `Dockerfile` is required for `build: .`. Image-only submissions do not require one.
Repository for publishing	Public GitHub repository with a linked GitHub account authorized for publishing
Revision for CLI publishing	Pinned full 40-character commit SHA; `zenith publish` defaults to local `HEAD`, or accepts `--commit`
Maximum size	`128 KiB`
Format	Non-empty YAML that loads as a Compose project
Services	Required top-level Compose map.
Zenith extension	Required top-level `x-zenith` map

For publishing, the selected commit must be available in the public GitHub repository. It need not be the current default-branch commit. Zenith fetches the root manifest at that exact commit. Later changes to zenith-compose.yml are not automatically pulled and will not change an existing submission until you submit a new revision. zenith up instead uploads your local project for temporary testing. It does not submit a catalogue listing or establish that the later GitHub publish build is identical. Unknown fields inside x-zenith fail parsing. Standard Compose fields are parsed separately. The repository schema may accept fields outside Compose compatibility, but only the listed fields have defined Zenith runtime behavior. Zenith admission also rejects the inputs listed under Zenith runtime restrictions.

Document shape

This fragment shows the document structure. A valid manifest also defines the web service referenced by expose.

zenith-compose.yml

x-zenith:
  catalog:
    name: Example
    description: Example application.
    authors: [Example team]
    tags: [example]
    source: https://github.com/example/app
    license: MIT
    alternatives: []
  expose:
    - service: web
      port: 3000
      web: true
  storage: {}
  configs: []
  env: {}

services: {}
configs: {}
volumes: {}
secrets: {}
networks: {}

Key	Type	Required	Purpose
`x-zenith.catalog`	map	Yes	Catalogue metadata. Required fields are listed below.
`x-zenith.expose`	list	Yes	At least one public endpoint.
`x-zenith.storage`	map	No	Metadata for persistent volumes.
`x-zenith.configs`	list	No	Specific files in named volumes that app owners can edit. Applying a change requests an app restart.
`x-zenith.env`	map	No	Deployment environment declarations.
`x-zenith.sign_in`	map	No	Callback registration for Sign in with Zenith through OpenID Connect.
`services`	map	Yes	Compose services referenced by `x-zenith`. Define these with your normal Compose workflow.
`configs`	map	No	Standard Compose inline configuration files mounted by referenced services.
`volumes`	map	No	Compose named volumes.
`secrets`	map	No	Compose secrets. Developer submissions cannot load them from files.
`networks`	map	No	Parsed by Compose. Zenith places all services in one isolated deployment network.

`catalog`

catalog describes the app listing. alternatives and the other optional fields can be omitted.

x-zenith:
  catalog:
    name: Example
    description: Example application.
    authors:
      - Example team
    tags:
      - example
    source: https://github.com/example/app
    license: MIT

Field	Type	Required	Description
`name`	string	Yes	App name.
`description`	string	Yes	App description.
`authors`	list of strings	Yes	One or more unique author names.
`tags`	list of strings	Yes	One or more unique tags.
`source`	URI	Yes	Source or repository URL.
`license`	string	Yes	License identifier or name.
`alternatives`	list of strings	No	Unique names of comparable apps.
`detail`	string	No	Additional catalogue detail. Roughly one paragraph.
`funding`	URI	No	Funding URL or empty string.
`website`	URI	No	Website URL or empty string.

`expose`

For setup examples, see Public URLs and domains. Each expose entry maps a service port to a public HTTP hostname. An entry without label uses the app’s primary hostname. Labelled entries use separate endpoint hostnames.

x-zenith:
  expose:
    - service: web
      port: 3000
      web: true

Field	Type	Required	Default	Behavior
`service`	string	Yes	None	Exact key from the top-level `services` map.
`port`	integer	Yes	None	Container port from `1` through `65535`. The port does not need to appear in the service’s Compose `ports` list.
`label`	string	No	Empty	Route label. Omit it for the primary endpoint; a non-empty label gives the endpoint a separate hostname.
`web`	boolean	Yes	None	Marks a service as user-facing. It does not control access.
`forward_auth`	boolean	No	`false`	Requires the deployment owner’s Zenith sign-in for this endpoint.

The primary endpoint uses the deployment’s canonical hostname:

https://<deployment-name>-<owner>.zh.run

Endpoint validation

service must name an existing Compose service.
port must be between 1 and 65535.
web must be present, even when its value is false.
expose must contain at least one entry. Use an entry without label for the main hostname and custom-domain target. Labels must be unique.
forward_auth, when present, must be a boolean. Omission and false both leave the endpoint without Zenith-provided forward authentication.
Development preview sessions reject forward_auth: true.

The exposed endpoint uses HTTP routing with TLS terminated by Zenith. web: false does not create a raw TCP or UDP endpoint.

The primary endpoint is also the target for a verified custom domain.

Forward authentication

x-zenith.expose[].forward_auth: true requires the deployment owner’s Zenith account before requests reach that HTTP endpoint. The following fragment protects the primary endpoint and a labelled endpoint. It leaves a third endpoint without Zenith forward authentication:

x-zenith:
  expose:
    - { service: web, port: 3000, web: true, forward_auth: true }
    - { service: admin, port: 3001, label: admin, web: true, forward_auth: true }
    - { service: api, port: 8080, label: api, web: false, forward_auth: false }

The fragment omits the required catalogue and service definitions. Omitting forward_auth on the api entry has the same effect as setting it to false.

Interaction	Behavior
Scope	Applies to every path on that exposed HTTP hostname. There are no per-path exemptions.
Multiple endpoints	Each entry has its own setting. Protecting one endpoint does not protect other entries, including entries for the same service.
Custom domain	Inherits the primary endpoint’s setting. It has no separate `forward_auth` property.
`web: false`	Still uses HTTP routing and still enforces `forward_auth: true`. It does not create a raw TCP or UDP authentication layer.
App authentication	Remains separate. Zenith checks access to the endpoint but does not create an app account or replace the app’s own login.
File-manager access	Remains separately authorized. This field applies to app endpoints, not storage access.
Local Docker Compose	Ignores `x-zenith`; it does not enforce this sign-in check.
Development previews	Reject `forward_auth: true`.

An unauthenticated browser navigation goes to Zenith sign-in. After authentication, the owner confirms the destination with Open app before returning to the original app URL.
An incorrect password stays on the login page with the normal credential error. A valid sign-in from a different account receives access denied.
Unauthenticated API requests and WebSocket upgrades are denied rather than redirected to an interactive login. Do not use this option on public webhook endpoints or APIs that need unauthenticated clients.
Existing app cookies and application Authorization headers are preserved. A Zenith dashboard session is not an API credential for the protected endpoint.
If Zenith cannot validate access, requests are denied rather than sent to the app without authentication.
Signing out of all Zenith sessions revokes protected-app access. Ordinary dashboard sign-out does not revoke an existing protected-app session.

Treat every exposed hostname as a separate access decision. An unprotected endpoint can still reach the same private data as a protected endpoint. Forward authentication is not a substitute for reviewing your app’s routes and permissions.

For setup, see Protect an app with forward authentication.

`storage`

For setup and file-manager access, see Persistent storage and files. storage is a map keyed by a stable storage ID. Each value describes a top-level Compose named volume.

x-zenith:
  storage:
    uploads:
      volume: app_uploads
      label: Uploaded files
      description: Files uploaded by app users.
      public: true

services:
  app:
    image: ghcr.io/example/app:1.0.0
    volumes:
      - app_uploads:/app/uploads

volumes:
  app_uploads:

Field	Type	Required	Description
Map key	string	Yes	Stable storage ID used by Zenith’s deployment API and file manager.
`volume`	string	Yes	Name of the top-level Compose volume this entry describes.
`label`	string	No	Owner-facing storage name.
`description`	string	No	Owner-facing description of the stored data.
`public`	boolean	No	Marks the volume as eligible for owner file-manager access where supported.

The schema defines the metadata shape only. Persistent-volume allocation, directory naming, and sizing are deployment behaviors outside this schema.

Public storage validation

When public is true:

volume must be set.
The named volume must exist in the top-level Compose volumes map.
The volume cannot be external.
No other public storage entry may reference the same volume.

The volume does not need to be mounted by a service for the manifest to validate.

Use public: true only for files an app owner should browse or edit. Do not expose database files, indexes, or credentials.

`x-zenith.configs`

x-zenith.configs exposes specific files in named volumes through the deployment’s configuration editor. Follow Expose configuration files for setup instructions.

x-zenith:
  storage:
    settings:
      volume: app_settings
  configs:
    - storage: settings
      path: /config.ini
      label: Server settings
      description: Example server settings.
      type: ini

Field	Type	Required	Default	Behavior
`storage`	string	Yes, to expose an editor	Empty	An `x-zenith.storage` ID backed by a managed named volume.
`path`	string	Yes, when `storage` is set	Empty	Canonical absolute file path relative to the volume root.
`label`	string	No	`path`	Owner-facing name for the file.
`description`	string	No	Empty	Explanation shown with the editor.
`type`	string	No	Filename extension, then plain text	Syntax-highlighting hint, such as `yaml`, `json`, `ini`, or `toml`. It does not validate the contents.

The example assumes app_settings is declared under top-level volumes. If it is mounted at /etc/example, /config.ini refers to /etc/example/config.ini in that container.

Configuration validation and behavior

storage must reference an existing storage entry whose volume is a declared, non-external named volume.
path must identify a file within that volume. /, parent traversal, repeated slashes, backslashes, control characters, trailing slashes, and the .zenith-files-tmp and .file-manager-tmp path segments are rejected.
Each volume and path pair must be unique, including across storage entries that reference the same volume.
The file must already exist and contain UTF-8 text without null bytes. Zenith does not create it from the declaration.
The volume can remain private. Configuration access covers only the declared file; storage.public: true separately enables the volume’s file manager.
Applying changes saves the file, then requests an app restart. If the restart request fails, the file remains saved and the owner can retry the restart.
Entries without storage remain legacy metadata and do not expose an editor.

This block is separate from standard Compose configs, which supplies read-only files from inline content. A file mounted directly from a Compose config is not writable through this editor.

`env`

For setup examples, see Environment variables and secrets. env is a map from a container environment variable name to an environment declaration.

x-zenith:
  env:
    APP_URL: ZENITH_PUBLIC_URL
    ADMIN_EMAIL:
      input:
        label: Administrator email
        default_template: '{ZENITH_OWNER_EMAIL}'
        required: true
        validator: '[^@]+@[^@]+'
    APP_SECRET:
      generate: '([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})'
      input:
        label: App secret
        secret: true
      services:
        - web

The map key is the literal variable name injected into the container. It must match:

^[A-Za-z_][A-Za-z0-9_]*$

The name must not collide with a Zenith-reserved variable. Zenith also rejects PATH, every LD_* name, and environment variables that can make a loader or interpreter execute user-selected code: NODE_OPTIONS, PYTHONPATH, PYTHONSTARTUP, PYTHONHOME, BASH_ENV, ENV, JAVA_TOOL_OPTIONS, _JAVA_OPTIONS, RUBYOPT, PERL5LIB, and PERL5OPT. Set a fixed value under the service’s Compose environment block when the app requires one of these names.

Environment declaration

Field	Type	Required	Default	Behavior
`input`	object	Conditional	None	Makes the value editable and supplies validation and display metadata. It can also be the value source.
`generate`	string	Conditional	None	RE2 pattern used to mint a stable value.
`template`	string	Conditional	None	String containing `{NAME}` references, resolved on every render.
`alias`	string	Conditional	None	Name of another declaration or Zenith built-in, resolved on every render.
`services`	list of strings	No	All services	Limits injection to the listed Compose services.
`legacy`	string	No	Empty	Pre-v1 migration key for a generated value. Do not use it for a new app.
`transform`	string	No	Empty	Applies `argon2id` or `urlencode` after resolution.

Every declaration must contain input or exactly one computed source: generate, template, or alias. The computed source fields are mutually exclusive. A bare string is shorthand for alias:

x-zenith:
  env:
    APP_URL: ZENITH_PUBLIC_URL

This is equivalent to:

x-zenith:
  env:
    APP_URL:
      alias: ZENITH_PUBLIC_URL

`input`

Field	Type	Required	Default	Behavior
`label`	string	No	Environment variable name	Label shown in the deployment environment editor.
`description`	string	No	Empty	Help text shown with the value.
`default`	string	No	Empty	Initial literal value for an input-only declaration. Stored on first non-empty resolution.
`required`	boolean	No	`false`	Fails rendering when the raw resolved value is empty.
`validator`	string	No	Empty	RE2 pattern matched against the complete raw value.
`default_template`	string	No	Empty	Initial templated value. It is resolved and stored once, then stops tracking its references.
`secret`	boolean	No	`false`	Masks a non-generated value in the environment editor.

default and default_template are mutually exclusive. Neither may be used when the same declaration has generate, template, or alias. Submission validation resolves declarations with deterministic test deployment data and no owner-entered values. An input marked required: true must therefore resolve non-empty from default, default_template, or a computed source. A required input with none of these is rejected before the deployment editor can ask the owner for it. A static default that uses an address at zenith.hosting, example.com, example.org, or example.net fails submission validation. To create an account with the deployment owner’s address, use default_template: '{ZENITH_OWNER_EMAIL}'. An input attached to a computed source adds display metadata and validation. It also makes the field available in the deployment editor. A generated input accepts an owner replacement because its stored raw value is the source. An alias or template remains source-driven and resolves again on every render. An input-only declaration uses the stored owner value or its default. Environment values are limited to 4096 bytes when set through the deployment editor. Clearing an input-only value resets it to its declared default on the next render. A computed input cannot be cleared to an empty value; it must be replaced with another value. A declaration without input is not owner-editable.

Resolution sources

Source	First render	Later renders	Stored value
Input only	Owner value, otherwise `default` or `default_template`	Reuses the stored value unless the owner changes or clears it	Raw value
`generate`	Mints from the RE2 pattern	Reuses the original value	Raw generated value
`alias`	Resolves the target	Resolves the target again	Latest value is stamped for display, but not used as the next source
`template`	Substitutes all references	Substitutes all references again	Stored only when paired with `input`, for display

Generated and defaulted values are stable for the lifetime of a deployment. Changing a generator pattern or input default does not rotate a value already stored by an existing deployment.

Aliases and templates are dynamic. They track changes such as a newly verified custom domain. Resolution is dependency-aware and order-independent. An alias or template may reference a declaration written later in the YAML map. Unknown references and dependency cycles fail validation.

`generate`

generate accepts an RE2 regular expression. Zenith expands it into a deterministic value and stores the result.

x-zenith:
  env:
    DATABASE_PASSWORD:
      generate: '([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})'

The pattern must be non-empty, compile under RE2, and produce a non-empty value. Independent capture groups contribute separately to generated secrets. Zenith currently does not enforce a minimum entropy threshold. Generation is deterministic for one deployment and pattern, but the stored value is authoritative. Normal rendering reuses the stored value.

`template`

template substitutes {NAME} references with declarations or built-ins on every render.

x-zenith:
  env:
    API_URL:
      template: '{ZENITH_PUBLIC_URL}/api'

Reference names use the same environment-name grammar. Write {{ when you need a literal { before text that could otherwise be parsed as a reference. An empty template fails validation.

`alias`

alias copies another declaration or built-in on every render.

x-zenith:
  env:
    APP_HOST:
      alias: ZENITH_PUBLIC_HOST

The target must exist and must not create a dependency cycle.

`services`

Without services, Zenith injects a declared value into every Compose service. With services, every listed name must exist and the value is injected only into those services.

x-zenith:
  env:
    DATABASE_PASSWORD:
      generate: '([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})'
      services:
        - web
        - database

An x-zenith.env value replaces a Compose environment value with the same name in every targeted service. Owners may also add undeclared environment variables to a deployment. Zenith injects those variables only into services marked by an expose entry with web: true. If no exposed endpoint has web: true, Zenith injects them into every service.

`transform`

Transforms run after the raw source is resolved and validated. The raw value remains stored and visible according to the input rules. The transformed value is injected and is the value referenced by downstream aliases and templates.

Value	Allowed sources	Result
`argon2id`	Input only or `generate`	Argon2id PHC string using `m=19456`, `t=2`, `p=1`, a 32-byte key, and a stable 16-byte deployment-specific salt.
`urlencode`	Any source	RFC 3986 component encoding. Spaces become `%20`.

Use urlencode on one URL component, such as an SMTP username or password. Do not apply it to a complete URL. An unknown transform fails validation. argon2id on alias or template also fails validation.

`legacy`

legacy migrates a stored value from Zenith’s pre-v1 {{ZENITH_*}} token system into a generated declaration.

x-zenith:
  env:
    DATABASE_PASSWORD:
      generate: '([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})([A-Za-z0-9]{11})'
      legacy: ZENITH_RANDOM0

legacy applies to apps with deployments that use the pre-v1 token system. New apps do not need this field. The supported migration value is the old token name without braces. The old inline token syntax is no longer expanded. A rendered value containing {{ZENITH_ fails submission validation.

Built-ins

Built-ins are resolved for each deployment. Zenith does not inject them automatically. Declare an alias or template when the app needs one.

Name	Value
`ZENITH_PUBLIC_URL`	Verified custom-domain URL when present; otherwise the canonical Zenith URL.
`ZENITH_PUBLIC_HOST`	Authority from `ZENITH_PUBLIC_URL`, including a port when present.
`ZENITH_PUBLIC_URLS`	Canonical Zenith URL and verified custom-domain URL, comma-separated.
`ZENITH_PUBLIC_HOSTS`	Canonical Zenith authority and verified custom-domain authority, comma-separated.
`ZENITH_PUBLIC_HOSTNAME`	Hostname from `ZENITH_PUBLIC_URL`, without a port.
`ZENITH_PUBLIC_HOSTNAMES`	Canonical Zenith hostname and verified custom-domain hostname, comma-separated and without ports.
`ZENITH_CUSTOMER_ID`	Immutable Zenith customer ID of the deployment owner.
`ZENITH_PUBLIC_URL_<LABEL>`	Canonical URL for a labelled endpoint. Labels are uppercased and hyphens become underscores.
`ZENITH_OWNER_EMAIL`	Deployment owner’s account email, or empty when unavailable.
`ZENITH_SMTP_HOST`	`smtp.zenithusercontent.com`.
`ZENITH_SMTP_PORT`	`587`.
`ZENITH_SMTP_FROM`	Sender address assigned by the deployment’s Zenith region.
`ZENITH_SMTP_DISPLAY`	Canonical Zenith hostname, even when a custom domain is verified.
`ZENITH_SMTP_USER`	Deployment-specific SMTP username.
`ZENITH_SMTP_PASS`	Deployment-specific SMTP password.

Follow SMTP email to configure the relay, authentication, and STARTTLS. The OIDC reference lists the OIDC credential built-ins. ZENITH_OWNER_EMAIL can be empty. Use it with default_template when creating an owner account. The value is stored only after it resolves non-empty. x-zenith.sign_in registers your app’s OpenID Connect callbacks with Zenith. Your app must implement or enable an OIDC client.

Field	Type	Required	Default	Behavior
`redirect_paths`	list of strings	Yes, when `sign_in` is present	None	One to eight unique, exact callback paths starting with `/`.
`owner_id_env`	string	No	Unset	Name of a plain `x-zenith.env` input used to seed the owner’s local account ID on fresh deployments.

For setup, callback restrictions, credential built-ins, owner linking, and protocol behavior, see Sign in with Zenith.

Preview policy

zenith check --upload-size validates the local project against preview policy and estimates upload size. zenith up uploads it for server validation and a temporary build. These commands do not validate the entire published runtime contract below. Preview source builds require:

Exactly one service using build: . and the root Dockerfile, without image on that service.
Publicly pullable image references for the other services.
A primary x-zenith.expose entry with web: true and no label.

Dockerfile EXPOSE is optional. The expose entry declares the routed port. Previews support the public env, storage, and configs blocks, named volumes, and inline Compose configs. forward_auth: true is unsupported in previews. Compose interpolation uses an empty host environment. $$ preserves a literal dollar sign. Local test secrets come from .env.local, which the CLI validates and sends separately from the source archive. External file references, bind mounts, and unsupported build options fail validation. The CLI also rejects inline secret content and privileged: true. Acceptance of a Compose field does not guarantee runtime support. These limits do not redefine the shared schema or published runtime. In particular, an image-only published manifest is not a valid preview project just because its images are pullable. See temporary previews for the full workflow and lifecycle.

Compose compatibility

This section describes the published runtime, not the stricter preview policy. Zenith uses the Compose model for service definitions, then maps a defined subset to its runtime. Every service becomes one independently managed workload.

Service fields

Compose field	Zenith behavior
`image`	Published workloads run images. For image-based services, declare a publicly pullable image and pin a tag or digest. The supported publishing build path supplies the app image before review.
`build`	Set `build: .` on one app service without `image`; other services need public images. CLI publishing uses a verified matching preview image or builds the pinned public GitHub commit before review. This is a pre-review build, not a runtime Compose build. See Build and host features.
`entrypoint`	Becomes the container command.
`command`	Becomes the container arguments.
`environment`	Injected as literal container environment values. Targeted `x-zenith.env` values take precedence.
`configs`	Mounts referenced top-level inline Compose configs as read-only files. Short and long service syntax are supported.
`ports`	Declares container and internal service ports. An `x-zenith.expose` port is added automatically when absent. Host IP binding has no Zenith meaning.
`volumes`	Named and anonymous volume mounts become persistent storage. `tmpfs` mounts remain memory-backed and ephemeral. Bind mounts are rejected during developer submission.
`secrets`	Service secret references are mounted read-only. Their default target is `/run/secrets/<source>`. Only inline top-level content is supported; it is visible in the public repository and must not contain private credentials.
`healthcheck`	Becomes startup, readiness, and liveness checks. `CMD` and `CMD-SHELL` are supported. `NONE` or `disable: true` disables checks.
`depends_on`	Only long-form `condition: service_healthy` creates a wait. `service_started` and `service_completed_successfully` do not create runtime ordering.
`deploy.replicas`	Sets the number of service replicas. Default: `1`.
`deploy.resources.limits`	Sets CPU and memory limits.
`deploy.resources.reservations`	Sets CPU and memory requests.
`working_dir`	Sets the container working directory.
`stdin_open`	Keeps standard input open.
`tty`	Allocates a TTY.
`user`	Numeric `uid` or `uid:gid` values set the runtime user and group. Named users are not translated.
`read_only`	Makes the container root filesystem read-only. Declared mounts remain available.
`cap_drop`	Removes Linux capabilities from the container.
`cap_add`	Adds specific Linux capabilities; it does not enable `privileged` mode. Avoid it unless your app needs it. Some capabilities weaken isolation or may be rejected by the cluster.
`privileged`	`privileged: true` is not supported. Submission fails if you set it.

Services resolve each other by service name inside the deployment. ports does not limit which ports sibling services can reach.

Health checks

Compose health checks are exec-based in Zenith:

CMD runs the argument list directly.
CMD-SHELL runs through /bin/sh -c.
interval, timeout, and retries map to probe timing.
start_period creates a startup probe budget.
Readiness uses a failure threshold of 3.

Public traffic is sent only to service replicas that pass readiness. A dependency using condition: service_healthy waits for the same readiness signal.

Persistent volumes

Top-level, non-external named volumes share one persistent allocation. Each volume receives its own stable subdirectory. Anonymous volume mounts are also persistent and receive stable subdirectories derived from the service name and target path. External volumes do not create Zenith storage. Do not rely on an external volume being present in the deployment.

Compose configs

For a complete app example, see Static configuration files. Use standard top-level Compose configs to deliver a static, non-secret file. Define each config with inline content, then reference it from every service that needs the file.

zenith-compose.yml

services:
  app:
    image: ghcr.io/example/app:1.0.0
    configs:
      - source: app-settings
        target: /etc/example/settings.yaml
        mode: 0440

configs:
  app-settings:
    content: |
      log_level: info

For an editable file, create a copy in a named volume and declare it under x-zenith.configs. See Expose configuration files.

Top-level config definition

Field	Type	Required	Default	Behavior
Map key	string	Yes	None	Config source name used by service references.
`content`	string	Yes	None	Static, non-secret file content. It counts toward the `128 KiB` manifest limit. Set `content: ''` when you intentionally need an empty file.

Only the inline content source is supported. Compose rejects a config definition with no source, so content must be present even when its value is empty. Zenith rejects file, external, environment, driver, driver_opts, and template_driver config sources.

Service config reference

A service can use short or long syntax:

services:
  app:
    configs:
      - app-settings
      - source: logging-settings
        target: /etc/example/logging.yaml
        mode: 0440

Field	Type	Required	Default	Behavior
Short value	string	Yes for short syntax	None	Names a top-level config and mounts it at `/<source>`.
`source`	string	Yes for long syntax	None	Names an existing top-level config.
`target`	string	No	`/<source>`	Absolute file path inside the container. It must be non-empty and must not end in `/`.
`mode`	octal file mode	No	Kubernetes ConfigMap default, `0644`	Sets the mounted file mode. Quote it if your YAML tooling would otherwise convert the octal value.
`uid`, `gid`	string	Unsupported	None	Rejected because ConfigMap mounts cannot remap file ownership.

Each reference is service-scoped. A service receives only the configs it names. A config target must not collide with another config, volume, tmpfs, or secret mount in the same service. Unknown sources fail validation. The mounted file is read-only and uses subPath. Zenith performs no runtime substitution inside content, including no x-zenith.env substitution. Standard Compose interpolation still runs while the manifest loads, so write $$ when the mounted file must contain a literal $. Do not put passwords, tokens, or private keys in configs.content or inline secrets.content. Both are part of the public manifest. Use generated or owner-provided deployment environment values for private credentials. When Zenith applies an updated app definition, a content change restarts only the services that consume that config. The file is not hot-reloaded in an existing container. A Git push does not update a submission or deployment automatically. Submit and apply the new definition through the normal workflow.

Zenith runtime restrictions

Some valid Compose settings do not work on Zenith. Use the supported service fields above and check these restrictions before submitting. The preview policy adds further restrictions for zenith check and zenith up. Published runtime configuration cannot read repository or host files. The supported publishing build can read its pinned source, but that does not make file-backed runtime configuration available. Therefore:

Top-level secrets.<name>.file is rejected.
Top-level configs.<name>.file and every other non-inline config source are rejected.
Service env_file and label_file are rejected.
Service extends is rejected.
Top-level include is rejected.
Service privileged: true is rejected.

Other Compose fields may parse, but Zenith does not guarantee that they will work.

Files in your public repository are public, even if you put them in secrets.content. Never put passwords or keys in an inline config or secret. Use deployment environment values for private credentials.

Build and host features

The runtime runs images. It does not execute Compose builds. With zenith publish, an app using build: . and a root Dockerfile can be built from the pinned public GitHub commit before review. You do not need to publish that app image to GHCR yourself. A manifest using publicly pullable images remains supported.Do not infer support for arbitrary build contexts, alternate Dockerfiles, build options, or multiple build services from this publishing path. The CLI waits for the publish artifact before submitting. Zenith can reuse a successful preview image when its source matches the pinned commit.Bind mounts are rejected. The running deployment cannot read a path from the GitHub repository or Zenith host. Use an inline Compose config for static non-secret content, deployment environment values for credentials, or a named volume for mutable data. Do not commit secrets to the public repository.

Submission validation

CLI publishing checks the selected public GitHub commit and publishing authorization. When a publish build is required, the CLI waits for it to succeed before submitting the app for review. See publishing for account prerequisites, metadata, screenshots, and revision commands. Zenith also validates the manifest before accepting the app for review:

Fetch the root zenith-compose.yml from the selected pinned commit.
Enforce the non-empty 128 KiB file limit.
Reject external file references, unsupported config sources, and bind mounts.
Load the Compose project with an empty host environment and discard environment files.
Parse x-zenith strictly.
Validate required catalogue and endpoint fields.
Resolve every x-zenith.env declaration against deterministic test deployment data.
Reject services with privileged: true.
Render the complete app and reject invalid or duplicate runtime object names.
Reject unresolved pre-v1 {{ZENITH_*}} tokens.

Schema validation

The schema requires these fields:

A top-level services map.
A top-level x-zenith map.
x-zenith.catalog with name, description, authors, tags, source, and license.
At least one x-zenith.expose entry.
x-zenith.expose entries with service, port, and web.
x-zenith.storage entries with volume.
x-zenith.configs entries with path.
x-zenith.env keys matching the environment-name pattern and declarations containing an input or one computed source.

The schema rejects unknown fields inside x-zenith, rejects unknown top-level fields unless they begin with x-, and enforces the documented name, URI, enum, uniqueness, and numeric range constraints. A deployment target may impose additional checks. Runtime validation also rejects:

An empty Compose service set.
A runtime service without an image after any supported publish build has been resolved.
Endpoint references to missing services.
Invalid or colliding service names.
Colliding persistent-volume directory names.
Unknown config references, unsupported config sources or ownership, invalid config targets, and config mount collisions.
Invalid public storage references.
Invalid environment declarations.

Passing validation makes the app eligible for review. It does not publish the app automatically.

x-zenith defaults

Setting	Default or constraint
`expose[].forward_auth`	`false` when omitted.
`storage.public`	`false` when omitted.
`env.services`	Every Compose service when omitted.
`input.label`	The environment variable name when omitted.
`input.required`	`false` when omitted.
`input.secret`	`false` when omitted.
`x-zenith.expose`	At least one entry is required.
Service replicas	`1` when omitted.
Compose config mount target	`/<source>` when omitted.
Compose config file mode	Kubernetes ConfigMap default, `0644`, when omitted.
Secret mount target	`/run/secrets/<source>` when omitted.

Build the file

Return to the step-by-step guide.

Start here

CLI workflow

App configuration

App integrations

zenith-compose.yml reference

File requirements

Document shape

`catalog`

`expose`

Endpoint validation

Forward authentication

`storage`

Public storage validation

`x-zenith.configs`

Configuration validation and behavior

`env`

Environment declaration

`input`

Resolution sources

`generate`

`template`

`alias`

`services`

`transform`

`legacy`

Built-ins

Preview policy

Compose compatibility

Service fields

Health checks

Persistent volumes

Compose configs

Top-level config definition

Service config reference

Zenith runtime restrictions

Build and host features

Submission validation

Schema validation

x-zenith defaults

Build the file

​File requirements

​Document shape

​catalog

​expose

​Endpoint validation

​Forward authentication

​Sign-in and request behavior

​storage

​Public storage validation

​x-zenith.configs

​Configuration validation and behavior

​env

​Environment declaration

​input

​Resolution sources

​generate

​template

​alias

​services

​transform

​legacy

​Built-ins

​Sign in

​Preview policy

​Compose compatibility

​Service fields

​Health checks

​Persistent volumes

​Compose configs

​Top-level config definition

​Service config reference

​Zenith runtime restrictions

​Build and host features

​Submission validation

​Schema validation

​x-zenith defaults

Build the file

File requirements

Document shape

`catalog`

`expose`

Endpoint validation

Forward authentication

Sign-in and request behavior

`storage`

Public storage validation

`x-zenith.configs`

Configuration validation and behavior

`env`

Environment declaration

`input`

Resolution sources

`generate`

`template`

`alias`

`services`

`transform`

`legacy`

Built-ins

Sign in

Preview policy

Compose compatibility

Service fields

Health checks

Persistent volumes

Compose configs

Top-level config definition

Service config reference

Zenith runtime restrictions

Build and host features

Submission validation

Schema validation

x-zenith defaults