Skip to main content
The CLI can build your app on Zenith. You do not need to publish an image to a registry before using zenith up or publishing an app with build: ..
A root Dockerfile is required for build: .. Image-only submissions use the declared public images and do not require a Dockerfile.
Image-based dependencies, such as Postgres or Redis, must also be publicly pullable. Zenith reuses a preview image only after verifying that its source matches the pinned publish commit.

​
Prepare a Dockerfile

From your app’s root directory, run:
The CLI adds missing files for a detected or selected framework. It preserves an existing Dockerfile and zenith-compose.yml unless you use --force. Reuse your production Dockerfile where possible. Review the generated start command, port, build steps, and runtime dependencies.

Install the CLI

Set up the CLI and choose a framework starter.

Docker framework guides

Adapt the container build to your language and framework.

​
Check the runtime

Use images that support linux/amd64. Configure HTTP services to listen on 0.0.0.0. Configure each service to:
  • Write logs to stdout and stderr.
  • Start without host-mounted source files.
  • Read deployment-specific values and secrets from environment variables.
  • Store persistent data in declared volumes.
Use static configuration files for static, non-secret files. Record the app’s listening port, health endpoint, required variables, and data paths in zenith-compose.yml.
Do not copy .env files, private keys, or registry credentials into an image. Use a gitignored .env.local for preview secrets and x-zenith.env for environment variables and secrets.
For a Zenith-built app, set build: . on one service and do not also set image. Other services need public image references. Zenith prepares the image before submission. It does not run Compose builds during deployment.

​
Test the build on Zenith

check validates preview policy. It does not build the image. up builds the root Dockerfile using the uploaded project. Preview builds do not support alternate Dockerfiles, build arguments, build targets, remote contexts, or bind mounts. See temporary deployments for the complete workflow. After testing, run:

​
Use an existing image

For image-based publishing or dependency services, set image to an anonymously pullable tag or digest. Pin a version rather than relying on a moving latest tag. An image-only app can be published, but it does not meet the preview requirement for one built app service. If you maintain the image yourself, publish it to a registry that permits anonymous pulls. Verify its visibility before submitting the app.

Publish to GHCR

Build and publish an image with GitHub Actions.

Publish to Docker Hub

Tag and push an image to a public Docker Hub repository.
New GHCR packages are private by default. Check GitHub’s package visibility rules before making an image public. Public packages cannot be made private again.
The container is ready when it starts without host files, answers on its declared port, and uses the expected environment variables and data paths. Every image-based service must be pullable without registry credentials.