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
- On the HTTPS API address only. There is no extra port.
- Never on the Unix socket and never over plain HTTP.
- It needs the API to listen: without
--listen(or the savedpodos setup --listen) no TCP port is open and there is no web UI. See Several servers with contexts. - The certificate comes from the server's internal CA, so a browser warns about it. See Compare the CA fingerprint.
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:
- the address to open, for example
https://server.example.com:8443; - a one-time setup code such as
ABCD-EFGH-JKLM, shown only this once; - the CA fingerprint of the server.
It creates no admin token. It cannot be combined with --token-file or
--new-admin-token.
Then:
- Start the daemon (
sudo systemctl enable --now podoswith the install script's unit, orsudo podos daemon). - Open the TCP port of
--listenin the server's firewall. Podos does not open firewall ports. - Open the address in a browser and compare the CA fingerprint.
- 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:
- In the warning page, open the details or the certificate of the page.
- Find the certificate at the top of the chain, the CA. The server sends the CA with its own certificate.
- 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
- It is valid for 30 minutes.
- After every five wrong codes, checks are paused for a while, and a right code is refused too until the pause ends. The pause grows from 30 seconds up to 5 minutes.
- After 40 wrong codes the code is void.
- The server keeps only a hash of the 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 browser sends the token once. It keeps only a session cookie, never the token.
- A session has the permissions and scope of its token. A token limited to one namespace sees only that namespace.
- The session ends when you choose Log out in the account menu, when the token is revoked or expires, after 12 hours without use, or after 7 days in all.
- At most 20 sessions exist per token. A new login beyond that replaces the oldest.
- The limits are not configurable.
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
- The server's host name, operating system, Podos version and uptime.
- Resources: capacity of memory, CPU and disk. Only admin tokens see it. What services request and use is not measured yet, so only capacity is shown.
- Needs attention: services that are failing or degraded, missing variables or secrets, an environment that could not be read, and free disk space below the deploy limit.
- Each environment with its health, ready containers, active release and domains.
- The active release of each environment.
On a server without applications, the page shows the commands for the first deploy.
Namespaces
- A table of the services of every namespace, by environment, with status, ready containers, image, domains, restarts and release. You can filter by environment, namespace and status, and find a service by name, image or domain.
- Opening a namespace and environment shows four tabs:
- Services: the same table for this environment.
- Domains: each domain, its service and its TLS mode. The certificate status is not shown yet.
- Variables: name, value, status, which services use it and when it
changed. You can add, edit and remove a variable. The value is shown in
clear text. Changes take effect with the next deploy. Needs a token that
may change variables (any kind but
read). - Secrets: name, status, which services use it and when it changed. You can add, replace and remove a secret. The value is write-only: it is never shown again. Needs a token that may change secrets.
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 namespace, 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:
- deploying, rolling back and removing services;
- files (
podos file) and the release history (podos releases); - logs and metrics;
- tokens and server settings after the setup (
podos token,podos setup); - running a command in a container.
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. |