Nexus/docs/installation.md

# Installation Guide

This guide covers everything needed to get Nexus 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/nexus.git
cd nexus
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 nexus-app-1 \
  node scripts/setup-admin.mjs \
  --email admin@example.com \
  --name "Admin" \
  --password changeme123
```

Replace `nexus-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 @nexus/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://nexus.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.