Guides
Deploy an image
Available This guide deploys a public image, updates it and removes it. It assumes a server set up as in the Quick start, with the daemon running, and that you work as root on the server. (Available With a context you can run the same commands from another machine.)
Write the manifest
project = "blog"
[service.web]
image = "ghcr.io/example/blog:2.3.0"
replicas = 2
resources = { cpu = 0.5, memory = "256M" }
env.LOG_LEVEL = "info"
project: blog
service:
web:
image: ghcr.io/example/blog:2.3.0
replicas: 2
resources: { cpu: 0.5, memory: 256M }
env:
LOG_LEVEL: info
Replace the image with one you can pull anonymously. Pin a version tag or a
digest (image@sha256:…) rather than latest, so a redeploy runs what you
expect.
podos manifest validate
podos deploy
What happens
- The CLI checks the manifest and sends the resolved manifest to the daemon.
- The daemon pulls the image for the server's platform. Every blob is verified against its digest; layers are unpacked safely (no path traversal, no device nodes, no links that escape the image).
- It creates and starts the containers, each under its own
conmonsupervisor, with the CPU and memory limits you set. - When the containers are still running after a few seconds, the release becomes active.
podos ps
podos logs web --tail 50
--tail also has the short form -t.
Update
Change the tag and deploy again:
podos deploy
A new release is created. Its containers start next to the old ones; when they run, the old containers are removed. If the new containers fail, they are removed, the command exits with code 1 and shows the last lines of their output, and the previous release keeps running.
Available Updates are rolling: a new replica is started before an old one is
stopped. With a health check, a replica receives
traffic only once the check passes:
[service.web]
image = "ghcr.io/example/blog:2.3.1"
port = 8080
health = "/healthz"
service:
web:
image: ghcr.io/example/blog:2.3.1
port: 8080
health: /healthz
If a service has no ready replica for 15 seconds within 60 seconds after
the new release became active, it is rolled back to the previous release
automatically. podos releases shows the failed release and the reason.
Scale
Change replicas and deploy. replicas = 0 keeps the service in the
release but runs no containers.
Remove
podos down
This removes the containers and deletes the environment with its values and
secrets. It asks you to type the environment name first; --yes (-y) skips that
for scripts. Available It also removes the environment's network, domains and
published ports. Volume data stays on the server unless you pass
--delete-volumes.
Troubleshooting
| Symptom | Cause |
|---|---|
| Exit code 1, "is not set in …" | The manifest references ${env.X} or ${secret.X} that is not set in this environment. Set it and deploy again. |
| Exit code 1, the container exited | The process ended within the first seconds. The error shows its last output lines; run it locally to see why. Every service must keep running. |
| Exit code 1, a message that building needs BuildKit | Available A service uses build and the server has no BuildKit or a crun older than 1.15. Install them with the install script, or use image. See Build from source. |
| Exit code 1, "port tcp/N cannot be published on this server" | Available A publish port is used by SSH, the proxy, the API, another program or another environment, or is reserved. The message is the same for every reason; the daemon log has the exact one. Pick another port. |
| Exit code 1, "not enough free disk space on the server" | Available The data directory's file system has less free space than the disk guard allows (--min-free-disk). Free some space. A pull can also fail with "there is not enough free disk space on this server to pull …". Running containers are not stopped. |
| Exit code 1, "the memory limit is larger than this server can give to containers" | Available resources.memory of a service is more than the server's memory minus the system reserve. Lower it, or see Limits. |
| Exit code 1, "set replicas to 1" | Available A service with publish has more than one replica. |
| Exit code 1, a certificate "does not exist" | Available tls = "cert:NAME" names a certificate that is not uploaded. Upload it with podos cert set. |
| Exit code 1, the release failed and was rolled back | Available The new replicas were not ready (for example the health check failed). podos releases --full shows the reason; podos logs shows the output. |
| Containers have no internet or no service names, or a published port or a domain cannot be reached from outside, on a server with Docker, ufw or firewalld (a deploy still reports success) | Available The firewall drops forwarded or incoming packets by default, including Podos traffic. podos setup and the daemon log warn about it and print the commands. See Next to Docker or another firewall. |
| Exit code 3 | The daemon is not reachable, or another deployment of this environment is running. Check podos ps and try again. |
| A container stopped after the deployment | Available It is restarted according to restart, with a growing delay; podos ps shows READY and RESTARTS. A server set up with M2 did not restart it: deploy again to recover. |