Add passwd command, fix template rendering, update deployment docs
- Add `passwd` CLI command to reset user passwords - Fix web UI templates: parse each page template with layout so blocks render correctly (was outputting empty pages) - Add login error logging for debugging auth failures - Update README with deploy workflow and container management commands - Update RUNBOOK for Docker-on-deimos deployment (replaces systemd refs) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
125
RUNBOOK.md
125
RUNBOOK.md
@@ -6,31 +6,29 @@ eng-pad-server receives engineering notebook data from the Engineering
|
||||
Pad Android app via gRPC, stores it in SQLite, and serves read-only
|
||||
views through a web UI. Single authenticated user.
|
||||
|
||||
**Ports**: 8443 (REST/HTTPS), 9443 (gRPC/TLS), 8080 (Web UI)
|
||||
**Host**: deimos.wntrmute.net
|
||||
**URL**: https://pad.metacircular.net
|
||||
**Ports**: 443 (nginx → 8080 web UI), 8443 (REST/TLS), 9443 (gRPC/TLS)
|
||||
**Data**: `/srv/eng-pad-server/`
|
||||
**Config**: `/srv/eng-pad-server/eng-pad-server.toml`
|
||||
**Binary**: `/usr/local/bin/eng-pad-server`
|
||||
**TLS**: Let's Encrypt (`/etc/letsencrypt/live/pad.metacircular.net/`), copied to `/srv/eng-pad-server/certs/`
|
||||
**Container**: `eng-pad-server` (Docker, `--restart unless-stopped`)
|
||||
|
||||
## 2. Health Checks
|
||||
|
||||
1. Check service is running:
|
||||
1. Check container is running:
|
||||
```
|
||||
systemctl status eng-pad-server
|
||||
docker ps | grep eng-pad-server
|
||||
```
|
||||
|
||||
2. Check database health:
|
||||
2. Check web UI responds:
|
||||
```
|
||||
eng-pad-server status -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
curl -s https://pad.metacircular.net/login | head -1
|
||||
```
|
||||
|
||||
3. Check web UI responds:
|
||||
3. Check container logs:
|
||||
```
|
||||
curl -k https://localhost:8443/login
|
||||
```
|
||||
|
||||
4. Check gRPC responds:
|
||||
```
|
||||
grpcurl -insecure localhost:9443 list
|
||||
docker logs eng-pad-server --tail 20
|
||||
```
|
||||
|
||||
## 3. Common Operations
|
||||
@@ -38,84 +36,69 @@ views through a web UI. Single authenticated user.
|
||||
### Start / Stop / Restart
|
||||
|
||||
```
|
||||
systemctl start eng-pad-server
|
||||
systemctl stop eng-pad-server
|
||||
systemctl restart eng-pad-server
|
||||
docker start eng-pad-server
|
||||
docker stop eng-pad-server
|
||||
docker restart eng-pad-server
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```
|
||||
journalctl -u eng-pad-server -f
|
||||
docker logs eng-pad-server -f
|
||||
```
|
||||
|
||||
### Deploy New Version
|
||||
|
||||
```bash
|
||||
# From local machine:
|
||||
rsync -az --exclude='.git' --exclude='srv/' . deimos.wntrmute.net:/tmp/eng-pad-server-build/
|
||||
ssh deimos.wntrmute.net "cd /tmp/eng-pad-server-build && \
|
||||
docker build -t eng-pad-server . && \
|
||||
docker stop eng-pad-server && docker rm eng-pad-server && \
|
||||
docker run -d --name eng-pad-server --restart unless-stopped \
|
||||
-p 127.0.0.1:8090:8080 -p 8443:8443 -p 9443:9443 \
|
||||
-v /srv/eng-pad-server:/srv/eng-pad-server eng-pad-server"
|
||||
```
|
||||
|
||||
### Create User
|
||||
|
||||
```
|
||||
docker exec -it eng-pad-server \
|
||||
eng-pad-server init -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
### Reset User Password
|
||||
|
||||
```
|
||||
docker exec -it eng-pad-server \
|
||||
eng-pad-server passwd <username> -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
### Manual Backup
|
||||
|
||||
```
|
||||
eng-pad-server snapshot -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
docker exec eng-pad-server \
|
||||
eng-pad-server snapshot -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
Backup saved to `/srv/eng-pad-server/backups/`.
|
||||
|
||||
### Check Backup Timer
|
||||
### Renew TLS Certificates
|
||||
|
||||
After certbot renews the Let's Encrypt cert:
|
||||
```
|
||||
systemctl list-timers eng-pad-server-backup.timer
|
||||
sudo cp /etc/letsencrypt/live/pad.metacircular.net/{fullchain,privkey}.pem \
|
||||
/srv/eng-pad-server/certs/
|
||||
docker restart eng-pad-server
|
||||
```
|
||||
|
||||
### Initialize (First Time)
|
||||
|
||||
1. Install the binary and config:
|
||||
```
|
||||
sudo deploy/scripts/install.sh
|
||||
```
|
||||
|
||||
2. Edit the config file:
|
||||
```
|
||||
sudo -u engpad vi /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
3. Generate TLS certificates (or copy existing ones):
|
||||
```
|
||||
# Self-signed for development:
|
||||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
|
||||
-keyout /srv/eng-pad-server/certs/key.pem \
|
||||
-out /srv/eng-pad-server/certs/cert.pem \
|
||||
-days 3650 -nodes -subj '/CN=pad.metacircular.net'
|
||||
chown engpad:engpad /srv/eng-pad-server/certs/*.pem
|
||||
chmod 600 /srv/eng-pad-server/certs/key.pem
|
||||
```
|
||||
|
||||
4. Create the admin user:
|
||||
```
|
||||
eng-pad-server init -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
5. Start the service:
|
||||
```
|
||||
systemctl enable --now eng-pad-server
|
||||
systemctl enable --now eng-pad-server-backup.timer
|
||||
```
|
||||
|
||||
### Register a FIDO2/U2F Security Key
|
||||
|
||||
1. Log in to the web UI with password.
|
||||
1. Log in to the web UI at https://pad.metacircular.net with password.
|
||||
2. Navigate to `/keys`.
|
||||
3. Enter a name for the key (e.g., "YubiKey 5").
|
||||
4. Click "Register" and touch the key when prompted.
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```
|
||||
cd deploy/docker
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
First-time setup inside the container:
|
||||
```
|
||||
docker compose exec eng-pad-server eng-pad-server init -c /srv/eng-pad-server/eng-pad-server.toml
|
||||
```
|
||||
|
||||
## 4. Alerting
|
||||
|
||||
No automated alerting is configured. Monitor via:
|
||||
@@ -129,12 +112,12 @@ No automated alerting is configured. Monitor via:
|
||||
|
||||
1. Check logs:
|
||||
```
|
||||
journalctl -u eng-pad-server -n 50 --no-pager
|
||||
docker logs eng-pad-server --tail 50
|
||||
```
|
||||
2. Common causes:
|
||||
- Config file missing or invalid → fix config
|
||||
- TLS cert/key missing → regenerate or copy
|
||||
- Port already in use → `ss -tlnp | grep 8443`
|
||||
- Config file missing or invalid → fix `/srv/eng-pad-server/eng-pad-server.toml`
|
||||
- TLS cert/key missing → re-copy from Let's Encrypt (see Renew TLS above)
|
||||
- Port already in use → `ss -tlnp | grep -E '8443|9443|8090'`
|
||||
- Database locked → check for zombie processes: `fuser /srv/eng-pad-server/eng-pad-server.db`
|
||||
|
||||
### Database Corruption
|
||||
|
||||
Reference in New Issue
Block a user