From 7d62ef84c48660d02df0dd925ec420641b97a936 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Sun, 9 Aug 2026 04:53:20 +0200 Subject: docs: add HTTPS.md + configure www.meshbay.org redirect MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Caddyfile updated: www → 301 → meshbay.org (canonical). Caddy auto-issued Let's Encrypt cert for www.meshbay.org in 4s. HTTPS.md explains the setup, cert lifecycle (90-day, auto-renewed), why 1-year certs are not recommended, DNS requirements. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- docs/HTTPS.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/HTTPS.md (limited to 'docs/HTTPS.md') diff --git a/docs/HTTPS.md b/docs/HTTPS.md new file mode 100644 index 0000000..2c1e13c --- /dev/null +++ b/docs/HTTPS.md @@ -0,0 +1,138 @@ +# MeshBay — HTTPS Certificate Setup + +> Server: meshbay.org (Ubuntu 26.04, OVH VPS) +> Proxy: Caddy 2.x +> Status: active as of 2026-08-09 + +--- + +## What was done + +### 1. Install Caddy + +Caddy is a modern web server that handles TLS certificate issuance and renewal automatically. No manual interaction with Let's Encrypt is required. + +```bash +sudo apt install -y caddy +sudo systemctl enable --now caddy +``` + +### 2. Configure the Caddyfile + +`/etc/caddy/Caddyfile`: + +``` +www.meshbay.org { + redir https://meshbay.org{uri} permanent +} + +meshbay.org { + reverse_proxy 127.0.0.1:8000 +} +``` + +What this does: +- `www.meshbay.org` → permanent 301 redirect to `meshbay.org` (canonical URL) +- `meshbay.org` → proxies all traffic to the uvicorn/FastAPI hub running on `127.0.0.1:8000` +- Caddy automatically handles TLS termination, HTTPS upgrade (HTTP→HTTPS redirect), and HTTP/2 + +### 3. Caddy obtains certificates automatically + +On first start or after a Caddyfile change, Caddy: +1. Registers with Let's Encrypt (ACME protocol) +2. Proves domain ownership via TLS-ALPN-01 challenge (no DNS or port 80 configuration needed) +3. Downloads the certificate chain +4. Stores certificates in `/var/lib/caddy/.local/share/caddy/` +5. Renews certificates automatically ~30 days before expiry + +```bash +sudo systemctl reload caddy # apply Caddyfile changes +sudo systemctl status caddy # check logs +``` + +The certificate for `www.meshbay.org` was obtained in ~4 seconds after the Caddyfile update. + +--- + +## Can we get a 1-year certificate? + +**Short answer: No, not from Let's Encrypt — and that's fine.** + +### Current situation (2026) + +Let's Encrypt certificates are valid for **90 days**. This is intentional: +- Short-lived certificates limit exposure if a private key is compromised +- Automation (via ACME) makes renewal transparent — no manual work needed +- Caddy renews automatically ~30 days before expiry + +Since Caddy handles renewal without any intervention, the 90-day limit is **completely transparent** to users and operators. The certificate is always valid; you will never see an expiry warning. + +### Why not 1 year? + +As of March 2026, the CA/Browser Forum voted to progressively reduce maximum certificate validity: +- 2026: 200 days max (not yet enforced by all CAs) +- 2027: 100 days max +- 2029: 47 days max + +The industry direction is **shorter**, not longer. Paid CAs (DigiCert, Sectigo) currently still issue 1-year certificates, but this will end within the next few years. + +### If you absolutely need a longer-lived certificate + +Options (all have trade-offs): + +| Option | Validity | Cost | Effort | +|---|---|---|---| +| Let's Encrypt + Caddy | 90 days (auto-renewed) | Free | None | +| ZeroSSL (ACME) | 90 days (auto-renewed) | Free | None | +| DigiCert / Sectigo | Up to 1 year (for now) | ~€50-150/year | Manual renewal | +| Self-signed | Any duration | Free | Clients will warn | + +**Recommendation: keep Let's Encrypt + Caddy.** It is effectively infinite-duration from an operational standpoint. Switching to a paid CA for a longer nominal validity provides no practical benefit and adds cost and manual renewal risk. + +--- + +## Troubleshooting + +```bash +# Check Caddy status and recent logs +sudo systemctl status caddy --no-pager -l + +# Validate the Caddyfile syntax before reloading +caddy validate --config /etc/caddy/Caddyfile + +# Force certificate renewal (normally not needed) +sudo systemctl stop caddy +sudo caddy run --config /etc/caddy/Caddyfile + +# View stored certificates +sudo ls /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/ +``` + +## Current certificate info + +```bash +# Check certificate from the outside +echo | openssl s_client -connect meshbay.org:443 -servername meshbay.org 2>/dev/null \ + | openssl x509 -noout -dates -subject +``` + +--- + +## DNS requirements + +For Let's Encrypt to work, DNS must resolve to this server **before** Caddy requests the certificate. + +- `meshbay.org` → A record → `164.132.246.44` +- `www.meshbay.org` → A record → `164.132.246.44` (or CNAME to `meshbay.org`) + +If the DNS is not pointing here, the TLS-ALPN-01 challenge will fail silently and Caddy will retry periodically. + +--- + +## Security notes + +- Caddy listens on ports 80 and 443 (allowed in UFW) +- HTTP requests on port 80 are automatically redirected to HTTPS by Caddy +- The hub (uvicorn) listens only on `127.0.0.1:8000` — not directly reachable from the internet +- Caddy enforces TLS 1.2+ by default (TLS 1.3 preferred) +- Port 8000 is NOT open in UFW (Caddy proxies internally) -- cgit v1.2.3