Podos A lightweight container platform Early development · not released

Guides

Web UI

Available

This page describes what is in the code on the main branch. There are no release binaries yet.

The web UI is part of the podos binary. The daemon serves it on its HTTPS API address, the one you give with --listen, for example https://server.example.com:8443. You log in with an API token. You can also finish the first setup of a new server in the browser, without a terminal session that prints a token.

The UI is a view on the same API as the CLI. It shows the state of the server and lets you change variables and secrets. Deploying stays in the CLI.

Where it is served

Turn it on or off

The web UI is on by default whenever the API listens. To turn it off:

sudo podos setup --web-ui off     # saved
sudo podos daemon --web-ui off    # for this run only

podos setup --web-ui on turns it on again. The flag of podos daemon wins over the saved setting. With the UI off, the API on the same address works as before.

Set up a new server in the browser

The normal first setup is podos setup on the server, which prints the first admin token (Install and set up a server). The browser variant does the same without printing a token on the terminal:

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

--listen and --tls-name are required: the browser must reach the HTTPS API of the server, and the certificate must cover the name you type. The command prepares everything that cannot be done remotely (data directory, secrets key, state database, internal CA) and then prints:

It creates no admin token. It cannot be combined with --token-file or --new-admin-token.

Then:

  1. Start the daemon (sudo systemctl enable --now podos with the install script's unit, or sudo podos daemon).
  2. Open the TCP port of --listen in the server's firewall. Podos does not open firewall ports.
  3. Open the address in a browser and compare the CA fingerprint.
  4. Follow the wizard (below).

Until the setup is finished, the API answers only health and the setup itself.

With the install script, the same thing in one step (see Install script):

sudo sh install.sh -- --web --listen 0.0.0.0:8443 --tls-name server.example.com

This needs no terminal. When the script's output is not a terminal, the setup code is in that output, so a provisioning log will hold it. The code is useless after 30 minutes or once the setup is finished.

Compare the CA fingerprint

The browser shows a certificate warning. That is expected: the certificate was made by the server's own CA, which no browser knows. The warning is also what you would see if someone sat between you and the server, so compare before you go on:

  1. In the warning page, open the details or the certificate of the page.
  2. Find the certificate at the top of the chain, the CA. The server sends the CA with its own certificate.
  3. Compare its SHA-256 fingerprint with the CA fingerprint printed by podos setup --web (SHA256:AB:CD:...).

If they are the same, continue to the page for this visit. If they differ, do not enter the code and do not continue. podos ca fingerprint on the server prints the fingerprint again.

The setup code

For a new code (expired, void or lost), stop the daemon and run sudo podos setup --web again. It prints a new code and the earlier one no longer works. This works only while the setup is pending.

sudo systemctl stop podos
sudo podos setup --web
sudo systemctl start podos

The wizard

Step What it does
Setup code You enter the code.
Checks Shows what Podos found on the server (tools, kernel, firewall) and whether it can run containers. Errors must be fixed to continue.
HTTPS The built-in proxy on or off, its HTTP and HTTPS addresses, and the contact e-mail for Let's Encrypt. Saving an e-mail is your agreement to the certificate authority's terms of service.
Networking The network pool, strict egress and allowed egress ranges.
Review Your choices, with the equivalent podos setup command.
Save Creates the admin token and shows it once, together with the CA fingerprint and a podos login command.

The fields start with the values the server has, including settings you gave to podos setup --web. The wizard saves the same settings as the flags of podos setup.

Some settings need a daemon restart. If the daemon can restart itself, the wizard says so and waits for the server to come back; your containers keep running. If not, it shows the command to run on the server. Copy the admin token before you leave the page: it is not shown again. A lost token is replaced with sudo podos setup --new-admin-token.

Use "Log in with this token" to open the UI, and podos login from your computer to use the CLI.

Log in

Open the address of the server. The login page asks for a token. Paste an admin token, or any token from podos token create.

The account menu (top right) shows the token's name, kind and scope and when the session started.

See Security model for what protects the session.

What the screens show

Overview

On a server without applications, the page shows the commands for the first deploy.

Projects

A missing variable or secret (named by a service but not set) shows in the tab and in Needs attention; the next deploy is refused until it is set. A token that may only read sees the values or names and no edit buttons.

Secrets

The server-wide secrets page lists, for each project, its secrets against its environments, with the state of each cell (set, missing, unused, changed after the release). Select a cell to set or replace the secret in that environment. You can filter by name and show only entries that need attention.

Not in the UI yet

These are CLI only for now:

A combined view of several servers is not built either. The UI shows the server whose address you opened.

A binary built from source

make build does not need Node and does not include the UI. A binary built that way answers on the HTTPS address with a page that says the web UI is not built into it. The API and the CLI work as usual. To include the UI, run make ui before make build. It needs Node 22.22 or newer and npm, and it runs npm ci and npm run build in web/. See Install and set up a server. Release builds will include the UI; there are none yet.

Troubleshooting

Message or symptom What it means
"The web UI is not built into this binary" The binary was built without make ui. Build the UI in, install a release build, or turn the page off with podos setup --web-ui off.
The page does not load Check that the daemon runs with --listen, that the web UI is not turned off, that the name in the address is one of the --tls-name names (other Host names are refused) and that the port is open in the firewall.
"this server is not set up yet: finish the setup in the browser" The server was set up with --web and waits for its first setup. Open the address and enter the setup code.
"the setup code is not right (N attempts left)" Copy the code again from the terminal. Case, dashes and spaces do not matter.
"too many wrong setup codes; try again in N seconds" The code is paused after five wrong tries. Wait.
"the setup code is no longer valid (expired or too many wrong attempts): stop the daemon and run 'podos setup --web' again on the server for a new code" Do as it says.
"a podos daemon is running and holds the state database; stop it first" podos setup refuses while the daemon runs. Stop the daemon first.
"Podos is already set up in ..., so the setup in the browser is not available" --web is only for a server set up with --web that has not finished. Use podos setup --new-admin-token for another token.
"the setup of this server is already complete" The wizard was finished. Log in with the admin token.
"This token was not accepted. Check that you copied all of it, and that it has not been revoked or expired." Wrong, malformed, revoked and expired tokens all give this answer.
"Too many failed attempts. Try again in ..." Failed logins are limited per address and for the whole server. Wait.
"The server refused the login because the request did not come from its own address." The page and the API must be on one address. A reverse proxy must pass the Origin header unchanged.
Sent back to the login page The session ended: token revoked or expired, 12 hours idle, or 7 days. Log in again.
"this request must come from the web page of this server" A change was sent with a cookie but without the page's headers, for example by a script. Use a token with the CLI or the API instead.