docs: replace nginx with Caddy across all documentation and installer

This commit is contained in:
2026-07-26 21:10:45 +02:00
parent 4dd7b6991d
commit 9457d3f8cc
8 changed files with 239 additions and 180 deletions
+17 -21
View File
@@ -1,6 +1,6 @@
# Production Deployment
This guide covers installing nuntius on a Linux server with `nginx`, `systemd`, and `rsync` already in place — the same setup used by [petrbalvin.org](https://www.petrbalvin.org). The same `rsync -avz` workflow that ships the static website works for nuntius with no changes.
This guide covers installing nuntius on a Linux server with `Caddy`, `systemd`, and `rsync` already in place — the same setup used by [petrbalvin.org](https://www.petrbalvin.org). The same `rsync -avz` workflow that ships the static website works for nuntius with no changes.
## Architecture in Production
@@ -8,21 +8,21 @@ This guide covers installing nuntius on a Linux server with `nginx`, `systemd`,
graph LR
Browser[Visitor's browser]:::accent6
Internet((Internet)):::accent2
Nginx[nginx :443]:::accent0
Caddy[Caddy :443]:::accent0
Nuntius[nuntius :8080]:::accent1
Systemd[systemd unit]:::accent7
SMTP[(SMTP provider)]:::accent2
Disk[(/var/lib/nuntius/data/*.jsonl)]:::accent2
Browser --> Internet
Internet --> Nginx
Nginx -->|proxy_pass /api/nuntius/| Nuntius
Internet --> Caddy
Caddy -->|reverse_proxy /api/nuntius/| Nuntius
Systemd -.->|manages| Nuntius
Nuntius -->|SMTP PLAIN| SMTP
Nuntius -->|append JSONL| Disk
```
nuntius listens on `127.0.0.1:8080` (default). nginx terminates TLS on `:443` and proxies `/api/nuntius/*` to the upstream. systemd restarts the process on failure.
nuntius binds `[::]:8080` by default — the dual-stack IPv6 wildcard that accepts both IPv4 and IPv6 connections on Linux and FreeBSD. Caddy should be configured to proxy to `[::1]:8080` or `127.0.0.1:8080` for loopback-only access.
## 1. Build and Upload (Local Machine)
@@ -121,35 +121,31 @@ The script is idempotent: re-running on an already-installed host is safe. It:
The script ends with the exact next steps you need to run by hand.
## 3. nginx Reverse Proxy
## 3. Caddy Reverse Proxy
Add this location block to the same nginx server that already serves your site (most likely `/etc/nginx/sites-available/petrbalvin.org`):
Add this directive to your Caddyfile (most likely `/etc/caddy/Caddyfile`):
```nginx
location /api/nuntius/ {
proxy_pass http://127.0.0.1:8080/api/nuntius/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
```caddyfile
handle_path /api/nuntius/* {
reverse_proxy 127.0.0.1:8080
}
```
Then:
```bash
sudo nginx -t
sudo systemctl reload nginx
sudo caddy validate
sudo systemctl reload caddy
```
Without `X-Forwarded-For`, the rate limiter will see every request as coming from `127.0.0.1` and effectively become useless once the form is live. The `Host` header also matters for vhost-aware upstreams; the default is fine for a single nuntius instance.
Caddy forwards `X-Forwarded-For` automatically — so the real client IP is always passed to nuntius without any extra configuration.
## 4. Wire It Up to Your Web
If you proxy `/api/nuntius/*` through nginx (recommended, step 3 above), `VITE_NUNTIUS_URL` can stay empty and the form will post to the same origin as the page. Otherwise, set it to the bare upstream URL:
If you proxy `/api/nuntius/*` through Caddy (recommended, step 3 above), `VITE_NUNTIUS_URL` can stay empty and the form will post to the same origin as the page. Otherwise, set it to the bare upstream URL:
```bash
# .env (in the web project, only needed if NOT proxying through nginx)
# .env (in the web project, only needed if NOT proxying through Caddy)
VITE_NUNTIUS_URL=https://your-server:8080
```
@@ -227,10 +223,10 @@ curl -s http://127.0.0.1:8080/health | jq .
# Recent log lines
journalctl -u nuntius -n 50 --no-pager
# nginx proxy works
# Caddy proxy works
curl -i https://your-domain.example/api/nuntius/health
# End-to-end POST through nginx
# End-to-end POST through Caddy
curl -X POST https://your-domain.example/api/nuntius/contact \
-H "Content-Type: application/json" \
-H "Origin: https://your-domain.example" \