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.
- The API is served over HTTPS only. Plain HTTP is never offered.
- The certificate comes from the internal CA of the server, covers the
--tls-namenames, and is renewed and reloaded without a restart. Requests with anotherHostname are refused. --tls-nameis needed when you listen on all interfaces. Use a DNS name or an IP address that your clients can reach.- Open the TCP port in the server's firewall.
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 \
--namespace shop --env test --expires 90d # short: -n shop -e test
# a read-only token for one namespace
sudo podos token create --name shop-viewer --kind read --namespace 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
- The CLI connects and shows the fingerprint of the server's CA.
- Compare it with the fingerprint printed by
podos setuporpodos ca fingerprinton 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. - 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. - The CLI saves the address, the CA and the token as the context
prod-eu. --usemakes 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 thepodos context use prod-euhint 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.
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:
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
[environment.test]
context = "test-box"
[environment.prod]
context = "prod-eu"
namespace: 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:
- The first time a manifest selects a context for a namespace, the CLI shows
the context, the address and the namespace and asks you to type
yes. It remembers the choice for that context and namespace. - Without a terminal it refuses. Pass
--context NAMEto confirm. --contextandPODOS_CONTEXTcome from you and never ask.
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
- There is no CA rotation yet.
- HTTP proxies are not supported for server connections; proxy environment variables are ignored.
- The HTTPS API needs a route from the client to the listen port; Podos does not open firewall ports.