Operations
Install and set up a server
Requirements
| Supported | |
|---|---|
| Operating system | Ubuntu 24.04 (other systemd distributions may work; not tested). Available The install script supports Ubuntu 24.04 and 26.04. |
| Kernel features | cgroup v2, overlayfs; Available Linux 5.6 or newer |
| Init system | systemd (the daemon uses transient systemd scopes for containers); Available systemd 245 or newer |
| Packages | crun, conmon; Available nft (Ubuntu package nftables). Available The install script provides crun and conmon itself. |
For build |
Available BuildKit and crun 1.15 or newer. Ubuntu 24.04's own crun is 1.14, which is too old. The install script provides both. |
| Privileges | root (see Security model) |
| Architecture | amd64 or arm64 |
podos setup checks for crun, conmon, systemctl and systemd-run.
Available It also checks for nft and that the kernel is Linux 5.6 or newer;
it does not check the systemd version. The networking
needs the kernel, systemd and nft minimums.
Podos runs on Linux only. On macOS or Windows, use a Linux VM.
Next to Docker or another firewall
Available Podos detects Docker's, ufw's and firewalld's firewalls
dropping packets: the daemon logs a warning and podos setup prints one,
with the exact commands for the firewall it found, as described in the rest
of this section. It checks forwarded and incoming traffic.
If another firewall on the server drops packets by default, Podos traffic is dropped even though Podos accepts it. This happens on two paths:
- Forwarded traffic: containers cannot reach the internet and published ports cannot be reached from outside.
- Incoming traffic to the server itself: containers cannot resolve service names (DNS on the Podos gateway, port 53) and the ingress ports (80 and 443 by default) are closed to the outside.
Docker does this on the forward path: it sets the policy of its iptables
FORWARD chain to drop. ufw and firewalld drop both. Docker's own
containers keep working; Podos traffic does not.
Podos recognises ufw, firewalld and Docker. It changes only its own firewall
table and never changes another firewall, so it does not fix this itself. It
detects it: the daemon logs a warning at start and whenever the situation
changes, and podos setup prints a warning on standard error after its
normal output (the exit code is unchanged). The warning names the chains,
says what is dropped and prints the exact commands for the firewall it
found. An example:
warning: another firewall on this server drops packets by default:
table ip filter, chain FORWARD (forward hook, policy drop, docker)
Packets that no rule there accepts are dropped even though Podos accepts them:
forward hook: containers cannot reach the internet and published ports cannot be reached from outside;
Podos changes only its own firewall table; the owner of that firewall decides.
Docker's firewall drops forwarded packets. To let Podos traffic pass:
1. add "ip-forward-no-drop": true to /etc/docker/daemon.json
2. run iptables -P FORWARD ACCEPT
Step 1 keeps the setting after a reboot; step 2 applies it now.
This sets Docker's FORWARD policy to accept: forwarded traffic that no Docker rule drops passes, for Docker's containers as well as for Podos'.
Under ufw or firewalld, without the commands below, containers have no service names and no outbound access, and the ingress is not reachable from outside. A deploy still reports success.
ufw. The rules let everything on the Podos interfaces (names starting
with pd) be forwarded and reach the DNS port of the server, and open the
ingress ports to anyone. ufw keeps them after a reboot. With other ingress
ports (--http-listen, --https-listen), the warning names those ports
instead of 80 and 443.
sudo ufw route allow in on pd+
sudo ufw route allow out on pd+
sudo ufw allow in on pd+ to any port 53
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
firewalld. This puts every Podos interface in the trusted zone, which
accepts all traffic from them to the server and through it, and opens the
web ports to anyone. For other ingress ports, the warning prints
--add-port commands instead of the services.
sudo firewall-cmd --permanent --zone=trusted --add-interface=pd+
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload
Docker. Available Add the setting to /etc/docker/daemon.json (merge it with
any settings already there), then change the policy now:
{
"ip-forward-no-drop": true
}
sudo iptables -P FORWARD ACCEPT
Docker reads daemon.json when it starts, so the first step keeps the
setting after a Docker restart or a reboot; the second applies it now,
without restarting Docker. This has been tested with Docker 29.1.3 through a
Docker restart and a reboot.
Other firewalls: the warning gives general advice. Allow, in that
firewall, the Podos interfaces (names starting with pd): forwarding in and
out, input to port 53, and the ingress ports to the outside.
Podos looks at the default of a chain: a drop policy, or rules that end in a drop or a reject. It does not check single rules. A server whose firewall already allows the Podos interfaces can still show the warning, so the warning means that packets may be dropped, not that they are.
Install today
Available There are no release binaries yet. Build from source with Go 1.26 or newer (on any machine; the binary is static):
git clone https://github.com/podos-org/podos.git
cd podos
GOOS=linux GOARCH=amd64 make build # or GOARCH=arm64
Copy bin/podos to the server, for example to /usr/local/bin/podos.
Then, on the server:
sudo apt update
sudo apt install -y crun conmon nftables
sudo podos setup
sudo podos daemon
podos setup creates /var/lib/podos (mode 0700) with the secrets key and
the state database, and checks the host tools. Available It also creates the
internal CA and the first admin token, which it prints once, and prints the
CA fingerprint. podos daemon runs in the
foreground; run it under your own supervisor (for example a systemd service
you write). Available The install script installs a unit.
This path needs the apt packages above, and it does not give you build:
the crun from Ubuntu 24.04 is too old and BuildKit is not installed. To
get a server that can build, install a binary you built with the script, as
described next.
Build with the web UI
Available make build does not include the web UI. A
binary built that way answers on the HTTPS address with a page that says the
UI is not built in; the API and the CLI are not affected. To include the UI,
run make ui before make build:
make ui
GOOS=linux GOARCH=amd64 make build
make ui needs Node 22.22 or newer and npm. It runs npm ci and
npm run build in web/ and copies the result into the source tree that
make build embeds. make build and make test themselves need only Go.
Install a binary you built, with the script
Available The install script also installs a local binary instead of a
release, so it works today. From a clone of the repository, as root on the
server (copy the podos binary and scripts/install.sh there first):
sudo env PODOS_BINARY=/root/podos sh install.sh
PODOS_BINARY must be an absolute path to a regular file. The script then
installs the pinned crun, conmon and BuildKit from their upstream
releases, checked against SHA-256 values written into the script. The
podos binary you point at is not checked: you built it.
podos version --licenses prints the licenses of the third-party software
compiled into the binary.
Install script
Available One command on a fresh server installs the binary, pinned versions
of crun, conmon and BuildKit, and a systemd unit for the daemon, then runs
podos setup and starts the daemon. The same script upgrades and uninstalls.
There are no release binaries yet. The command below works once a release exists; until then it answers "not found". Install today by building from source. A shorter address for the script is planned.
Once a release exists:
curl -fsSL https://github.com/podos-org/podos/releases/latest/download/install.sh | sudo sh
Or download install.sh first, read it, and run it with sudo sh install.sh.
Supported: Ubuntu 24.04 and 26.04, on amd64 and arm64, with systemd as
init and cgroup v2. Anything else is refused, unless you set
PODOS_INSTALL_UNSUPPORTED=1 to try anyway; nothing is promised then.
What it installs. Every download is HTTPS only. crun, conmon and
BuildKit are pinned versions with a SHA-256 written in the script. The
podos binary is checked against the SHA-256 published with the release. A
mismatch stops the script before anything is installed. Files are replaced
atomically.
| Path | What |
|---|---|
/usr/local/bin/podos |
The program: daemon and CLI. |
/usr/local/lib/podos/bin/ |
crun 1.31, conmon v2.2.1, and BuildKit v0.35.0 (buildkitd, buildctl). Not on PATH. |
/usr/local/lib/podos/installed |
Which versions the script installed. |
/usr/local/lib/podos/podos.previous |
The binary before the last upgrade, for the rollback. |
/etc/systemd/system/podos.service |
The daemon's unit. |
/etc/modules-load.d/podos.conf |
Kernel modules loaded at boot. |
/etc/modprobe.d/podos-blacklist.conf |
Protocol modules that no Podos host needs, disabled host-wide (SCTP, DCCP, AF_ALG, RDS, TIPC, Bluetooth, CAN and others). Set PODOS_SKIP_MODPROBE_BLACKLIST=1 to skip it. |
It also installs nftables from the distribution with apt-get when nft
is missing. It needs curl.
On a server installed this way, Podos looks for crun, conmon, buildkitd
and buildctl in /usr/local/lib/podos/bin before the system path. You do
not need apt install crun conmon there. The Install today
path (a binary you copy yourself) does need those packages.
What it prints first. Before it changes anything, the script prints the list of changes it is about to make. When nothing needs changing it says so and changes nothing.
Arguments for podos setup. Everything after -- is passed to
podos setup:
curl -fsSL https://github.com/podos-org/podos/releases/latest/download/install.sh | sudo sh -s -- -- --acme-email me@example.com --listen 0.0.0.0:8443 --tls-name host.example.com
When you run a downloaded script, that is
sudo sh install.sh -- --acme-email me@example.com --listen 0.0.0.0:8443 --tls-name host.example.com.
On a server that is already set up, arguments after -- run podos setup
again with them: the daemon is stopped for it and started again, and running
containers keep running.
The admin token is shown once. A first install runs podos setup, which
prints the first admin token and the CA fingerprint once, to a terminal.
When standard output is not a terminal (a pipe into a log, for example), the
script refuses to start: run it in a terminal (over ssh: ssh -t), or set
PODOS_TOKEN_FILE=/absolute/path and podos setup writes the token to that
new file with mode 0600 instead. Nothing is changed when it refuses.
Finish the setup in a browser. Available Instead of an admin token on the terminal, the script can leave the first setup to a browser:
sudo sh install.sh -- --web --listen 0.0.0.0:8443 --tls-name host.example.com
This passes --web to podos setup. No admin token is created, so the
script needs no terminal and no PODOS_TOKEN_FILE. It prints the address, a
one-time setup code (valid 30 minutes) and the CA fingerprint of the server.
When the output is not a terminal, the code is in the script's output. Open
the address, compare the CA fingerprint with the browser's certificate
warning, and enter the code. See Web UI for the steps and
for a new code. sudo podos setup --web issues a new code while the setup is
pending.
Variables. All are optional.
| Variable | Meaning |
|---|---|
PODOS_VERSION |
Release tag to install, for example v0.1.0. Default: the latest release. |
PODOS_BINARY |
Absolute path of a local podos binary to install instead of downloading a release. |
PODOS_RELEASE_URL |
Base URL of the releases. https only. Default https://github.com/podos-org/podos/releases. |
PODOS_TOKEN_FILE |
Absolute path where podos setup writes the first admin token (mode 0600) instead of printing it. Needed when standard output is not a terminal. |
PODOS_SKIP_STATE_CHECK=1 |
Skip the check that the state database is not newer than the new binary. |
PODOS_INSTALL_UNSUPPORTED=1 |
Try an operating system or architecture the script refuses. |
PODOS_SKIP_MODPROBE_BLACKLIST=1 |
Do not write /etc/modprobe.d/podos-blacklist.conf. An existing one is left alone. |
PODOS_WAIT_SECONDS |
How long to wait for the daemon to answer after a start. Default 300. |
Running it again on an up-to-date server prints that Podos is already installed and changes nothing. To upgrade, see Upgrade and backup.
The unit. It starts podos daemon without flags: the settings come from
podos setup. It restarts the daemon on failure, writes no core dumps, and
runs with a reduced capability set (it drops, among others, the capabilities
to load kernel modules, set the time, reboot and read the audit log). Stopping or
restarting the unit never stops containers: they run in their own systemd
scopes. The file is replaced on upgrade; put changes in a drop-in file
(systemctl edit podos).
Uninstall
sudo sh install.sh uninstall
This stops and disables the daemon and removes the unit, /usr/local/bin/podos,
the files in /usr/local/lib/podos that the script installed, and the two
files in /etc/modules-load.d and /etc/modprobe.d. It keeps
/var/lib/podos (database, secrets key, images, volumes). It does not
stop running containers: they keep running without a daemon, and nothing
restarts, routes or supervises them until you install Podos again, which
adopts them.
sudo sh install.sh uninstall --purge
--purge also stops and removes all containers, deletes the Podos firewall
table and network interfaces, and deletes /var/lib/podos and /run/podos
with all data, including the secrets key. This cannot be undone. When
the data directory is a mount point of its own (a dedicated disk), its
content is deleted and the mount point stays. At the end the script lists
anything of Podos that is still there.
Files and directories
| Path | Content |
|---|---|
/var/lib/podos |
Data directory: state database, secrets key, images, container root filesystems and logs. Mode 0700. Override with --data-dir or PODOS_DATA_DIR. |
/run/podos/podos.sock |
The daemon's Unix socket, mode 0600, root only. Override the directory with --run-dir or PODOS_RUN_DIR. |
Remote access
Available By default the daemon opens no TCP port. With --listen ADDR:PORT
(or podos setup --listen) it also serves the API over HTTPS, with a
certificate from the internal CA for the --tls-name names. You choose the
port, for example 8443, and open it in the server's firewall. See
Several servers with contexts.
Upgrading an M2 server
Available Install nftables first (sudo apt install -y nftables); the new
daemon needs nft for the container networks. A server set up with M2 has
no admin token. After you install the new binary and restart the daemon, run
as root on the server:
sudo podos token create --name admin --kind admin
The local socket keeps working as before; root there is an administrator.
sudo podos ca fingerprint prints the CA fingerprint for podos login. To
enable remote access, add --listen and --tls-name as described in
Several servers with contexts.
Available Before it changes the database schema, the daemon writes a backup
state.db.before-v<N> next to the database and logs each migration; see
Upgrade and backup. Containers started by a version
before M3 keep running after the upgrade, but without networking, until you
deploy the application again. The daemon logs a warning for each of them.
Ports
Available The daemon opens these ports:
| Port | Why | How to change it |
|---|---|---|
| 80 and 443 | The built-in proxy for domains. |
podos setup --http-listen, --https-listen, or --ingress off |
| The one you choose, for example 8443 | The remote HTTPS API, only with --listen. |
podos setup --listen, --reset listen |
Each port you publish |
Published ports of your services. | the publish key |
Podos does not open firewall ports for you. Two environments cannot publish
the same host port, and a port the server already listens on (such as 22)
cannot be published. The message is the same for every reason:
port tcp/N cannot be published on this server.
Network settings
Available Each project and environment gets a private network carved from
10.88.0.0/16 in /24 slices. Change the range with
podos setup --network-pool (private ranges only). By default containers
reach the internet and the server's private networks; the cloud metadata
address is always blocked. podos setup --strict-egress stops containers
from reaching private networks, and --allow-egress CIDR lists the
exceptions. See podos setup.
Let's Encrypt
Available tls = "auto" needs podos setup --acme-email EMAIL, which also
records your agreement to the certificate authority's terms of service. It
has only been tested against a test ACME server, not yet against the real
Let's Encrypt service. See Domains and HTTPS.
Available By default the daemon uses the Let's Encrypt production directory.
Two daemon flags change that (they are flags only; podos setup does not
save them):
--acme-directory URL: the ACME directory, https only. Use it for Let's Encrypt staging or a private CA.--acme-ca-file PATH: a PEM bundle that is the only trust for the ACME connection, for a private CA. Use an absolute path. It must be a regular file, not a symbolic link, owned by root or the daemon's user, and not writable by group or others, and its directory must not be writable by group or others. A file in/tmpis refused.
Node protection and disk guard
Available At every start the daemon reads the server's memory, CPU count and
disk. It caps all containers together at the server's memory minus a system
reserve, and at 80% of the kernel's process limit. A service whose memory
limit is larger than what the server can give to containers is refused at
deploy. Deploys and image pulls are refused with "not enough free disk space
on the server" when the data directory's file system is nearly full; running
containers are never stopped because of it. These are the defaults and the
daemon flags that change them (flags only; podos setup does not save them):
| Setting | Default | Flag |
|---|---|---|
| System reserve (memory kept for the system) | 10% of the server's memory, at least 256 MiB, at most 2 GiB | --system-reserve-memory SIZE, for example 512M or 1G |
| Free-disk threshold | the larger of 1 GiB and 5% of the file system, at most 10 GiB | --min-free-disk SIZE, for example 2G |
See Limits.