Houmeres/LLeMbas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Add registration toggle and password change; genericise deploy

Browse Source 
Two things the running instance needed.

**Registration toggle.** Admin -> General, backed by a new settings table
group rather than the environment. LEMBAS_ALLOW_SIGNUP now seeds only the
initial value: once an administrator saves the setting, the stored value
wins. The alternative -- environment always winning -- means a toggle in
the UI silently reverts on the next restart, which is worse than not
offering one. Closing registration also removes the "Create one" link
from the sign-in page, so the link never leads somewhere that refuses.

**Password change**, on the user settings page. Changing a password
revokes every other session and immediately re-issues a cookie for the
current one: if the reason for the change is that somebody else knows
the password, leaving their session alive defeats the point, but signing
the user out of the tab they are standing in is merely rude.

**deploy/ is now host-agnostic.** This repository is public, so the unit
and vhost became templates with __PREFIX__ / __SITE_HOST__ / __APP_PORT__
substituted at install time, and every path, hostname and port moved to
environment variables. REPO_URL defaults to the checkout's own origin so
a fork deploys itself. Machine-specific values belong in private notes,
not here -- CLAUDE.md now says so.

83 tests, ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jaroslav Beneš
2026-07-21 11:14:33 +02:00
parent 0f44e8d24c
commit 9179461bfe
16 changed files with 713 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/README.md
+43 -33
View File
@@ -1,51 +1,63 @@
# Deployment
Installs LLeMbas as a **system** service behind nginx at `https://chat.lan`.
Installs LLeMbas as a **system** service behind nginx with a self-signed
certificate. Written for a systemd + nginx host; tested on Arch.
Written for `gamebox` (Arch), and follows the conventions already used there
for llama-swap and comfyui:
| | |
| | Default |
|---|---|
| Service user | `lembas` (system account, `nologin`) |
| Home | `/home/lembas`, bind-mounted to `/srv/lembas` |
| Checkout | `/srv/lembas/app` (git clone of the Gitea remote) |
| Virtualenv | `/srv/lembas/venv` |
| Database | `/srv/lembas/data/lembas.db` |
| Environment | `/srv/lembas/lembas.env` (mode 600) |
| Home | `/home/lembas` |
| Install prefix | `/srv/lembas` (bind mount of the home) |
| Checkout | `$PREFIX/app` |
| Virtualenv | `$PREFIX/venv` |
| Database | `$PREFIX/data/lembas.db` |
| Environment | `$PREFIX/lembas.env` (mode 600) |
| Unit | `/etc/systemd/system/lembas.service` |
| Vhost | `/etc/nginx/conf.d/chat.lan.conf`, self-signed cert |
| Listens | `127.0.0.1:8080` — reachable only through nginx |
| Vhost | `/etc/nginx/conf.d/<host>.conf` |
| Listens on | `127.0.0.1:8080` — reachable only through nginx |
The home lives on `/home` rather than `/var/lib` because the root LV on that
box is only 50 GB; `/srv/lembas` is the same bind-mount trick as `/srv/llama`
and `/srv/comfyui`.
The prefix defaults to a bind mount of the service user's home because on many
machines the root filesystem is small while `/home` is not, and the virtualenv
plus database belong on the larger volume. Set `PREFIX=$HOME_DIR` to skip it.
## First install
```bash
./deploy/install.sh
SITE_HOST=chat.example ./deploy/install.sh
```
Idempotent — safe to re-run. It creates the user and bind mount, clones the
repo, builds the venv, generates `lembas.env` with a fresh
`LEMBAS_SECRET_KEY`, installs the unit and vhost, issues a self-signed cert,
adds a `/etc/hosts` entry, and enables the service.
repo, builds the venv, generates `lembas.env` with a fresh `LEMBAS_SECRET_KEY`,
installs the unit and vhost, issues a self-signed certificate, adds a
`/etc/hosts` entry if the name does not already resolve, and enables the
service.
Then open <https://chat.lan>, accept the self-signed certificate warning, and
create the first account — it becomes the administrator.
Then open `https://<SITE_HOST>`, accept the certificate warning, and create the
first account — it becomes the administrator.
Everything is overridable from the environment:
| Variable | Default | |
|---|---|---|
| `SITE_HOST` | `lembas.local` | nginx `server_name` and certificate CN |
| `APP_PORT` | `8080` | loopback port the service binds |
| `SERVICE_USER` | `lembas` | system account to run as |
| `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 |
## Deploying a change
```bash
git push # from the working copy
git push
./deploy/update.sh
```
`update.sh` fetches, hard-resets `/srv/lembas/app` to `origin/main`, reinstalls
dependencies and restarts the service, then prints what changed. The hard reset
is deliberate: nothing is ever edited in place there, so there is no local work
to preserve and no merge conflicts to resolve.
`update.sh` fetches, hard-resets the deployment checkout to `origin/main`,
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.
## Operating it
@@ -53,10 +65,9 @@ to preserve and no merge conflicts to resolve.
systemctl status lembas
journalctl -u lembas -f
sudo -u lembas /srv/lembas/venv/bin/lembas info # paths and counts
sudo systemctl restart lembas
```
Configuration lives in `/srv/lembas/lembas.env`. Edit it and restart.
Configuration lives in `$PREFIX/lembas.env`. Edit it and restart.
## Notes
@@ -70,11 +81,10 @@ delivers it in one lump at the end, which is indistinguishable from streaming
being broken. `proxy_read_timeout` is raised to an hour because a model can
think for minutes before the first token.
**Name resolution.** `chat.lan` is in Pi-hole, but this box queries the router
first and the router's dnsmasq is authoritative for `.lan` without forwarding
those queries on — the same reason `comfy.lan` needs one. `install.sh` adds a
`/etc/hosts` entry, which is harmless if DNS already answers.
**Hardening is deliberately moderate.** `ProtectSystem=full`, not `strict`: the
agentic features planned for later need to run commands, and a lockdown that
has to be torn out again is worse than one that was never applied.
**Use a real certificate if this is exposed beyond a trusted LAN.** The
self-signed cert exists so the install works with no external dependencies;
point `ssl_certificate` at a real one and nothing else needs to change.
deploy/install.sh
+67 -37
View File
@@ -1,28 +1,52 @@
#!/usr/bin/env bash
# Install LLeMbas as a system service behind nginx at https://chat.lan.
# Install LLeMbas as a system service behind nginx with a self-signed cert.
#
# Follows the conventions already used on this box for llama-swap and comfyui:
# a dedicated service user whose home lives on /home (the root LV is only
# 50 GB) and is bind-mounted to /srv/<name>, a system unit so it survives
# logout, and an nginx vhost with a self-signed cert.
# Creates a dedicated service user, a virtualenv, a systemd unit and an nginx
# vhost. Idempotent: safe to re-run. To deploy new code afterwards use
# update.sh, which is what a `git push` should be followed by.
#
# Idempotent: safe to re-run. To deploy new code afterwards use update.sh,
# which is what a `git push` should be followed by.
# Everything is configurable from the environment:
#
# SITE_HOST=chat.example ./deploy/install.sh # vhost name
# APP_PORT=8080 # loopback port
# PREFIX=/srv/lembas # install root
# HOME_DIR=/home/lembas # service user's home
# REPO_URL=... # defaults to this checkout's origin
#
# PREFIX defaults to a bind mount of HOME_DIR rather than living directly under
# /srv, because on many machines the root filesystem is small and the venv plus
# database belong on the larger /home volume. Set PREFIX=HOME_DIR to skip that.
set -euo pipefail
REPO_URL="${LEMBAS_REPO_URL:-https://git.houmeres.sk/Houmeres/LLeMbas.git}"
HERE="$(dirname "$(readlink -f "$0")")"
SITE_HOST="${SITE_HOST:-lembas.local}"
APP_PORT="${APP_PORT:-8080}"
SERVICE_USER="${SERVICE_USER:-lembas}"
HOME_DIR="${HOME_DIR:-/home/lembas}"
PREFIX="${PREFIX:-/srv/lembas}"
BRANCH="${LEMBAS_BRANCH:-main}"
SERVICE_USER=lembas
HOME_DIR=/home/lembas
PREFIX=/srv/lembas
# 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)}"
APP="$PREFIX/app"
VENV="$PREFIX/venv"
ENV_FILE="$PREFIX/lembas.env"
HERE="$(dirname "$(readlink -f "$0")")"
if [[ -z "$REPO_URL" ]]; then
echo "Could not determine REPO_URL. Set it explicitly." >&2
exit 1
fi
echo "== plan =="
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)"
echo "== service user =="
# --system: no ageing, no mail spool. Home under /home, not /var/lib, so the
# venv and database sit on the big volume.
# venv and database sit on the larger volume.
if ! getent passwd "$SERVICE_USER" >/dev/null; then
sudo useradd --system --create-home --home-dir "$HOME_DIR" \
--shell /usr/bin/nologin --comment "LLeMbas" "$SERVICE_USER"
@@ -31,12 +55,14 @@ else
fi
sudo chmod 755 "$HOME_DIR"
echo "== /srv/lembas bind-mount onto /home =="
sudo mkdir -p "$PREFIX"
grep -q "^$HOME_DIR[[:space:]]" /etc/fstab \
|| echo "$HOME_DIR $PREFIX none bind 0 0" | sudo tee -a /etc/fstab >/dev/null
sudo systemctl daemon-reload
mountpoint -q "$PREFIX" || sudo mount "$PREFIX"
if [[ "$PREFIX" != "$HOME_DIR" ]]; then
echo "== $PREFIX bind-mount onto $HOME_DIR =="
sudo mkdir -p "$PREFIX"
grep -q "^$HOME_DIR[[:space:]]" /etc/fstab \
|| echo "$HOME_DIR $PREFIX none bind 0 0" | sudo tee -a /etc/fstab >/dev/null
sudo systemctl daemon-reload
mountpoint -q "$PREFIX" || sudo mount "$PREFIX"
fi
echo "== checkout =="
if [[ ! -d "$APP/.git" ]]; then
@@ -53,8 +79,8 @@ sudo -u "$SERVICE_USER" "$VENV/bin/pip" install --quiet --upgrade pip
sudo -u "$SERVICE_USER" "$VENV/bin/pip" install --quiet -e "$APP"
echo "== environment =="
# Generated once and never regenerated: rotating LEMBAS_SECRET_KEY would sign
# every user out and make the stored API keys unreadable.
# Generated once and never regenerated: rotating LEMBAS_SECRET_KEY signs every
# user out AND makes the stored upstream API keys unreadable.
if [[ ! -f "$ENV_FILE" ]]; then
KEY=$("$VENV/bin/python" -c "import secrets; print(secrets.token_urlsafe(48))")
sudo tee "$ENV_FILE" >/dev/null <<EOF
@@ -63,9 +89,9 @@ if [[ ! -f "$ENV_FILE" ]]; then
# Changing it signs everyone out and makes stored API keys unreadable.
LEMBAS_SECRET_KEY=$KEY
LEMBAS_DATA_DIR=$PREFIX/data
# Loopback only: reachable through the nginx chat.lan vhost, never direct.
# Loopback only: reachable through the nginx vhost, never directly.
LEMBAS_HOST=127.0.0.1
LEMBAS_PORT=8080
LEMBAS_PORT=$APP_PORT
LEMBAS_LOG_LEVEL=info
LEMBAS_ALLOW_SIGNUP=true
LEMBAS_DEFAULT_THEME=moria
@@ -80,30 +106,34 @@ fi
sudo install -d -o "$SERVICE_USER" -g "$SERVICE_USER" -m 750 "$PREFIX/data"
echo "== systemd unit =="
sudo install -Dm644 "$HERE/lembas.service" /etc/systemd/system/lembas.service
sed -e "s|__PREFIX__|$PREFIX|g" -e "s|__SERVICE_USER__|$SERVICE_USER|g" \
"$HERE/lembas.service" | sudo tee /etc/systemd/system/lembas.service >/dev/null
sudo systemctl daemon-reload
echo "== self-signed cert for chat.lan =="
echo "== self-signed cert for $SITE_HOST =="
sudo mkdir -p /etc/nginx/ssl
if [[ ! -f /etc/nginx/ssl/chat.lan.crt ]]; then
if [[ ! -f "/etc/nginx/ssl/$SITE_HOST.crt" ]]; then
sudo openssl req -x509 -newkey rsa:2048 -nodes \
-keyout /etc/nginx/ssl/chat.lan.key -out /etc/nginx/ssl/chat.lan.crt \
-days 3650 -subj "/CN=chat.lan" -addext "subjectAltName=DNS:chat.lan"
sudo chmod 600 /etc/nginx/ssl/chat.lan.key
sudo chmod 644 /etc/nginx/ssl/chat.lan.crt
-keyout "/etc/nginx/ssl/$SITE_HOST.key" -out "/etc/nginx/ssl/$SITE_HOST.crt" \
-days 3650 -subj "/CN=$SITE_HOST" -addext "subjectAltName=DNS:$SITE_HOST"
sudo chmod 600 "/etc/nginx/ssl/$SITE_HOST.key"
sudo chmod 644 "/etc/nginx/ssl/$SITE_HOST.crt"
fi
echo "== nginx vhost =="
sudo install -Dm644 "$HERE/chat.lan.nginx.conf" /etc/nginx/conf.d/chat.lan.conf
sed -e "s|__SITE_HOST__|$SITE_HOST|g" -e "s|__APP_PORT__|$APP_PORT|g" \
"$HERE/nginx-vhost.conf" | sudo tee "/etc/nginx/conf.d/$SITE_HOST.conf" >/dev/null
sudo nginx -t
sudo systemctl reload nginx
echo "== local name resolution =="
# chat.lan is in Pi-hole, but this box asks the router first and the router's
# dnsmasq is authoritative for .lan without forwarding it on -- same reason
# comfy.lan needs a hosts entry. Harmless if DNS already resolves it.
grep -q 'chat\.lan' /etc/hosts \
|| printf '127.0.0.1\tchat.lan\n::1\t\tchat.lan\n' | sudo tee -a /etc/hosts >/dev/null
# Only useful when the LAN's DNS does not already answer for this name.
if ! getent hosts "$SITE_HOST" >/dev/null; then
printf '127.0.0.1\t%s\n::1\t\t%s\n' "$SITE_HOST" "$SITE_HOST" | sudo tee -a /etc/hosts >/dev/null
echo " added $SITE_HOST to /etc/hosts"
else
echo " $SITE_HOST already resolves"
fi
echo "== enable service =="
sudo systemctl enable --now lembas
@@ -111,5 +141,5 @@ sleep 2
sudo systemctl --no-pager --lines=0 status lembas || true
echo
echo "LLeMbas is up at https://chat.lan (self-signed cert; accept the warning)"
echo "LLeMbas is up at https://$SITE_HOST (self-signed cert; accept the warning)"
echo "Create the first account -- it becomes the administrator."
deploy/lembas.service
+18 -23
View File
@@ -1,48 +1,43 @@
# LLeMbas system service.
# LLeMbas system service template.
#
# Deployed to /etc/systemd/system/lembas.service by deploy/install.sh.
# install.sh substitutes __PREFIX__ and __SERVICE_USER__ and writes the result
# to /etc/systemd/system/lembas.service. Edit this file, not the installed copy.
#
# A system unit, not a user unit, so it survives logout and comes up at boot
# without anyone signing in -- matching llama-swap and comfyui on this box.
#
# /srv/lembas is a bind mount of /home/lembas: the root LV is only 50 GB and
# the venv plus SQLite database belong on /home, same trick as /srv/llama.
# without anyone signing in.
[Unit]
Description=LLeMbas - web UI for language models
Documentation=https://git.houmeres.sk/Houmeres/LLeMbas
After=network-online.target
Wants=network-online.target
# The unit is useless without the bind mount: the venv and database live there.
RequiresMountsFor=/srv/lembas
# Not a hard dependency. LLeMbas starts fine with the endpoint down and shows a
# readable error in the admin UI, which is better than refusing to boot.
After=llama-swap.service
# The prefix is usually a bind mount; the venv and database live there, so
# starting before it is mounted would create an empty database in its place.
RequiresMountsFor=__PREFIX__
[Service]
Type=simple
User=lembas
Group=lembas
WorkingDirectory=/srv/lembas/app
EnvironmentFile=/srv/lembas/lembas.env
ExecStart=/srv/lembas/venv/bin/lembas serve
User=__SERVICE_USER__
Group=__SERVICE_USER__
WorkingDirectory=__PREFIX__/app
EnvironmentFile=__PREFIX__/lembas.env
ExecStart=__PREFIX__/venv/bin/lembas serve
Restart=on-failure
RestartSec=5
# Reachable only through the nginx chat.lan vhost, never directly on the LAN.
# The bind address is set by LEMBAS_HOST in the environment file.
# The bind address comes from LEMBAS_HOST in the environment file, which the
# installer sets to 127.0.0.1: reachable through nginx, never directly.
# --- Hardening -------------------------------------------------------------
# Modest rather than maximal: the agentic features planned for later will need
# to run commands, so ProtectSystem=strict would only be torn out again.
# Moderate rather than maximal. The agentic features planned for later need to
# run commands, and a lockdown that has to be torn out again is worse than one
# that was never applied.
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
ProtectKernelTunables=yes
ProtectControlGroups=yes
RestrictSUIDSGID=yes
# Only /srv/lembas needs to be writable; /home/lembas is the same inode.
ReadWritePaths=/srv/lembas
ReadWritePaths=__PREFIX__
LimitNOFILE=65535
[Install]
deploy/chat.lan.nginx.conf → deploy/nginx-vhost.conf
+18 -14
View File
@@ -1,12 +1,16 @@
# chat.lan - HTTPS reverse proxy to LLeMbas (127.0.0.1:8080).
# Deployed to /etc/nginx/conf.d/chat.lan.conf. Self-signed cert (chat.lan).
# nginx vhost template for LLeMbas.
#
# Mirrors the comfy.lan and llama.lan vhosts on this box.
# install.sh substitutes __SITE_HOST__ and __APP_PORT__ and writes the result to
# /etc/nginx/conf.d/<host>.conf. Edit this file, not the installed copy.
#
# Assumes a self-signed certificate at /etc/nginx/ssl/<host>.{crt,key}, which
# install.sh generates. To use a real certificate, point ssl_certificate at it;
# nothing else here needs to change.
server {
listen 80;
listen [::]:80;
server_name chat.lan;
server_name __SITE_HOST__;
return 301 https://$host$request_uri;
}
@@ -14,17 +18,17 @@ server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name chat.lan;
server_name __SITE_HOST__;
ssl_certificate /etc/nginx/ssl/chat.lan.crt;
ssl_certificate_key /etc/nginx/ssl/chat.lan.key;
ssl_certificate /etc/nginx/ssl/__SITE_HOST__.crt;
ssl_certificate_key /etc/nginx/ssl/__SITE_HOST__.key;
ssl_protocols TLSv1.2 TLSv1.3;
# File uploads land here once that feature exists; 0 = no limit.
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_pass http://127.0.0.1:__APP_PORT__;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
@@ -32,13 +36,14 @@ server {
proxy_set_header X-Forwarded-Proto $scheme;
# Streamed replies are server-sent events. Every one of these matters:
# with buffering on, nginx holds the whole reply and delivers it in one
# lump at the end, which looks exactly like streaming being broken.
# with buffering on (the default) nginx holds the whole reply and
# delivers it in one lump at the end, which is indistinguishable from
# streaming being broken.
proxy_buffering off;
proxy_request_buffering off;
proxy_cache off;
# SSE is plain HTTP/1.1 chunked, so the connection header must not be
# the websocket upgrade dance -- it must simply stay open.
# SSE is plain HTTP/1.1 chunked, not a websocket upgrade, so the
# connection header must simply be left to keep-alive.
proxy_set_header Connection "";
# A model can think for minutes before the first token. The default
@@ -47,9 +52,8 @@ server {
proxy_send_timeout 3600s;
}
# Static assets are immutable per release and never need revalidating.
location /static/ {
proxy_pass http://127.0.0.1:8080;
proxy_pass http://127.0.0.1:__APP_PORT__;
proxy_set_header Host $host;
expires 1h;
add_header Cache-Control "public";
deploy/update.sh
+19 -16
View File
@@ -1,36 +1,39 @@
#!/usr/bin/env bash
# Pull the latest LLeMbas and restart the service.
# Pull the latest LLeMbas into the deployment and restart the service.
#
# This is what to run after pushing: it fetches, hard-resets the deployment
# checkout to the remote branch, reinstalls dependencies if they changed, and
# restarts. Nothing is ever edited in place at /srv/lembas/app, so a hard reset
# is safe and avoids merge conflicts from a dirty deployment tree.
# Run this after pushing. It fetches, hard-resets the deployment checkout to the
# remote branch, reinstalls dependencies if they changed, and restarts. Nothing
# is ever edited in place under the deployment prefix, so a hard reset is safe
# and avoids merge conflicts from a dirty tree.
set -euo pipefail
SERVICE_USER=lembas
PREFIX=/srv/lembas
SERVICE_USER="${SERVICE_USER:-lembas}"
PREFIX="${PREFIX:-/srv/lembas}"
BRANCH="${LEMBAS_BRANCH:-main}"
APP="$PREFIX/app"
VENV="$PREFIX/venv"
BRANCH="${LEMBAS_BRANCH:-main}"
if [[ ! -d "$APP/.git" ]]; then
echo "No deployment at $APP. Run deploy/install.sh first." >&2
exit 1
fi
before=$(sudo -u "$SERVICE_USER" git -C "$APP" rev-parse HEAD)
git_as() { sudo -u "$SERVICE_USER" git -C "$APP" "$@"; }
before=$(git_as rev-parse HEAD)
echo "== fetching =="
sudo -u "$SERVICE_USER" git -C "$APP" fetch --quiet origin "$BRANCH"
sudo -u "$SERVICE_USER" git -C "$APP" reset --hard --quiet "origin/$BRANCH"
git_as fetch --quiet origin "$BRANCH"
git_as reset --hard --quiet "origin/$BRANCH"
after=$(sudo -u "$SERVICE_USER" git -C "$APP" rev-parse HEAD)
after=$(git_as rev-parse HEAD)
if [[ "$before" == "$after" ]]; then
echo " already at $(git -C "$APP" rev-parse --short HEAD), nothing to pull"
echo " already at ${after:0:7}, nothing to pull"
else
echo " $(echo "$before" | cut -c1-7) -> $(echo "$after" | cut -c1-7)"
sudo -u "$SERVICE_USER" git -C "$APP" --no-pager log --oneline "$before..$after" | sed 's/^/ /'
echo " ${before:0:7} -> ${after:0:7}"
git_as --no-pager log --oneline "$before..$after" | sed 's/^/ /'
fi
# Cheap and idempotent; catches a dependency added since the last deploy.
@@ -42,7 +45,7 @@ sudo systemctl restart lembas
sleep 2
if systemctl is-active --quiet lembas; then
echo " lembas is running at https://chat.lan"
echo " lembas is running"
else
echo " lembas FAILED to start:" >&2
sudo journalctl -u lembas -n 30 --no-pager >&2