Getting started

This page is for a developer starting from a fresh checkout. You will run two independent Next.js applications that live in separate repositories: the main ROUNDTABLE application (COG-GTM/NIWCPAC_N66001-26-S-C129) on port 3000, and this documentation site (COG-GTM-NIWCPAC_N66001-26-S-C129_DOCS_REPO) on port 3001. The main app needs PostgreSQL; the docs site only needs its own Node dependencies, with no database and no sign-in.

Prerequisites

Install these before troubleshooting the application:

The main app is Next.js 14. The docs site is a separate repository and uses Next.js 15 with a compatible Fumadocs 15 line, so the two upgrade independently.

1. Start PostgreSQL

The simplest development database is a disposable PostgreSQL container:

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

The root .env.example expects a connection string similar to:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/roundtable

If a container named roundtable-pg already exists, use docker start roundtable-pg instead of creating another one.

2. Configure and install the main app

From the root of the application repository:

cp .env.example .env
pnpm install
pnpm db:setup

db:setup runs Prisma client generation, migration deployment, and the idempotent seed script. It creates commands, ten portfolio nodes, government users, eight industry organizations, calls, an announcement, and sample engagement records.

3. Start the main application

pnpm dev

Open http://localhost:3000. Use the seeded accounts in Seeded accounts to demonstrate both sides.

4. Start the documentation site

Clone the docs repository next to the application checkout, then, from the docs repository root:

pnpm install
pnpm dev

Open http://localhost:3001/docs. Run every docs command from that checkout: it has its own package.json and lockfile and shares nothing with the application repository.

Verify your setup

What a successful local setup contains

Next steps

Read Environment variables, then Seeded accounts. If you need to understand why the app calls Prisma from route handlers, continue to Architecture. If you only need the documentation site, the main app and database are not required to render this content.

Common port conflicts

The main app and the docs site intentionally use different ports. Find the process occupying a port before changing configuration:

lsof -iTCP:3000 -sTCP:LISTEN
lsof -iTCP:3001 -sTCP:LISTEN

If another process owns 3000, stop that development process or run the main app with its documented alternative. Do not silently move the docs server: links and verification instructions assume 3001. If 3001 is occupied by an earlier docs process, reuse it when it is the same checkout; otherwise stop the stale process and start the docs site again.

PostgreSQL and Prisma sequence

The order matters:

1. PostgreSQL must accept connections.
2. .env must point at that database.
3. pnpm install must install the Prisma CLI and client.
4. pnpm prisma generate creates the typed client.
5. pnpm prisma migrate deploy applies committed migrations.
6. pnpm prisma db seed inserts demo data.

prisma generate does not create tables, and migrations do not create seeded users. Treat those as separate failure domains when reading terminal output.

Migrations also run CREATE EXTENSION IF NOT EXISTS pg_trgm and build the trigram indexes the fuzzy search stage needs, so the database role running them must be allowed to create extensions. Unless the extension is already installed — CREATE EXTENSION IF NOT EXISTS is then a no-op needing no privilege — a role without that right fails the migration. Confirm the extension landed with select extname from pg_extension where extname = 'pg_trgm'; — if the pg_trgm migration alone was skipped or the extension was dropped later, full-text search still runs, but the fuzzy stage logs one error and falls back to substring matching for the life of the process rather than failing the request.

Development-only warning

The seeded password, .example.com contacts, and navy.mil demo addresses are fixtures. They make a walkthrough reproducible, but they are not identities to deploy. Replace all secrets and review seeded data before sharing an environment beyond the local team.

First successful run

The shortest reliable path is:

1. Start PostgreSQL and confirm the container is healthy.
2. Copy the root environment example and set a local database URL.
3. Set a long random NEXTAUTH_SECRET and a local NEXTAUTH_URL.
4. Configure MinIO or another S3-compatible service before testing uploads.
5. Run pnpm db:setup from the application repository root. This applies migrations, generates Prisma Client, and runs the idempotent seed path described in the environment page.
6. Start the main application on port 3000.
7. Sign in with one seeded government account and one seeded industry account.
8. Create a harmless read-only test flow before mutating shared seed records.
9. In a second terminal, start the docs site from its own checkout on port 3001.
10. Open /docs and use the API pages alongside the running application.

What setup verification proves

Passing one row does not prove the next row. For example, a successful login does not prove S3 configuration, and a docs build does not prove the main application's database environment.