Manual Install (Node + Postgres)

CompassDocs is a standard Next.js server plus a PostgreSQL database, so you can run it directly with Node.js — handy for local development or a hand-managed server.

Prerequisites

• Node.js 20+
• A PostgreSQL 14+ database

1. Get a PostgreSQL database

Homebrew (macOS, no Docker):

5432/compassdocs

brew install postgresql@16 && brew services start postgresql@16
createdb compassdocs

Docker (just the database):

5432/compassdocs

docker run -d --name compass-pg -p 5432:5432 \
  -e POSTGRES_PASSWORD=compass -e POSTGRES_DB=compassdocs \
  postgres:16

2. Configure and run

git clone https://github.com/mattny20/CompassDocs.git
cd CompassDocs
npm install
cp .env.example .env        # set DATABASE_URL to the value from above
npm run dev
# open http://localhost:3000

On first connection the app creates its own schema and seeds example spaces and documents — no manual migrations. Sign in with admin / admin and change the password when prompted.

Changed your .env?

Environment variables are read at startup. After editing .env, fully restart the dev server for changes (like DATABASE_URL or DATABASE_SSL) to take effect.

3. Production build

npm run build
npm run start

The server listens on port 3000 by default (web UI and the /api/* REST routes share the same port — there is no separate API port). To use a different one: PORT=8080 npm run start. Remember to allow the port through your firewall for remote access — see Ports & firewall.

Connecting to managed Postgres

For hosted databases (Neon, Supabase, RDS, …), TLS is usually required. CompassDocs enables SSL automatically for non-local hosts. If you hit The server does not support SSL connections, your database is local — set DATABASE_SSL=disable (or add ?sslmode=disable to the URL). To force SSL on a host that looks local, set DATABASE_SSL=require. See Environment variables.

Deploying to a platform

Because the app is stateless, it runs anywhere and scales horizontally. Set DATABASE_URL (and optionally ANTHROPIC_API_KEY, COMPASSDOCS_ADMIN_*) as environment variables on your platform of choice:

Target	Notes
Vercel + Neon	Import the repo; add a Neon/Vercel Postgres and set DATABASE_URL. Cheapest to start.
Railway	App + Postgres plugin in one project; Railway injects DATABASE_URL.
Render	Web Service + managed Postgres; wire the internal DATABASE_URL.
Fly.io / a VPS	Use the included Dockerfile (Next.js standalone output).

Use a pooled connection string on serverless platforms and keep DATABASE_POOL_MAX modest.