An update you can ask for, and a boundary that stays where it was
The button cannot do the work, and that is the whole design. The service runs as an unprivileged account, cannot restart itself, and should not be able to: a web application that can restart its own service is one whose worst day is much worse. So /admin/updates writes a file, and an opt-in systemd .path unit runs deploy/update.sh as root. Three properties hold it up, and each is a thing that could have been got wrong. The request file carries nothing that reaches a command line -- no branch, no ref, no arguments -- because the branch is baked into the unit at install time, so pressing the button is always "deploy the branch this host was configured with" and can never be "deploy something else". It is off unless somebody passes INSTALL_UPDATE_HELPER=1, and re-running the installer without it removes both units and the marker. And without the helper the page says so and prints the manual command rather than writing a file nothing is watching, which would be a button that reports success and does nothing. The card that says all of this is rendered whether or not there is anything to apply. It was inside the "there is an update" branch first, so an administrator could not discover the helper was missing until the day they needed it, which is the worst possible moment. Opening the page makes no network request; Check is the one thing that fetches. And it shows the log between, not a count: "3 behind" is a number somebody has to go and look up, while the subjects are what decides whether this is worth restarting for right now. Docker is one stage, because there is nothing to build -- no Node, no compiled assets. It bakes no secret key (one in an image is one every copy shares, and rotating it makes stored API keys unreadable), no data, and no .git, so /admin/updates inside a container correctly reports that it was not installed from a checkout. Compose publishes on loopback and refuses to start without a key. TLS in front is a constraint rather than a recommendation: the service worker and the microphone both require HTTPS or localhost. The image was built and run before this was committed, which is how the missing COPY of LICENSE was found -- pyproject declares it and the build backend reads it, so the failure reads like a packaging problem and is one line. deploy/lxc-install.sh creates an unprivileged Debian container and runs the existing installer inside it. A wrapper, not a second install path: a parallel installer is two things to keep correct and one of them rots. /healthz opens the database rather than only proving the socket is listening -- a process that is up with a database it cannot open answers every page with a 500 -- and says nothing about what is here, being reachable without signing in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jaroslav Beneš
+70
-1
@@ -45,7 +45,37 @@ Everything is overridable from the environment:
|
||||
| `HOME_DIR` | `/home/lembas` | that account's home |
|
||||
| `PREFIX` | `/srv/lembas` | install root (bind mount of `HOME_DIR`) |
|
||||
| `REPO_URL` | this checkout's `origin` | so a fork deploys itself |
|
||||
| `LEMBAS_BRANCH` | `main` | branch to deploy |
|
||||
| `LEMBAS_BRANCH` | `main` | branch to deploy, and what `/admin/updates` compares against |
|
||||
| `INSTALL_UPDATE_HELPER` | `0` | `1` lets the web interface deploy that branch as root |
|
||||
|
||||
## Updating from the web interface
|
||||
|
||||
`/admin/updates` says what is running, what is on the branch and what changed
|
||||
between. **Checking** reaches the remote; opening the page does not.
|
||||
|
||||
The button is opt-in, and the reason is a boundary rather than caution:
|
||||
|
||||
```bash
|
||||
INSTALL_UPDATE_HELPER=1 SITE_HOST=chat.example ./deploy/install.sh
|
||||
```
|
||||
|
||||
That installs `lembas-update.path` and `lembas-update.service`. The web
|
||||
interface writes `$PREFIX/data/update-requested`; the path unit notices and the
|
||||
service runs `update.sh` **as root**.
|
||||
|
||||
**What that grants.** Anybody who can administer this web interface can then
|
||||
deploy whatever is on the configured branch and restart the service. That is the
|
||||
point of it, and it is why it is not the default.
|
||||
|
||||
**What it deliberately does not grant.** The request file carries nothing that
|
||||
reaches a command line — no branch, no ref, no arguments. The branch is baked
|
||||
into the unit at install time from `LEMBAS_BRANCH`, so the button is always
|
||||
"deploy the branch this host was configured with" and never "deploy something
|
||||
else". Re-running the installer without the flag removes both units and the
|
||||
marker, and the page goes back to printing the manual command.
|
||||
|
||||
Without the helper the page says so and shows `sudo …/deploy/update.sh`, which is
|
||||
the same honest degradation the SSH and search extras have.
|
||||
|
||||
## Deploying a change
|
||||
|
||||
@@ -59,6 +89,45 @@ reinstalls dependencies and restarts, printing the commits it pulled. The hard
|
||||
reset is deliberate: nothing is ever edited in place there, so there is no local
|
||||
work to preserve and no conflicts to resolve.
|
||||
|
||||
## In a container
|
||||
|
||||
A `Dockerfile` and a `docker-compose.yml` are in the repository root.
|
||||
|
||||
```bash
|
||||
echo "LEMBAS_SECRET_KEY=$(python -c 'import secrets;print(secrets.token_urlsafe(48))')" > .env
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
It publishes on `127.0.0.1:8080` and expects **a TLS reverse proxy in front**.
|
||||
That is a constraint, not a preference: a service worker and a microphone both
|
||||
require HTTPS or localhost, so over plain http on a LAN address the app cannot be
|
||||
installed and cannot dictate — and the session cookie is deliberately not marked
|
||||
`secure`, so an attacker on that network could steal a session.
|
||||
|
||||
Three things about the image:
|
||||
|
||||
- **No secret key is baked in**, and compose refuses to start without one. A key
|
||||
in an image is a key every copy of that image shares, and rotating it signs
|
||||
everybody out *and* makes stored upstream API keys unreadable.
|
||||
- **`.git` is excluded**, so `/admin/updates` inside a container says it was not
|
||||
installed from a checkout and offers nothing. That is correct: a container is
|
||||
updated by pulling a new image.
|
||||
- **One replica.** The generation registry, the stop mechanism, the terminal
|
||||
sessions and the schedule ticker are all in-process — two would mean two
|
||||
tickers and every schedule firing twice.
|
||||
|
||||
## On Proxmox
|
||||
|
||||
```bash
|
||||
CTID=140 SITE_HOST=chat.example ./deploy/lxc-install.sh
|
||||
```
|
||||
|
||||
Run on the Proxmox host. It creates an **unprivileged** Debian container,
|
||||
installs the dependencies, and runs `deploy/install.sh` inside it — the same
|
||||
installer, so a fix there reaches this without anybody remembering. Unprivileged
|
||||
is not a default to change: nothing LLeMbas does needs privilege, because agent
|
||||
chats run their commands over SSH on some *other* machine.
|
||||
|
||||
## Operating it
|
||||
|
||||
```bash
|
||||
|
||||
@@ -26,6 +26,11 @@ SERVICE_USER="${SERVICE_USER:-lembas}"
|
||||
HOME_DIR="${HOME_DIR:-/home/lembas}"
|
||||
PREFIX="${PREFIX:-/srv/lembas}"
|
||||
BRANCH="${LEMBAS_BRANCH:-main}"
|
||||
# Whether to install the units that let the web interface update this host.
|
||||
# Off, and off on a re-run that does not ask for it: it grants anybody who can
|
||||
# administer the web UI the ability to deploy the branch, as root. See the
|
||||
# "Updating from the web interface" section of deploy/README.md.
|
||||
INSTALL_UPDATE_HELPER="${INSTALL_UPDATE_HELPER:-0}"
|
||||
# Default to wherever this checkout came from, so a fork deploys itself.
|
||||
REPO_URL="${REPO_URL:-$(git -C "$HERE" remote get-url origin 2>/dev/null || true)}"
|
||||
|
||||
@@ -43,6 +48,11 @@ echo " host : https://$SITE_HOST -> 127.0.0.1:$APP_PORT"
|
||||
echo " user : $SERVICE_USER ($HOME_DIR)"
|
||||
echo " prefix : $PREFIX"
|
||||
echo " repo : $REPO_URL ($BRANCH)"
|
||||
if [[ "$INSTALL_UPDATE_HELPER" == "1" ]]; then
|
||||
echo " updates : web interface may deploy $BRANCH as root (helper units)"
|
||||
else
|
||||
echo " updates : by hand only ($PREFIX/app/deploy/update.sh)"
|
||||
fi
|
||||
|
||||
echo "== service user =="
|
||||
# --system: no ageing, no mail spool. Home under /home, not /var/lib, so the
|
||||
@@ -101,6 +111,11 @@ LEMBAS_PORT=$APP_PORT
|
||||
LEMBAS_LOG_LEVEL=info
|
||||
LEMBAS_ALLOW_SIGNUP=true
|
||||
LEMBAS_DEFAULT_THEME=moria
|
||||
# Which branch /admin/updates compares against. Deployment configuration, not
|
||||
# an instance setting: it decides what code runs here, and a value a web
|
||||
# administrator could edit would turn "you may deploy the branch" into "you may
|
||||
# deploy anything".
|
||||
LEMBAS_UPDATE_BRANCH=$BRANCH
|
||||
EOF
|
||||
sudo chown "$SERVICE_USER:$SERVICE_USER" "$ENV_FILE"
|
||||
sudo chmod 600 "$ENV_FILE"
|
||||
@@ -120,6 +135,35 @@ sed -e "s|__PREFIX__|$PREFIX|g" -e "s|__SERVICE_USER__|$SERVICE_USER|g" \
|
||||
sha256sum "$HERE/lembas.service" | cut -d' ' -f1 | sudo tee "$PREFIX/.unit-applied" >/dev/null
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
echo "== update helper =="
|
||||
# Two units and a marker. The marker is what the web interface reads to decide
|
||||
# whether to offer the button at all -- a file rather than `systemctl
|
||||
# is-enabled`, because that would be a subprocess on every page render to answer
|
||||
# a question that changes once.
|
||||
UPDATE_MARKER="$PREFIX/data/.update-helper"
|
||||
if [[ "$INSTALL_UPDATE_HELPER" == "1" ]]; then
|
||||
for unit in lembas-update.path lembas-update.service; do
|
||||
sed -e "s|__PREFIX__|$PREFIX|g" \
|
||||
-e "s|__SERVICE_USER__|$SERVICE_USER|g" \
|
||||
-e "s|__UPDATE_BRANCH__|$BRANCH|g" \
|
||||
"$HERE/$unit" | sudo tee "/etc/systemd/system/$unit" >/dev/null
|
||||
done
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now lembas-update.path
|
||||
sudo touch "$UPDATE_MARKER"
|
||||
sudo chown "$SERVICE_USER:$SERVICE_USER" "$UPDATE_MARKER"
|
||||
echo " installed. The web interface can now deploy $BRANCH and restart."
|
||||
else
|
||||
# Removed rather than left, so turning it off is re-running without the flag
|
||||
# rather than remembering three commands. The button then says so and prints
|
||||
# the manual one, which is the honest degradation.
|
||||
sudo systemctl disable --now lembas-update.path 2>/dev/null || true
|
||||
sudo rm -f /etc/systemd/system/lembas-update.path \
|
||||
/etc/systemd/system/lembas-update.service "$UPDATE_MARKER"
|
||||
sudo systemctl daemon-reload
|
||||
echo " not installed (INSTALL_UPDATE_HELPER=1 to allow updating from the web UI)"
|
||||
fi
|
||||
|
||||
echo "== self-signed cert for $SITE_HOST =="
|
||||
sudo mkdir -p /etc/nginx/ssl
|
||||
if [[ ! -f "/etc/nginx/ssl/$SITE_HOST.crt" ]]; then
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# Watches for an update request written by the web interface.
|
||||
#
|
||||
# install.sh substitutes __PREFIX__ and writes the result to
|
||||
# /etc/systemd/system/lembas-update.path. Installed only when the installer is
|
||||
# run with INSTALL_UPDATE_HELPER=1 — see deploy/README.md for what that decision
|
||||
# means.
|
||||
#
|
||||
# `PathExists` rather than `PathChanged`: the service deletes the file as its
|
||||
# first act, so the unit re-arms itself and a second request fires again. With
|
||||
# `PathChanged` a request written while the service was running would be missed.
|
||||
|
||||
[Unit]
|
||||
Description=Watch for a LLeMbas update request
|
||||
# Only while the thing being updated is meant to be running. Stopping lembas on
|
||||
# purpose should not leave a watcher that restarts it.
|
||||
PartOf=lembas.service
|
||||
|
||||
[Path]
|
||||
PathExists=__PREFIX__/data/update-requested
|
||||
Unit=lembas-update.service
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,37 @@
|
||||
# Runs deploy/update.sh when the web interface asks for it.
|
||||
#
|
||||
# install.sh substitutes __PREFIX__, __SERVICE_USER__ and __UPDATE_BRANCH__ and
|
||||
# writes the result to /etc/systemd/system/lembas-update.service.
|
||||
#
|
||||
# **What this grants.** Installing it means anybody who can administer the web
|
||||
# interface can deploy whatever is on the configured branch, as root, and
|
||||
# restart the service. That is the point of it, and it is why it is opt-in and
|
||||
# why the installer says so out loud rather than doing it by default.
|
||||
#
|
||||
# **What it deliberately does not grant.** The request file carries nothing that
|
||||
# reaches this command line: no branch, no ref, no arguments. The branch is
|
||||
# baked in below, from the installer's environment, so pressing the button is
|
||||
# "deploy the branch this host was configured with" and can never be "deploy
|
||||
# something else".
|
||||
|
||||
[Unit]
|
||||
Description=Apply a requested LLeMbas update
|
||||
# Not `After=lembas.service`: this restarts it, and an ordering dependency on
|
||||
# the thing being restarted is how a one-shot ends up waiting for itself.
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
# Deleted first, always. The path unit re-arms on the file existing, so leaving
|
||||
# it in place would run this again the moment the service came back -- an
|
||||
# update loop with no obvious cause. `-` so a failure to delete does not stop
|
||||
# the update, and `ExecStartPre` so it happens even if the script itself fails.
|
||||
ExecStartPre=-/usr/bin/rm -f __PREFIX__/data/update-requested
|
||||
Environment=SERVICE_USER=__SERVICE_USER__
|
||||
Environment=PREFIX=__PREFIX__
|
||||
Environment=LEMBAS_BRANCH=__UPDATE_BRANCH__
|
||||
ExecStart=/bin/bash __PREFIX__/app/deploy/update.sh
|
||||
# The script's own failure path prints the journal and exits non-zero, which is
|
||||
# what makes `systemctl status lembas-update` say what went wrong.
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
TimeoutStartSec=600
|
||||
Executable
+141
@@ -0,0 +1,141 @@
|
||||
#!/usr/bin/env bash
|
||||
# Create a Debian LXC container on a Proxmox host and install LLeMbas in it.
|
||||
#
|
||||
# A **wrapper around what already works**, not a second install path. It makes a
|
||||
# container, puts the dependencies in it, and runs `deploy/install.sh` inside --
|
||||
# which is the same script, doing the same things, so a fix to the installer
|
||||
# reaches this without anybody remembering. A parallel installer would be two
|
||||
# things to keep correct and one of them would rot.
|
||||
#
|
||||
# Run this on the Proxmox host, as root:
|
||||
#
|
||||
# CTID=140 SITE_HOST=chat.example ./deploy/lxc-install.sh
|
||||
#
|
||||
# Everything is overridable:
|
||||
#
|
||||
# CTID next free id the container's id
|
||||
# CT_HOSTNAME lembas hostname inside it
|
||||
# CT_STORAGE local-lvm where the rootfs goes
|
||||
# CT_TEMPLATE debian-12 template, matched against pveam list
|
||||
# CT_DISK 12 GB
|
||||
# CT_CORES 2
|
||||
# CT_MEMORY 4096 MB
|
||||
# CT_BRIDGE vmbr0
|
||||
# CT_IP dhcp or 192.168.1.50/24
|
||||
# CT_GATEWAY (unset) required when CT_IP is static
|
||||
# REPO_URL this checkout's origin
|
||||
# SITE_HOST lembas.local
|
||||
#
|
||||
# **Unprivileged, and that is not a default to change lightly.** Nothing LLeMbas
|
||||
# does needs privilege: agent chats run their commands over SSH on some *other*
|
||||
# machine, which is the whole isolation story. A privileged container would give
|
||||
# up the host's protection to buy nothing.
|
||||
set -euo pipefail
|
||||
|
||||
CT_HOSTNAME="${CT_HOSTNAME:-lembas}"
|
||||
CT_STORAGE="${CT_STORAGE:-local-lvm}"
|
||||
CT_TEMPLATE="${CT_TEMPLATE:-debian-12}"
|
||||
CT_DISK="${CT_DISK:-12}"
|
||||
CT_CORES="${CT_CORES:-2}"
|
||||
CT_MEMORY="${CT_MEMORY:-4096}"
|
||||
CT_BRIDGE="${CT_BRIDGE:-vmbr0}"
|
||||
CT_IP="${CT_IP:-dhcp}"
|
||||
CT_GATEWAY="${CT_GATEWAY:-}"
|
||||
SITE_HOST="${SITE_HOST:-lembas.local}"
|
||||
BRANCH="${LEMBAS_BRANCH:-main}"
|
||||
|
||||
HERE="$(dirname "$(readlink -f "$0")")"
|
||||
REPO_URL="${REPO_URL:-$(git -C "$HERE" remote get-url origin 2>/dev/null || true)}"
|
||||
|
||||
if ! command -v pct >/dev/null; then
|
||||
echo "pct not found. Run this on a Proxmox host." >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ -z "$REPO_URL" ]]; then
|
||||
echo "Could not determine REPO_URL. Set it explicitly." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
CTID="${CTID:-$(pvesh get /cluster/nextid)}"
|
||||
|
||||
# The template has to be on the host before a container can be made from it.
|
||||
# Matched by prefix rather than pinned to a filename, because the point release
|
||||
# in it moves and a hard-coded name would break on a host that downloaded a
|
||||
# different one.
|
||||
echo "== template =="
|
||||
template=$(pveam list local 2>/dev/null | awk -v want="$CT_TEMPLATE" '$1 ~ want {print $1}' | head -1)
|
||||
if [[ -z "$template" ]]; then
|
||||
available=$(pveam available --section system | awk -v want="$CT_TEMPLATE" '$2 ~ want {print $2}' | tail -1)
|
||||
if [[ -z "$available" ]]; then
|
||||
echo "No template matching '$CT_TEMPLATE'. Try: pveam available --section system" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo " downloading $available"
|
||||
pveam download local "$available"
|
||||
template="local:vztmpl/$available"
|
||||
fi
|
||||
echo " $template"
|
||||
|
||||
echo "== container $CTID =="
|
||||
if pct status "$CTID" >/dev/null 2>&1; then
|
||||
echo " $CTID already exists, using it"
|
||||
else
|
||||
net="name=eth0,bridge=$CT_BRIDGE,ip=$CT_IP"
|
||||
[[ -n "$CT_GATEWAY" ]] && net="$net,gw=$CT_GATEWAY"
|
||||
pct create "$CTID" "$template" \
|
||||
--hostname "$CT_HOSTNAME" \
|
||||
--cores "$CT_CORES" \
|
||||
--memory "$CT_MEMORY" \
|
||||
--rootfs "$CT_STORAGE:$CT_DISK" \
|
||||
--net0 "$net" \
|
||||
--unprivileged 1 \
|
||||
--features nesting=1 \
|
||||
--onboot 1
|
||||
echo " created"
|
||||
fi
|
||||
|
||||
pct start "$CTID" 2>/dev/null || true
|
||||
# `pct exec` returns before the container's own network is up, and the very next
|
||||
# thing this does is apt-get. Waiting on DNS resolving rather than on a fixed
|
||||
# sleep, because a fixed sleep is either too short on a slow host or wasted on a
|
||||
# fast one.
|
||||
echo "== waiting for the network =="
|
||||
for _ in $(seq 1 30); do
|
||||
pct exec "$CTID" -- getent hosts deb.debian.org >/dev/null 2>&1 && break
|
||||
sleep 2
|
||||
done
|
||||
|
||||
echo "== dependencies =="
|
||||
pct exec "$CTID" -- bash -lc '
|
||||
set -e
|
||||
export DEBIAN_FRONTEND=noninteractive
|
||||
apt-get update -qq
|
||||
apt-get install -y -qq --no-install-recommends \
|
||||
git python3 python3-venv python3-pip nginx openssl sudo ca-certificates
|
||||
'
|
||||
|
||||
echo "== checkout =="
|
||||
pct exec "$CTID" -- bash -lc "
|
||||
set -e
|
||||
rm -rf /tmp/lembas-src
|
||||
git clone --quiet --branch '$BRANCH' '$REPO_URL' /tmp/lembas-src
|
||||
"
|
||||
|
||||
# The same installer this repository ships, run inside. Everything it decides --
|
||||
# the service user, the prefix, the unit, the vhost, the self-signed certificate
|
||||
# -- it decides there, so this script has no opinions to keep in step with it.
|
||||
echo "== install =="
|
||||
pct exec "$CTID" -- bash -lc "
|
||||
set -e
|
||||
SITE_HOST='$SITE_HOST' LEMBAS_BRANCH='$BRANCH' REPO_URL='$REPO_URL' \
|
||||
bash /tmp/lembas-src/deploy/install.sh
|
||||
"
|
||||
|
||||
address=$(pct exec "$CTID" -- hostname -I 2>/dev/null | awk '{print $1}')
|
||||
echo
|
||||
echo "LLeMbas is installed in container $CTID."
|
||||
echo " address : ${address:-unknown}"
|
||||
echo " site : https://$SITE_HOST (self-signed; accept the warning)"
|
||||
echo
|
||||
echo "Point '$SITE_HOST' at ${address:-the container} in your DNS or hosts file,"
|
||||
echo "then create the first account -- it becomes the administrator."
|
||||
Reference in New Issue
Block a user