Getting started

This walks you from a clone to a populated directory running at http://localhost:3001. It takes about ten minutes and needs only Node 20+, pnpm, and a Postgres database.

1. Install dependencies

pnpm install

2. Create a Postgres database

Any Postgres works — a local instance, or a hosted one from Neon or Supabase. Have its connection string ready, for example:

postgresql://user:password@localhost:5432/directory

3. Set environment variables

The database package and the web app each read their own env file:

# the DATABASE_URL used by Prisma migrations and the seed
echo 'DATABASE_URL="postgresql://…"' > packages/database/.env

# the web app's local config
cp apps/web/.env.example apps/web/.env.local

At minimum apps/web/.env.local needs DATABASE_URL and BETTER_AUTH_SECRET (generate one with openssl rand -base64 32). Everything else is optional for local dev — see Environment variables for the full list.

4. Generate the Prisma client and push the schema

pnpm --filter @repo/database build   # prisma generate
npx prisma db push --schema=packages/database/prisma/schema.prisma

db push creates the tables directly from the schema — no migration files to manage for a first setup.

5. Load the starter content

pnpm --filter @repo/database seed

The seed is idempotent (it upserts by slug) and gives you 8 categories, 30 example tools, 3 stacks, 3 role pages, 6 news sources, 3 news stories, and 2 blog posts — enough that no public surface renders empty. From there the pipelines keep news, prices, and editorial content growing on their own.

6. Start the dev server

pnpm --filter web dev

Open http://localhost:3001. The public directory is already populated. Now visit /admin — the first time you open it, a setup wizard creates the owner account and saves your site identity. There is no public sign-up; every account is created from the console.

A bigger starter catalog (optional)

The pnpm seed above gives you 30 tools — enough to see the site work. If you'd rather launch with a full directory, two scripts load a larger hand-curated catalog through the REST API while the dev server is running:

# server must be running; use an API key with the `content` scope
AWP_API_KEY=<your-key> npx tsx scripts/seed-tools.ts      # ~90 real tools
AWP_API_KEY=<your-key> npx tsx scripts/seed-tools-v2.ts   # ~200 more → ~300 total

Both POST to /api/tools, which upserts by slug, so they're safe to re-run and won't duplicate what you already have. The tools land as plain entries; the tools-crawl and tools-enrich pipelines then verify each site and write the full editorial layer. Set AWP_API_KEY to a key you created in /admin/api-keys (or your bootstrap env key).

Your first 30 minutes

Once you're in the admin console:

1. Finish the wizard — owner email and password, site name, brand color.
2. Set your identity at /admin/settings — logo text, tagline, social links, footer copy. This is what visitors see; see Configuration.
3. Create an API key at /admin/api-keys with the publish scope — the pipelines and any agents authenticate with it. Copy it now; the plaintext is shown only once.
4. Add DeepSeek (optional) at /admin/settings → Integrations to turn on AI editorial for news and tool enrichment.
5. Run a pipeline by hand from /admin/pipelines — try the news pipeline to pull real stories, then review them in the dashboard.
6. Browse the queues — /admin/tools, /admin/submissions, /admin/news — to see the daily editorial loop described in Content operations.

When you're ready to go live, head to Deployment.