From 1cfae51620a9bf14217d58491c04946e403f0f88 Mon Sep 17 00:00:00 2001
From: Hikari <hikari@nhcarrigan.com>
Date: Tue, 10 Mar 2026 12:59:07 -0700
Subject: [PATCH] docs: add CLAUDE.md with 404 handling and site setup notes

---
 CLAUDE.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6b90abd
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,29 @@
+# NGINX Configs — Project Notes
+
+## 404 Handling
+
+### Global 404 redirect
+Any 404 from any site is handled globally via `nginx/nginx/nginx.conf` in the `http {}` block:
+
+```nginx
+error_page 404 https://404.nhcarrigan.com;
+```
+
+This redirects (302) to `404.nhcarrigan.com` which serves `/home/naomi/404/index.html`.
+No need to add `error_page` to individual server blocks — the `http {}` level default covers everything.
+
+### 404 site config
+`nginx/nginx/sites-available/404.conf` — serves the static 404 page at `/home/naomi/404`.
+Requires an SSL cert at `/etc/letsencrypt/live/404.nhcarrigan.com/`.
+
+### Catch-all server block (`catch-all.conf`)
+Handles any HTTPS request for a subdomain that doesn't match any configured `server_name`.
+Uses `default_server` on port 443, `server_name _`, and serves the same 404 page directly
+(with `return 404` to preserve the status code, since this is the final fallback rather than a redirect).
+
+## Adding a New Site
+
+1. Create `nginx/nginx/sites-available/<name>.conf` with the server block.
+2. Create a symlink: `ln -s ../sites-available/<name>.conf nginx/nginx/sites-enabled/<name>.conf`
+3. Ensure an SSL cert exists on the server for the domain (`certbot --nginx -d <domain>`).
+4. No need to add `error_page 404` — it's handled globally.