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

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:

openssl rand -base64 32

Paste the output into .env:

NEXTAUTH_SECRET=<paste output here>
NEXTAUTH_URL=http://localhost:3100

---

3. Start

docker compose --profile full up -d

Wait for the app to become healthy (usually 30–60 seconds):

curl -s http://localhost:3100/api/health | grep '"status"'
# Expected: "status": "ok"

You can also watch the logs:

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:

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:

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:

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:

  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
  

• Set NEXTAUTH_URL to your real HTTPS domain:

  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.