forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/deployment.md

@@ -1,281 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 3
-skill-tiers: [dev]
----
-
-# ForgeCAD Deployment & Environment
-
-See also the **[Runbook](runbook.md)** for day-to-day operations, testing, troubleshooting, and API reference.
-
-ForgeCAD runs as a Docker Compose stack. There are two compose files:
-
-- **`docker-compose.yml`** — Full self-hosted stack (Caddy + ForgeCAD + PostgreSQL + Redis). Use this for manual VPS deployment.
-- **`docker-compose.coolify.yml`** — Simplified stack for Coolify (ForgeCAD + PostgreSQL only). Coolify handles TLS and reverse proxy.
-
-Production runs on **Hetzner** via **Coolify**, which auto-deploys on push to `mainline`.
-
----
-
-## Architecture
-
-```
-Internet
-  │
-  ├─ Coolify Proxy (Traefik)       ← TLS termination, routing
-  │    │
-  │    └─ forgecad container       ← Fastify app (Node.js)
-  │         │
-  │         ├─ Serves SPA (dist/)  ← Vite-built React frontend
-  │         ├─ API routes (/api/*) ← Auth, projects, files
-  │         └─ connects to ──────► postgresql container
-  │
-  └─ Volume: project-data          ← User project files on disk
-```
-
-In the self-hosted compose file, Caddy replaces Coolify's proxy, and Redis/Valkey is added for rate limiting.
-
----
-
-## Environment Variables
-
-### Server Core
-
-These configure the Fastify application server itself.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `NODE_ENV` | no | `development` | Set to `production` for deployed instances |
-| `FORGE_PORT` | no | `5173` | HTTP port the server listens on |
-| `FORGE_HOST` | no | `127.0.0.1` | Bind address. Use `0.0.0.0` in Docker |
-| `FORGE_DIST_DIR` | no | — | Path to Vite build output (the SPA). In Docker: `/app/dist` |
-
-### Database
-
-ForgeCAD uses PostgreSQL 16 for users, projects, sessions, and audit logs. The database schema is managed by Drizzle ORM with auto-migrations on server startup.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_DB_URL` | **yes** | — | PostgreSQL connection string |
-
-**How the connection is wired in Coolify:**
-
-Coolify auto-generates credentials for linked database services and injects them as `SERVICE_USER_POSTGRES` and `SERVICE_PASSWORD_POSTGRES`. The compose file constructs the full URL from these:
-
-```yaml
-FORGE_DB_URL=postgresql://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@postgresql:5432/${POSTGRES_DB:-forgecad}
-```
-
-The hostname `postgresql` is the Docker Compose service name — Docker's internal DNS resolves it to the postgres container. You never need to set `FORGE_DB_URL` directly in Coolify; it assembles itself from Coolify's auto-generated service credentials.
-
-**In the self-hosted compose file**, the pattern is simpler:
-
-```yaml
-FORGE_DB_URL=postgresql://forgecad:${POSTGRES_PASSWORD}@postgres:5432/forgecad
-```
-
-Here you set `POSTGRES_PASSWORD` in a `.env` file and the same value is shared with the postgres container.
-
-### Authentication
-
-Authentication uses JWT access tokens (short-lived, 15 min) and refresh tokens (7 days, stored in DB with rotation and replay detection).
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_JWT_SECRET` | **yes** | — | HMAC key for signing JWT tokens. Generate with `openssl rand -base64 32` |
-| `FORGE_JWT_ACCESS_EXPIRES` | no | `15m` | Access token lifetime |
-| `FORGE_JWT_REFRESH_EXPIRES` | no | `7d` | Refresh token lifetime |
-
-**The JWT secret is critical.** Without it, login and registration complete the database operations but crash when issuing tokens — the user gets a 500 error. The server starts without it (the value is lazily read), but all auth endpoints fail.
-
-### CORS & Public URL
-
-These tell the server which origins to trust and how to construct user-facing URLs (e.g., in emails).
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_ALLOWED_ORIGINS` | no | `http://localhost:5173` | Comma-separated list of allowed CORS origins |
-| `FORGE_APP_URL` | no | `http://localhost:5173` | Public base URL for the app. Used in email links |
-
-For production, set `FORGE_ALLOWED_ORIGINS=https://forgecad.io` and `FORGE_APP_URL=https://forgecad.io`.
-
-### OAuth Providers
-
-Optional. If not set, the corresponding "Sign in with X" button won't appear on the login page.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `GITHUB_CLIENT_ID` | no | — | GitHub OAuth app client ID |
-| `GITHUB_CLIENT_SECRET` | no | — | GitHub OAuth app client secret |
-| `GOOGLE_CLIENT_ID` | no | — | Google OAuth client ID |
-| `GOOGLE_CLIENT_SECRET` | no | — | Google OAuth client secret |
-
-To set up GitHub OAuth: create an OAuth App at github.com/settings/developers with callback URL `https://forgecad.io/auth/callback/github`.
-
-### Email Delivery
-
-Email is used for account verification and password reset. Without `RESEND_API_KEY`, emails are logged to the container's stdout instead of being sent — useful for development, but users won't receive them.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `RESEND_API_KEY` | no | — | API key from [resend.com](https://resend.com). Enables real email delivery |
-| `FORGE_EMAIL_FROM` | no | `ForgeCAD <noreply@forgecad.io>` | Sender address for outgoing emails |
-
-To enable email: sign up at Resend, verify `forgecad.io` as a sending domain (add their DNS records), get an API key, and set it in Coolify.
-
-### File Storage
-
-User project files (`.forge.js`, meshes) are stored on disk, not in the database.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_STORAGE_ROOT` | no | `/data/projects` | Root directory for project file storage |
-
-In Docker, this is backed by the `project-data` volume, which persists across container rebuilds.
-
----
-
-## Coolify-Specific Variables
-
-These are managed by Coolify itself — you don't set them manually, but the compose file references them:
-
-| Variable | Source | Purpose |
-|----------|--------|---------|
-| `SERVICE_USER_POSTGRES` | Coolify auto-generated | PostgreSQL username |
-| `SERVICE_PASSWORD_POSTGRES` | Coolify auto-generated | PostgreSQL password |
-| `POSTGRES_DB` | Coolify (defaults to `forgecad`) | Database name |
-
----
-
-## What You Actually Need to Set in Coolify
-
-Only these variables need manual configuration in Coolify's environment settings:
-
-1. **`FORGE_JWT_SECRET`** — `openssl rand -base64 32`. Without this, auth is broken.
-2. **`FORGE_ALLOWED_ORIGINS`** — `https://forgecad.io`
-3. **`RESEND_API_KEY`** — from resend.com (optional, but needed for email)
-4. **`GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`** — if you want GitHub login
-5. **`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`** — if you want Google login
-
-Everything else has working defaults or is auto-generated by Coolify.
-
----
-
-## Database Migrations
-
-Migrations run automatically on server startup (`server/db/migrate.ts`). The migration system:
-
-1. Creates a `_migrations` table to track which migrations have been applied
-2. Runs any unapplied migrations in order
-3. Logs each migration to stdout
-
-No manual database setup is needed. The PostgreSQL container starts with an empty database, and the ForgeCAD server creates all tables on first boot.
-
----
-
-## Debugging Production
-
-SSH access: `ssh hetzner` (see `~/.ssh/config`).
-
-```bash
-# Find containers
-docker ps --format "{{.Names}}" | grep forge
-
-# App logs
-docker logs --tail 200 <forgecad-container>
-
-# DB access (get credentials from app env first)
-docker exec <forgecad-container> env | grep POSTGRES
-docker exec <postgres-container> psql -U <USER> -d forgecad
-
-# System health
-df -h && free -h
-```
-
-See the `/hetzner-logs` skill for the full workflow.
-
-### Email not delivered (user didn't receive verification/reset email)
-
-**Symptom:** User registers or requests password reset, no email arrives. Logs show:
-```
-[email] To: user@example.com | Subject: Verify your ForgeCAD email
-```
-
-**Cause:** `RESEND_API_KEY` is empty or missing. The `[email]` log line is the dev fallback — it means the email was *logged* to stdout, not sent.
-
-**Check:**
-```bash
-docker exec <forgecad-container> env | grep RESEND_API_KEY
-# → RESEND_API_KEY=    ← empty = emails not sent
-```
-
-**Fix:** Set `RESEND_API_KEY` in Coolify environment variables → redeploy.
-
-### Connecting a DB client (e.g. Beekeeper Studio) to prod
-
-The PostgreSQL container has no host port mapping — `localhost:5432` is not reachable from outside the server. Instead use an SSH tunnel to the container's Docker network IP.
-
-1. Find the container IP (run once, it's stable across restarts within the same Coolify stack):
-   ```bash
-   ssh hetzner "docker inspect \$(docker ps -qf name=postgresql) | grep '\"IPAddress\"'"
-   # → 10.0.2.3  (or similar)
-   ```
-
-2. In Beekeeper Studio, configure the SSH tunnel:
-   - SSH Host: `65.108.210.215`, User: `kostard`, use your private key
-   - DB Host: `10.0.2.3`, Port: `5432`
-   - Credentials: from Coolify's auto-generated `SERVICE_USER_POSTGRES` / `SERVICE_PASSWORD_POSTGRES`
-   - Database: `forgecad`
-
-   > `AllowTcpForwarding yes` must be set in `/etc/ssh/sshd_config` on the server for the tunnel to work.
-
----
-
-## Local Development
-
-### Quick start (editor only, no auth)
-
-For working on the CAD editor, geometry, sketches, or viewer:
-
-```bash
-npm run dev
-```
-
-Opens the editor with local example files. No login, no database. Fastest workflow for anything that doesn't touch auth or multi-user features. Vite proxies `/api` to port 5174 but the backend is optional — the editor works without it.
-
-### Production build locally (test real server behavior)
-
-For testing WASM serving, bundle sizes, caching headers — the full production Fastify server on your machine:
-
-```bash
-npm run dev:db        # start PostgreSQL (once)
-npm run dev:prod      # tsc + vite build + run Fastify server
-```
-
-Open `http://localhost:5173` — same server code as production, serving the Vite production build. ~25s turnaround.
-
-### Full stack (auth, database, landing page, docs, blog)
-
-For working on the hosted application:
-
-```bash
-# Terminal 1: start PostgreSQL (once)
-npm run dev:db
-
-# Terminal 2: start Fastify API server (port 5174)
-npm run dev:server
-
-# Terminal 3: start Vite dev server (port 5173, proxies /api to 5174)
-npm run dev:studio
-```
-
-Open `http://localhost:5173` — landing page, login, docs, blog, admin, the full thing.
-
-To stop the database: `npm run dev:db:stop`
-
-**Dev credentials** (hardcoded in `dev:server`, never used in production):
-- Database: `forgecad:forgecad@localhost:5432/forgecad`
-- JWT secret: `dev-secret-do-not-use-in-production`
-- Allowed origin: `http://localhost:5173`
-
-Migrations run automatically on server startup.