Update docs for Docker-on-deimos deployment, add grpc_plain_addr option

- ARCHITECTURE.md: document nginx + direct gRPC topology, add
  grpc_plain_addr config, update cert filenames to Let's Encrypt
  convention, add passwd to CLI table
- RUNBOOK.md: replace systemctl/journalctl with docker commands,
  fix cert path references, improve sync troubleshooting steps
- Example config: update cert paths, document grpc_plain_addr option
- grpcserver: add optional plaintext gRPC listener for reverse proxy
- config: add GRPCPlainAddr field

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-03-25 08:58:01 -07:00
parent 2185bbe563
commit 691301dade
6 changed files with 80 additions and 41 deletions

View File

@@ -226,13 +226,14 @@ Built with Go `html/template` + htmx. Embedded via `//go:embed`.
```toml
[server]
listen_addr = ":8443"
grpc_addr = ":9443"
tls_cert = "/srv/eng-pad-server/certs/cert.pem"
tls_key = "/srv/eng-pad-server/certs/key.pem"
listen_addr = ":8443" # REST API (HTTPS)
grpc_addr = ":9443" # gRPC (TLS, exposed directly)
grpc_plain_addr = "" # Optional plaintext gRPC for reverse proxy
tls_cert = "/srv/eng-pad-server/certs/fullchain.pem"
tls_key = "/srv/eng-pad-server/certs/privkey.pem"
[web]
listen_addr = ":8080"
listen_addr = ":8080" # Web UI (plain HTTP behind nginx)
base_url = "https://pad.metacircular.net"
[database]
@@ -255,13 +256,32 @@ level = "info"
## 9. Deployment
### Production (deimos.wntrmute.net)
Docker container behind nginx on deimos:
- **Web UI**: `https://pad.metacircular.net` — nginx (port 443) → container:8080
- **gRPC sync**: `pad.metacircular.net:9443` — direct TLS, exposed via ufw
- **REST API**: container:8443 — not exposed externally
- **TLS**: Let's Encrypt cert for `pad.metacircular.net`, shared by nginx
and the container (copied to `/srv/eng-pad-server/certs/`)
```
Internet
├── :443 → nginx (TLS termination) → container:8080 (Web UI, plain HTTP)
└── :9443 → container:9443 (gRPC, direct TLS)
```
### Container
Multi-stage Docker build:
1. Builder: `golang:1.25-alpine`, `CGO_ENABLED=0`, stripped binary
2. Runtime: `alpine:latest`, non-root user
2. Runtime: `alpine:3.21`, non-root user (`engpad`, UID 1000)
### systemd
### systemd (alternative)
systemd units are provided for non-Docker deployments:
| Unit | Purpose |
|------|---------|
@@ -279,8 +299,8 @@ ReadWritePaths=/srv/eng-pad-server.
├── eng-pad-server.toml
├── eng-pad-server.db
├── certs/
│ ├── cert.pem
│ └── key.pem
│ ├── fullchain.pem # Let's Encrypt cert chain
│ └── privkey.pem # Let's Encrypt private key
└── backups/
```
@@ -301,6 +321,7 @@ ReadWritePaths=/srv/eng-pad-server.
|---------|---------|
| server | Start the service |
| init | Create database, first user |
| passwd | Reset a user's password |
| snapshot | Database backup (VACUUM INTO) |
| status | Health check |