feature: the package installs the Router Manager, which is no longer a package of its own.
Release / release (push) Failing after 4s

This commit is contained in:
slawek committed 2026-11-14 12:52:44 +01:00
1 parent 6d90441bee
commit 8efe21bfa6
129 files changed
+17381 -104

No files matched your search

+150 -5
View File
@@ -49,7 +49,7 @@ the overall status and the Client IP, `standard` also the package versions and t
active and other services, and `full` also each service and the state of the site-to-site, IKEv2, OpenVPN and
WireGuard features. The Client IP is the address the request came from, through the trusted
proxies, so a person can see the address the router sees. Nothing comes from the configuration.
`/status` names its content, so clients such as manage-ui and the Router Manager show what it
`/status` names its content, so clients such as Cloud Manager and the Router Manager show what it
has. `vpn-router-setup` opens the
port on both interfaces in UFW, so the choice of `web.listen` is made by the service alone, and
writes the features and the facts it resolves to `/run/vpn-router/web.json`.
@@ -227,7 +227,7 @@ no CORS headers, so a browser cannot call it directly, and tokens kept in the pa
by its scripts.
Decision: `vpn-router-manager` is a Debian package of its own, built in the repository
`linux-cloud-router-manager`. A React and MUI application in the style of manage-ui is built
`linux-cloud-router-manager`. A React and MUI application in the style of Cloud Manager is built
with Vite when the package is built and shipped as static files. A Python server, using the
Ubuntu packages `python3-requests` and `python3-psycopg`, serves them, signs users in through the
router's `/auth`, keeps their tokens in a server-side session in PostgreSQL behind an
@@ -650,7 +650,7 @@ Status: Accepted
Context: The router had one IPsec site-to-site tunnel, the `remote` section, run as the swanctl
connection `remote-site`, with the local identity mode in `wan` and the local subnets in `local`.
A router often links more than one site, each with its own peer, subnets and key, and an admin
should add them without a shell. The install answers and the Cloud Platform describe one
should add them without a shell. The install answers and Cloud Manager describe one
connection, and the platform rewrites `vpn-router.json` when it rebuilds the VM.
Decision: `site_to_site` maps a connection name to its settings: `addrs`, `id`, `cidrs`,
@@ -658,7 +658,7 @@ Decision: `site_to_site` maps a connection name to its settings: `addrs`, `id`,
without a fallback for the old format. The name, a lowercase letter followed by at most 30
lowercase letters, digits and hyphens, names the swanctl connection, its child and its secret
`ike-psk-<name>`, so it is a valid swanctl section name and stays the same while the connection
lives. The install answers and the Cloud Platform write the connection `remote-site`, the first
lives. The install answers and Cloud Manager write the connection `remote-site`, the first
one, so its name is the one the tunnel always had.
- **Local settings per connection:** each connection has its own `local_cidrs` and
@@ -692,7 +692,7 @@ Consequences: A configuration with `remote` is refused, so the package and a con
the new format go together. The status shows each connection. A rate across a rekey misses the
traffic of the old child SA since the previous sample. A renamed connection starts a new series.
A connection added through the API lives in
`vpn-router.json` only; the Cloud Platform's rebuild of the VM writes the file again with its
`vpn-router.json` only; Cloud Manager's rebuild of the VM writes the file again with its
one connection, dropping the others. A change through the API is answered before setup has
applied it, so a configuration that setup cannot apply shows in the setup state, not in the
answer. A connection with a key file keeps it until a key is given through the API, which then
@@ -1375,6 +1375,7 @@ last line of defence, every server replaces the default reports:
- `vpnrouter_serve.serve`, which the web service and the metrics service run, sets the servers'
`handle_error`, `threading.excepthook` and `sys.excepthook`.
- `vpnrouter_manager.serve`, which the Router Manager runs, does the same.
- The bootstrap server sets its server's `handle_error` and `sys.excepthook`.
A `ConnectionError` of a client that went away is not logged; any other exception is logged in
@@ -1396,3 +1397,147 @@ columns. `release.py` joins its lines with single spaces into the commit message
Consequences: The commit message is one line however the summary is wrapped, so a summary
rewrapped later still matches the commit of its release.
## ADR-50: The help is Markdown rendered in the browser, in a panel that pushes the page
Status: Accepted
Context: The Router Manager's pages were explained only in its README. Help should be written as
plain files next to the code, shipped with the package, readable only after signing in, and able
to show pictures. serve-markdown renders Markdown in the browser with marked, DOMPurify and
github-markdown-css. Google Cloud's console shows its Learn panel on the right and moves the page
left, so the help never covers what it explains.
Decision: The help is the Markdown files of `docs/` (plain Markdown, no MDX), with SVG and PNG
pictures, installed to `/usr/share/vpn-router/manager/docs` and served by the manager at
`/docs/<file>` behind the session, with no-sniff and a CSP that keeps an SVG from running
scripts. The browser renders them with marked (GFM) and DOMPurify, styled with
github-markdown-css in the Manager's light or dark scheme, without syntax highlighting or
diagrams. The help icon in the header opens a persistent drawer on the right whose width the page
gives up; it opens at the topic of the page and tab shown, and links between topics stay in the
panel.
Consequences: Help is edited as Markdown and released with the package. The Manager depends on
marked, DOMPurify and github-markdown-css. A page without a topic of its own shows the index. The
help is not reachable without a session.
## ADR-51: The files of web sites pass the manager streamed, outside the JSON proxy
Status: Accepted
Context: The Web Sites page uploads and downloads the files of the router's web sites, up to the
router's `sites.upload_max_mb`, by default 512 MiB. The manager's proxy reads a request body of at
most 64 KiB into memory, sends it as JSON and holds the whole answer; the API helper of the page
parses every answer as JSON. Encoding files in JSON would grow them by a third and still need the
whole file in memory.
Decision: `GET`, `HEAD` and `PUT` of `/api/sites/<name>/files/...` take their own route in the
manager: the request body is passed to the router as it is read, with its `Content-Type` and
`Content-Length`, and the router's answer is passed back as it arrives, with its `Content-Type`,
`Content-Length` and `Content-Disposition`. The page uploads with `XMLHttpRequest`, whose upload
events give the progress `fetch` does not, sending the file as the raw body, a zip archive with
`?unzip=true`, and downloads with `fetch` into a blob. Folders, renaming and removal stay JSON
calls of the usual proxy.
Consequences: Large files cross the manager without filling its memory. An upload needs a
`Content-Length`, which browsers send for a file. Dropped folders are not uploaded as trees; a zip
archive carries a tree.
## ADR-52: On a workstation, the router's URL is the Terraform output router_web_url
Status: Accepted
Context: With `terraform_dir`, the manager built `http://<router_private_ip_addresses.int>:7081`.
The port of the router's web service is `web.port` and the interfaces it listens on are `web.listen`,
which the platform sets from its variables; the manager that `dev.sh` runs on a workstation cannot read them.
Decision: `router_url` is the output `router_web_url` of the platform, which derives the URL from
the same variables that configure the router.
Consequences: The manager follows the router's port and interfaces without settings of its own; a
state written before the platform had the output gives no `router_url` until the next deploy.
## ADR-53: The system's packages are upgraded with apt-get upgrade, apart from the router's package
Status: Accepted
Context: The Overview tab upgrades only `vpn-router`. The router's
operating system needs its other packages upgraded too, from the same page. An upgrade restarts
services, the manager among them, so it cannot run inside the manager's unit.
Decision: The System tab lists what `apt-get -s upgrade` would upgrade and runs `apt-get upgrade
-y` through the same helper as the router's package, with `--system`, in its own transient unit
and with its own state and log files, so each tab shows its own last upgrade. `upgrade`, not
`dist-upgrade` or `full-upgrade`, so nothing is installed or removed; a package that needs a new
dependency is kept back. The manager refuses an upgrade while the other runs; the check for
updates is the same `apt-get update` for both.
Consequences: Kept-back packages, a new kernel series among them, stay until upgraded on the
router. An upgrade of the system also upgrades the router's package when it is newer, which
the Overview tab's state does not record.
## ADR-54: The Shell page's editor is Monaco, opened by vre and loaded on demand
Status: Accepted
Context: Administrators edit files on the router from the Shell page. The page needs no file
browser: the shell names the files, as `$EDITOR` would. Monaco is VS Code's editor component and
is published as the ESM package `monaco-editor`. Its full entry point brings the language services
of CSS, HTML, JSON and TypeScript, each with a worker, and its bundle is several megabytes.
Decision: The router's `vre` names a file in a text message over the shell's WebSocket, which the
manager relays unchanged. The page reads and saves the file through the JSON proxy, whose body
limit is raised for `/api/shell/editor/` alone to hold a file of up to 1 MiB escaped in JSON.
Monaco 0.57 is bundled from npm through its tree-shakeable entry points: `monaco-editor/editor`
with all editor features and all language definitions, and only the editor worker. It is a chunk
of its own, imported when the first file opens, and Vite's preload helper has a chunk of its own,
so the entry does not load Monaco.
Consequences: The editor colours the syntax of every language Monaco defines, but has no
validation, completion or formatting by language services. The page loads Monaco, about 1.1 MB
compressed, the first time a file opens.
## ADR-55: index.html sets the color scheme before the first paint
Status: Accepted
Context: Each page of the manager is a document of its own, so a page switch loads `index.html`
again. MUI sets the color scheme class on `<html>` and the page background from JavaScript, once
React renders, which waits for the bundle and for `GET /info`. Until then the browser paints its
default white page.
Decision: An inline script in the head of `index.html` reads the mode MUI stores in localStorage
(`mui-mode`, `system` when not stored), as MUI's `InitColorSchemeScript` does, and adds the class
`light` or `dark` to `<html>`. An inline style gives `html.dark` the dark color scheme and MUI's
default dark background, `#121212`. The page has no meta color-scheme, which would follow the
system against a stored light or dark choice.
Consequences: A page in the dark theme is dark from its first paint. The script depends on the
storage key and class names of MUI's defaults, which `colorSchemeSelector: 'class'` uses.
## ADR-56: The Router Manager is part of the vpn-router package
Status: Accepted
Context: The Router Manager runs only on the router: it imports `vpnrouter_net`, `vpn-router-setup`
opens its ports and creates its first administrator, Caddy proxies it and the status reports it.
As a package of its own it would pin the router's version and the router its, and a change of the
router's API would need two repositories and two changelogs.
Decision: One package, `vpn-router`, installs the manager with the router. The manager's programs
are in `/usr/lib/vpn-router`, its application and help in `/usr/share/vpn-router/manager`, its
settings and secrets in `/etc/vpn-router` (`manager.json`, `manager-database.secret`,
`manager-admin.json`) and the state of its upgrades in `/var/lib/vpn-router`. The unit
`vpn-router-manager.service`, its transient units and its database keep their names. The debconf
questions of its first administrator are `vpn-router/admin_username` and `admin_password`. The
router's bootstrap page shows the manager, and the manager has no bootstrap service of its own.
The package carries no migration from the separate package: it has no relation to
`vpn-router-manager`, and dpkg refuses to install it beside that package, since both have
`vpn-router-manager.service`. `dev.sh` still runs the manager on a workstation, with
`terraform_dir` and `bind`.
Consequences: A router with the separate package is moved to this one by hand: remove
`vpn-router-manager` without purging it, move its files to the new paths, then install
`vpn-router`. A backup made before the merge restores the manager's files to
`/etc/vpn-router-manager`, where the manager no longer reads them. The repository holds the
manager's `web/` and `docs/`, and its build runs from the root.