Getting Started

Getting Started

This page walks through a local development setup from a fresh clone to a running app with seeded demo data.

Prerequisites

• Docker for the database, and for the one-command Docker path below.
• Node.js 22 (pinned via .nvmrc and the engines field) only when running on the host. The make targets select it automatically via nvm.

With Docker (recommended)

Needs only Docker, no Node on the host. Builds the app, starts PostgreSQL, applies migrations and seeds demo data in one command.

make env            # create .env.local with generated secrets
docker compose up   # app on http://localhost:3000, database seeded

Migrations and the demo seed run on every start, so a fresh machine is ready right after git pull.

Install and run on the host

make setup   # install deps, create .env.local, start DB, migrate, seed
make run     # start the dev server

make doctor diagnoses the setup and can auto-fix common issues, including creating .env.local and switching to Node 22. The underlying npm steps work too:

# 1. Install dependencies (also runs `prisma generate` via postinstall)
npm install

# 2. Configure the environment
cp .env.example .env.local
# then edit AUTH_SECRET (npx auth secret)

# 3. Start the database, apply migrations and seed demo data
npm run db:init

# 4. Run the development server
npm run dev

Open http://localhost:3000 and sign in with the seeded admin account:

admin@datashield.local / ChangeMe123!

Override the seeded account with SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD before seeding if you want different credentials.

Switching machines / after git pull

The Prisma client is regenerated automatically on npm install via the postinstall hook. The database is not migrated automatically: npm run dev only warns if migrations are pending (the predev hook runs prisma migrate status), it never applies them on boot.

After pulling changes that add a migration, apply it explicitly:

npm run db:migrate   # prisma migrate deploy, applies pending migrations

When you edit prisma/schema.prisma yourself, create the migration instead:

npx prisma migrate dev --name <change>

Database commands

Command	Effect
npm run db:init	Start Postgres container, apply all migrations, seed demo data
npm run db:up	Start the Postgres container
npm run db:down	Stop the container
npm run db:migrate	Apply pending migrations (prisma migrate deploy)
npm run seed	Seed only the admin account
npm run seed:dev	Reseed full demo data (breaches, employees, alerts)

Without Docker

Point DATABASE_URL at your own PostgreSQL instance, then run:

npx prisma migrate deploy && npm run seed:dev

The defaults in .env.example match compose.yml, so npm run db:init works out of the box (postgresql://user:password@localhost:5432/datashield).

Next steps

• Set environment variables to unlock optional features: see Configuration.
• Connect an identity provider: see Directory Integrations.
• Add a breach API key and run your first scan: see Breach Scanning.