Hartmut
d4641e27aa
- /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>
157 lines
3.6 KiB
Markdown
157 lines
3.6 KiB
Markdown
# 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.
|