OCI image deployment

Use OCI images when your application is already packaged outside Zenifra. This flow is recommended for CI pipelines that build the image, publish it to a registry, and promote versions by tag.

When to choose OCI

Choose OCI when:

• your team already uses Docker in production
• the image is generated by GitHub Actions, GitLab CI, Jenkins, or another pipeline
• you want to promote specific tags between environments
• build steps should not run inside Zenifra
• the application must keep the same artifact across platforms

For projects that evolve directly from source code, see GitHub Deployment.

Image requirements

The image must:

• expose a long-running HTTP process
• listen on 0.0.0.0
• use the port configured in the Zenifra project
• must not run the main process as root; use a non-privileged user
• listen on a port compatible with a non-privileged user, such as 8080, when the image cannot open ports below 1024
• receive configuration through environment variables
• start without depending on local files outside the image or configured volume

Avoid generic tags like latest in production. Prefer tags such as 1.4.2, 2026-05-16, or the commit SHA.

For NGINX, use an image that already runs without root privileges, such as:

docker.io/nginxinc/nginx-unprivileged:stable-alpine

In this case, configure the project port according to the port exposed by the image, usually 8080, unless you have customized the container configuration.

Create the project

In the console:

1. click Create Project
2. choose OCI Image as source
3. enter the image, for example ghcr.io/acme/api:1.4.2
4. select whether the image is public or private
5. configure the application port
6. add environment variables
7. choose plan, instances, and storage
8. create the project and follow the logs

Update the image

To publish a new version:

1. generate a new image in your pipeline
2. publish the tag to the registry
3. change the project image in the console
4. validate logs, metrics, and public URL

If the image is private, keep the same authentication type defined during creation. For details, see Private registry.

Validation

After publication, confirm:

• the *.clients.zenifra.com URL responds
• the /health route returns success, if it exists
• logs do not show startup errors
• CPU, RAM, storage, and HTTP requests appear according to plan
• DATABASE_URL and other variables were manually configured

Next steps

• Private registry
• Ports and health checks
• Rollback

FAQ

Can I convert an OCI project to GitHub later?

A project created with OCI source remains an OCI project; this conversion is not part of the normal flow.

Can I use a private image?

Yes. The current documentation covers authentication through AWS ECR or registry user and token/password.

Should I use latest?

Avoid it in production. Immutable tags make rollback, audit, and support more predictable.