Get started
Quick start
This page runs a first application. It takes about ten minutes, most of it building the binary. The binary you build from the current source includes the features marked Available (networking, the HTTPS proxy, health checks, remote use and more). There are no release binaries yet.
Available The five-minute version. The flow is built: run the install script on a fresh server,
podos loginfrom your laptop, thenpodos deployfrom your application directory, where a service withbuild = "."is built on the server from yourDockerfile, and open it on HTTPS. It needs the first published release, and there is none yet. Remote use withpodos loginis Available (see Several servers with contexts). Until a release exists, this page uses today's path: you build the binary yourself and set up the server as root.
What you need
- A Linux server or VM with Ubuntu 24.04 and root access. In general Podos needs Linux 5.6 or newer, systemd 245 or newer and cgroup v2, which Ubuntu 24.04 has by default.
crun,conmonandnfton the server.- On the machine where you build: Git and Go 1.26 or newer.
Install the runtime packages on the server (nftables provides nft):
sudo apt update
sudo apt install -y crun conmon nftables
1. Build the binary
There are no release binaries yet. Build a static Linux binary from the
source (set GOARCH=arm64 for an ARM server):
git clone https://github.com/podos-org/podos.git
cd podos
GOOS=linux GOARCH=amd64 make build
The binary is bin/podos. Copy it to the server, for example to
/usr/local/bin/podos, and check it:
podos version
2. Set up the server
Run podos setup once, as root. It creates the data directory
(/var/lib/podos, mode 0700), the secrets key and the state database, and
checks the kernel version and that crun, conmon, nft, systemctl and
systemd-run are installed:
sudo podos setup
Running it again changes nothing. Back up the secrets key and the database together: secrets cannot be recovered without the key.
Available You can also finish the setup in a browser instead:
podos setup --web --listen ADDR:PORT --tls-name NAME creates no admin token
and prints a one-time setup code. See Web UI. This page
keeps the command line path.
3. Start the daemon
The daemon runs in the foreground until you stop it. (Available The install script sets up a systemd unit instead, once a release exists.) Keep this terminal open:
sudo podos daemon
It listens only on a Unix socket, /run/podos/podos.sock, which only root
can use. All other commands below talk to that socket, so run them as root
in a second terminal. (Available The daemon also starts the built-in proxy on
ports 80 and 443; podos setup --ingress off turns it off. This example
does not use it.)
sudo -i
4. Write a manifest
Create an application directory with a manifest. This one runs two replicas of a small BusyBox loop that prints a greeting and a secret every second:
mkdir -p ~/hello && cd ~/hello
namespace = "hello"
[service.web]
image = "busybox:1.36"
replicas = 2
command = ["/bin/sh", "-c", "while true; do echo \"$GREETING $API_TOKEN\"; sleep 1; done"]
env = { GREETING = "hello ${env.WHO}", API_TOKEN = "${secret.API_TOKEN}" }
namespace: hello
service:
web:
image: busybox:1.36
replicas: 2
command: ["/bin/sh", "-c", "while true; do echo \"$GREETING $API_TOKEN\"; sleep 1; done"]
env:
GREETING: "hello ${env.WHO}"
API_TOKEN: "${secret.API_TOKEN}"
Save it as podos.toml (or podos.yaml; only one of the two may exist).
podos init can write a starter manifest for you instead.
Check it:
podos manifest validate
It prints podos.toml: valid and what would be deployed, or every problem
with its file, line and key.
5. Set a value and a secret
The manifest refers to ${env.WHO} and ${secret.API_TOKEN}. Both must exist
in the environment before the deployment, or podos deploy refuses it and
lists what is missing.
podos env set WHO=world
podos secret set API_TOKEN
podos secret set asks for the value twice without echo. You can also pipe
it in on standard input. Values given to podos env set appear in your
shell history, so never put secrets there.
6. Deploy
podos deploy
The daemon pulls the image, verifies every layer against its digest and starts two containers. The command follows the progress and ends with the release number and its state. Exit code 0 means the release is active.
podos ps
podos logs web --tail 5
podos logs web -f # follow; Ctrl+C stops
podos ps lists service, replica, container ID, release, status and start
time. Available It also shows READY (yes, starting or no, or - right after the daemon
starts) and RESTARTS.
In podos logs, a line from replica 0 starts with web/0.
The containers keep running when the daemon stops. Stop the daemon with
Ctrl+C, start it again, and podos ps shows the same containers.
Change the manifest (for example replicas = 1) and run podos deploy
again to roll out a new release. If the new release fails, the previous one
keeps running. Available A container that crashes is restarted with a growing
delay, and a release that never becomes healthy is rolled back
automatically; podos releases shows why.
Each environment has its own private network (Available). A second service in
this namespace could reach web by its name, for example http://web:8080/
if web listened on port 8080.
To serve a service on a domain with HTTPS, see
Domains and HTTPS.
7. Clean up
podos down
podos down asks you to type the environment name (prod), then stops and
removes the containers and deletes the environment with its values and
secrets, which cannot be recovered. The namespace is kept. Available It also
removes the environment's network, domains and published ports; volume data
is kept unless you pass --delete-volumes.
Deploy your own code
Available To deploy an application with a Dockerfile instead of a public
image, write build = "." in the service (podos init does this when it
finds a Dockerfile) and run podos deploy in that directory:
namespace = "myapp"
[service.web]
build = "."
port = 3000
namespace: myapp
service:
web:
build: .
port: 3000
podos deploy uploads the source, the server builds it with BuildKit while
the log is shown, and the release uses the image that came back. This needs
BuildKit and crun 1.15 or newer on the server. The crun that Ubuntu 24.04
ships is too old, and the apt packages above do not include BuildKit; the
install script provides both. See
Build from source.
Next steps
- Concepts explains namespaces, environments and releases.
- Environments and secrets sets up
testandprod. - Domains and HTTPS puts a service on a domain.
- Limits of this version lists what Podos does not do yet.