The setup page
remote machines for users for administrators
The daemon serves a page at / that sets up any machine, with one script for every tool at /setup/all and a page per tool, a status bar on every page, a 30-day summary of the upstream servers, and on its own machine and trusted networks links to the cache page and the upstream status.
On the map: setup and the command line
▶ Watch this deck — 9 scenes, ~6 min
Part of journeys
- One pkgproxy for your local network, step 4 of 9 · previous: Setting up clients · next: The cache page
01 What this topic covers
The page at the proxy's own address that sets up any machine, with a page per tool, the desktop entry, the status bar, and the cache and upstream lines.
The setup page is the web page pkgproxy serves at its own address, so that a machine without pkgproxy installed can start using it. If you have not seen pkgproxyctl setup, start there. You see the page and its one command for every tool, each tool's own page, the address the commands name, and opening the page from the desktop. Last come the bar every page opens with, and what the page says of the cache and the upstream servers.
02 A page at the proxy's own address
curl -fsSL http://host:3142/setup/all | sh, run as yourself;
its undo is ?undo=1. Each tool's page is at
/setup/<tool>. GET / is HTML for a browser,
plain text for curl. -setup-page=false turns it off.
A machine without pkgproxy installed can still use it. Opened in a browser, the proxy's own address on port 3142 shows a setup page. Its first command fetches the script at /setup/all and pipes it to sh: that sets up every tool it finds on your machine, asking for sudo for those that need root, and goes on past one that fails. Below it, a tile for each tool whose proxy engine is turned on leads to that tool's own page. Curl gets plain text with every tool's commands. The setup page option turns the page off.
03 The same script, read before it runs
/setup/apt is #!/bin/sh plus what
pkgproxyctl setup apt | sh would run, as text/plain
for curl; a browser gets the apt page. Minimal Debian and Ubuntu images
have no curl: paste the commands instead.
Each script under /setup is the shell's first line followed by exactly what pkgproxyctl setup prints when piped: pkgproxy builds both the same way, so they cannot drift apart. Curl gets the script. A browser at the same address gets the tool's own page instead: the command, the commands it runs, to read first or to paste on a machine without curl, and how to undo it. The scripts travel over plain HTTP, so piping one to sh trusts the network between you and the proxy, as using the proxy does.
04 The address the page names for administrators
-public-url http://host[:port] (snap option
public-url) beats the request's Host, which
beats -addr.
The commands on the page must name an address the visitor can reach, and the listen address usually cannot be that: its host is a wildcard. So the page uses the Host header the request arrived with, the address the visitor just reached the proxy at. That header ends up inside shell commands, so it is used only when it is a plain host name or IP address with an optional port; anything else falls back to the listen address. The -public-url flag overrides both, for an instance behind NAT or reached by another name.
05 Opening it from the desktop
pkgproxy.open runs pkgproxyctl open: it reads
/pkgproxy/v1/info, opens http://localhost:3142/
with xdg-open, and on failure says why on stderr.
On the machine that runs it, the snap adds pkgproxy to the applications menu. The entry runs pkgproxy.open, which is pkgproxyctl open with only the desktop plug. It asks the daemon on the stats socket where it listens and whether it serves the page, retrying briefly while the daemon starts. A wildcard host becomes localhost, and the public URL is ignored, as it is meant for other machines. Then xdg-open hands the address to the desktop's browser. A menu entry has no terminal, so to see why it fails, run pkgproxy.open in one.
06 One bar on every page
The status element is re-read from /pkgproxy/status every
30 seconds while the page is visible; offline shows a hollow dot, so it
reads without colour. In plain text, the setup page shows a notice
instead. The footer has a language switcher.
Every page pkgproxy serves opens with the same bar: its name and the address to use, the pages you may open, and a status element. The status shows the worst state pkgproxy is in: online, degraded while it leaves a failing server alone, or offline. Opened, it says for how long and why. It stays current while the page is open. While something is wrong, a banner under the bar says so too, and that what is cached is still served. Unless you are on its machine or a trusted network, neither names a server.
07 The cache and the upstream servers
"How the upstream servers have answered, last 30 days"; "Other servers"
is shown only once three or more were asked. The lines link to
/pkgproxy/cache and /pkgproxy/upstreams; a request
from an untrusted network, or carrying Forwarded,
Via or X-Forwarded-*, gets a 404.
Everyone who opens the page sees how the upstream servers have answered over the last thirty days, once any was asked: the snap store, Go modules, Docker Hub and the other servers summed up, with no other server named. On the machine that runs the proxy, or from a network the administrator trusts, the page has two more lines: the cache's size, linking to the cache page, and how many servers are failing, linking to the upstream status. Anyone else, or a request that came through a proxy, gets a 404 for those pages, as for any unknown path.
08 Where to go next for administrators in place of the general version
Next: The cache page, for what it shows; Offline mode, for what fails while offline; pkgproxyctl setup, for the same scripts from the command line.
Any machine on your network can now set itself up with one command from the page, and the page tells you when pkgproxy cannot fetch. To see what the cache page shows, watch The cache page. To see what fails while the proxy is offline, watch Offline mode. For the same scripts from the command line, watch pkgproxyctl setup.
09 Where to go next general version
Next: pkgproxyctl setup, for the same scripts on the proxy's machine; Offline mode, for what fails while it is offline.
Any machine on your network can now set itself up with one command from the page, and the page tells you when pkgproxy cannot fetch. For the same scripts on the proxy's own machine, watch pkgproxyctl setup. To see what fails while the proxy is offline, watch Offline mode.
Read more
What the page serves
| Address | A browser gets | curl gets |
|---|---|---|
/ | The setup page: one command for every tool, a tile per tool, the 30-day summary | Every tool's commands, as plain text |
/setup/all | The script | A script that runs, for each tool found on the machine, that tool's script; sudo only where root is needed. It goes on past a tool that fails and exits non-zero if any did. |
/setup/all?undo=1 | The script | The same, undoing each tool, in the reverse order |
/setup/<tool> | The tool's page: the command, the commands it runs, and the undo | The tool's script |
/setup/<tool>?undo=1 | The tool's page | The undo script |
/pkgproxy/status | The status element alone, never cached | The same |
The tools are those whose proxy engine is turned on: apt, snap, go, docker, lxd, lxd-remote, snapcraft, rockcraft and charmcraft. /setup/all checks for each with command -v (for docker, also /var/snap/docker/current), and prints pkgproxy: <tool> before each.
Language
Every page has a language switcher in its footer. The page's language is, in order: ?lang=, the pkgproxy-lang cookie the switcher sets for a year, then the browser's Accept-Language.
Roads from here
CORE · the path every proxy engine shares
- Offline mode — what degraded and offline mean
SETUP AND THE COMMAND LINE
- Setting up clients — the same scripts from pkgproxyctl setup
- pkgproxyctl — pkgproxyctl open and the stats socket
OPERATIONS
- The cache page — what the cache page shows
- Upstream status — the status pages the bar links to