Podos A lightweight container platform Early development · not released

Guides

Several servers with contexts

Available

This page describes what is in the code on the main branch. There are no release binaries yet. Without a context, the CLI talks only to the daemon on the same machine, over its Unix socket, as root.

A context is a saved server address, the CA that signs its certificate, and a token. With contexts you run podos deploy, podos ps and the other commands from your laptop. Each server stays independent: there is no central hub and no agent.

1. Open remote access on the server

Remote access is off by default. The local socket works as before. To turn it on, give the daemon an address to listen on and the names clients use to reach it. Either save them once with podos setup:

sudo podos setup --listen 0.0.0.0:8443 --tls-name server.example.com
sudo podos daemon

or pass them to the daemon each time (podos daemon --listen ... --tls-name ..., or PODOS_LISTEN and PODOS_TLS_NAMES). The saved settings live in settings.json in the data directory.

2. Get the first admin token and the CA fingerprint

podos setup on a new server prints the first admin token once, and the fingerprint of the CA:

Admin token ... (shown only this once; store it safely, it cannot be recovered):
  ...
CA fingerprint (public; ...):
  SHA256:...

The token is printed only to a terminal. In a script, write it to a file instead: podos setup --token-file /root/podos-admin.token (mode 0600, never over an existing file). Only the token's hash is stored, so a lost token cannot be shown again.

The fingerprint is public and is printed on every run of podos setup. Root can print it again at any time, also while the daemon runs:

sudo podos ca fingerprint

A server that was set up with an earlier version has no admin token yet. As root on the server, create one:

sudo podos token create --name laptop --kind admin

podos setup --new-admin-token does the same on a set-up server. As root on the local socket you are already an administrator; tokens are for remote use.

3. Create scoped tokens

Give each person or CI job the least access it needs. See Tokens and scopes for what each kind can do.

# a CI job that deploys to the test environment of shop, for 90 days
sudo podos token create --name ci-shop-test --kind deploy \
  --project shop --env test --expires 90d   # short: -p shop -e test

# a read-only token for one project
sudo podos token create --name shop-viewer --kind read --project shop

sudo podos token list
sudo podos token revoke ci-shop-test

The token is printed once. A deploy token cannot change secrets unless you add --secrets-write. A deploy token can still read its environment's secrets indirectly, through the containers it deploys: grant deploy tokens deliberately.

A token that is not an admin token sees only what is in its scope. Anything outside it answers "not found", as if it did not exist.

4. Log in from your laptop

podos login https://server.example.com:8443 --name prod-eu --use
  1. The CLI connects and shows the fingerprint of the server's CA.
  2. Compare it with the fingerprint printed by podos setup or podos ca fingerprint on the server. Confirm only if they are the same. This is the one moment you have to check; it is what protects you from a server that pretends to be yours.
  3. The CLI asks for the token without echo. It can also read it from standard input or from PODOS_TOKEN; there is no token flag, so the token never appears in a process list.
  4. The CLI saves the address, the CA and the token as the context prod-eu.
  5. --use makes it the current context. Without --use, a first login makes it current only when there is no current context and no podos daemon answers on this machine's local socket. Otherwise the context is saved, commands keep using what they used before, and the CLI prints the podos context use prod-eu hint to switch.

From then on the server is verified strictly against the saved CA. If the CA ever differs, every command fails and nothing is trusted again silently.

Without a terminal, pass the fingerprint yourself:

echo "$TOKEN" | podos login https://server.example.com:8443 \
  --name prod-eu --ca-fingerprint SHA256:...

Contexts are kept in ~/.config/podos/contexts.json (or under $XDG_CONFIG_HOME), mode 0600, in a directory with mode 0700. The file stores the project of each remembered choice. A file written by an earlier build, with namespace there, is refused: log in again.

5. Work with contexts

podos context list              # the current one is marked with *
podos context use prod-eu       # make it the current context
podos whoami                    # which token the server sees, its kind and scope
podos ps --context test-box     # one command, another server (short: -c)
podos logout prod-eu            # delete the saved token, keep address and CA
podos context remove prod-eu    # delete the context

local is built in and means the daemon socket on this machine; podos context use local goes back to it. logout and context remove only change your machine: the token stays valid on the server until you run podos token revoke.

A command picks its server in this order: --context, --socket, PODOS_CONTEXT, PODOS_SOCKET, the manifest's context key, the current context, the local socket. See Connecting to the daemon. Every command that talks to a remote server prints which context and URL it uses, so you see where podos deploy is going before anything is sent.

6. Bind an environment to a server

A manifest environment can name the context it lives on, so test and prod can be on different servers:

TOML
project = "shop"
environments = ["test", "prod"]

[service.web]
image = "ghcr.io/example/shop:1.4.2"

[environment.test]
context = "test-box"

[environment.prod]
context = "prod-eu"
YAML
project: shop
environments: [test, prod]

service:
  web:
    image: ghcr.io/example/shop:1.4.2

environment:
  test:
    context: test-box
  prod:
    context: prod-eu

podos deploy --env prod then goes to the server of context prod-eu. The value is only a context name, never an address or a token. It is not uploaded to the server.

The hostile-repository protection

A manifest can come from a repository you did not write. If it could pick the server freely, a cloned repository could send your next podos deploy to a production server, using the token you saved for it. So the CLI asks first:

Several servers, no hub

Each server is an independent Podos with its own state, tokens and CA. You keep one context per server and the CLI switches between them. Nothing connects the servers to each other.

The web UI is served by each server and shows that one server. A combined view of all your servers is Planned: podos ui is planned to run locally and switch between your contexts. It is not built.

Limits