feat: first-run setup wizard, CLI seed script, and installation docs

- /setup Server Component + SetupClient form + createFirstAdmin Server Action: zero-users guard (TOCTOU-safe), argon2 hash, ADMIN user creation, redirects to /auth/signin after setup - scripts/setup-admin.mjs: CLI alternative for headless/container setups - docs/installation.md: 7-section install guide (clone → configure → run → verify) Co-Authored-By: claude-flow <ruv@ruv.net>
2026-04-02 20:45:15 +02:00
parent 41eb722369
commit d4641e27aa
5 changed files with 452 additions and 0 deletions
@@ -0,0 +1,156 @@
+# Installation Guide
+
+This guide covers everything needed to get CapaKraken running from a fresh clone.
+
+---
+
+## 1. Prerequisites
+
+Before you begin, ensure the following are installed on your machine:
+
+- **Docker Desktop** (macOS / Windows) or **Docker Engine + Compose plugin** (Linux)
+  - Minimum version: Docker Engine 24, Compose 2.20
+- **Git** — to clone the repository
+- **openssl** — to generate a secure secret (usually pre-installed on macOS and Linux)
+
+You do **not** need Node.js or pnpm installed locally; the application runs entirely inside Docker.
+
+---
+
+## 2. Clone & Configure
+
+```bash
+git clone https://github.com/your-org/capakraken.git
+cd capakraken
+cp .env.example .env
+```
+
+Open `.env` and fill in the required values:
+
+| Variable | Description | Example |
+|---|---|---|
+| `NEXTAUTH_SECRET` | Random secret for session signing | see command below |
+| `NEXTAUTH_URL` | Full URL the app is served from | `http://localhost:3100` |
+| `DATABASE_URL` | PostgreSQL connection string | already set in `.env.example` |
+
+Generate a secure `NEXTAUTH_SECRET`:
+
+```bash
+openssl rand -base64 32
+```
+
+Paste the output into `.env`:
+
+```dotenv
+NEXTAUTH_SECRET=<paste output here>
+NEXTAUTH_URL=http://localhost:3100
+```
+
+---
+
+## 3. Start
+
+```bash
+docker compose --profile full up -d
+```
+
+Wait for the app to become healthy (usually 30–60 seconds):
+
+```bash
+curl -s http://localhost:3100/api/health | grep '"status"'
+# Expected: "status": "ok"
+```
+
+You can also watch the logs:
+
+```bash
+docker compose logs -f app
+```
+
+---
+
+## 4. First-Run: Web Wizard (recommended)
+
+Open your browser and navigate to:
+
+```
+http://localhost:3100/setup
+```
+
+Fill in your administrator name, email, and password, then click **Create admin account**.
+
+The wizard automatically redirects to the sign-in page once the account is created. If the setup page redirects you to sign-in immediately, an administrator account already exists.
+
+---
+
+## 5. First-Run: CLI (alternative)
+
+If you prefer the command line, run the setup script inside the running container:
+
+```bash
+docker exec capakraken-app-1 \
+  node scripts/setup-admin.mjs \
+  --email admin@example.com \
+  --name "Admin" \
+  --password changeme123
+```
+
+Replace `capakraken-app-1` with your actual container name if different (check with `docker ps`).
+
+Expected output on success:
+
+```
+Admin user created: admin@example.com
+```
+
+If an administrator already exists:
+
+```
+Admin user already exists. Skipping.
+```
+
+The script exits with code 0 in both cases.
+
+**Running on the host** (advanced): If you have Node.js and pnpm installed locally and `DATABASE_URL` is reachable from your host, you can also run:
+
+```bash
+pnpm --filter @capakraken/db exec prisma generate   # ensure Prisma client is built
+node scripts/setup-admin.mjs --email admin@example.com --name "Admin" --password changeme123
+```
+
+---
+
+## 6. Verify
+
+Confirm the API is healthy:
+
+```bash
+curl -s http://localhost:3100/api/health
+# {"status":"ok","db":"ok"}
+```
+
+Sign in at:
+
+```
+http://localhost:3100/auth/signin
+```
+
+Use the email and password you created in step 4 or 5.
+
+---
+
+## 7. Production Notes
+
+For production deployments:
+
+- Use `docker-compose.prod.yml` together with the base `docker-compose.yml`:
+  ```bash
+  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+  ```
+- Set `NEXTAUTH_URL` to your real HTTPS domain:
+  ```dotenv
+  NEXTAUTH_URL=https://capakraken.yourdomain.com
+  ```
+- See `tooling/deploy/README.md` for reverse-proxy configuration and TLS setup.
+- Never commit `.env` to version control — it contains secrets.
+- Rotate `NEXTAUTH_SECRET` by updating the value and restarting the app; existing sessions will be invalidated.