Skip to content

Setup Guide (Internal Use)

Jump to bottom
Mahid Ahmad edited this page Aug 15, 2025 · 3 revisions

🛠️ Project Setup & Run Guide (Internal Use)

This guide explains how to set up and run the LangRoute project in your local development environment, using Docker for PostgreSQL and the provided environment files.

1️⃣ Prerequisites — Install These First

Docker Desktop (with Docker Compose)

Docker will be used to run the local PostgreSQL database without manual installation. Follow these steps:

  1. Download Docker Desktop 🔗 https://www.docker.com/products/docker-desktop/

  2. Install using default settings, but ensure:

    • WSL 2 integration is enabled (required for Windows)
    • You select your default WSL distro during install

  3. After installation:

    • Open Docker Desktop once to confirm it runs without errors
    • Ensure Docker Compose is included (it is bundled in Docker Desktop by default)

PostgreSQL via Docker

You do not need to install PostgreSQL manually — it will run in a container. The repository already includes:

  • docker/docker-compose.db.yml — configuration for the PostgreSQL container
  • npm run db boot — command to start PostgreSQL in Docker

Node.js

2️⃣ Environment Setup

Recommended: start from a fresh clone due to recent directory/structure changes.

  1. Place the shared .env from the Discord channel in ./env/ and rename to .env.local.

    • Any existing .env in the project root will be overwritten when you run environment preparation commands.
    • The .env in the root is auto-generated — don’t edit it directly

  2. Generate a root .env (local by default): sh npm run env

  3. Prisma setup (run after the database is running — see the next section: Running the Database):

    • Prisma requires a .env file in the project root. Ensure it has been generated.

    • Once your .env file is ready and the database is running, run:

        npx prisma generate
  npx prisma migrate dev

Note: Running npm run env or npm run dev will always overwrite the root .env with a generated file. By default, it merges .env.base (if present) and .env.local. To run with another env, see Notes.

3️⃣ Running the Database

The project includes a db-cli for managing the local PostgreSQL container via Docker.

  • Boot database (recommended daily start):

    npm run db boot
    • Starts Docker Desktop (if not already running)
    • Boots the PostgreSQL container in the background

  • Shutdown database:

    npm run db shutdown
    • Stops the PostgreSQL container
    • Attempts to close Docker Desktop to avoid WSL shutdown issues

Tip: Always use these commands to start/stop the DB — they handle Docker Desktop for you and prevent the "WSL not closed properly" error.

4️⃣ Running the Application

  • Quickest / Recommended

     npm run dev:boot
    • Prepares .env for local development
    • Boots the database container
    • Starts the Next.js app in dev mode

  • Alternative

     npm run dev
    • Starts the app in dev mode only (local by default)
    • Requires the database to already be running

5️⃣ Common Commands

Command Description
npm run dev:boot Type check + lint + env prep (local) + DB boot + start dev
npm run dev Starts app in dev mode with local env (regenerates .env)
npm run env Manually (re)generate the root .env (local target)
npm run db boot Boots Docker Desktop + PostgreSQL container
npm run db shutdown Stops DB; attempts to close Docker Desktop
npm run db reset Recreate containers without deleting volumes (keeps data)
npm run db nuke Wipes all DB volumes + network, starts fresh (⚠ destructive)
npm run check Runs lint + type checks
npm run build Builds the app for production

6️⃣ Troubleshooting

  • Docker not starting → Ensure Docker Desktop is installed and can start manually before using db-cli commands

  • Port 5432 in use → Stop any local PostgreSQL or service using 5432.

  • Outdated containers/volumes → Reset with:

    npm run db reset

  • WSL not closed properly error → Always use npm run db shutdown before turning off your PC

  • Corrupted volume or migration drift → Full wipe (⚠ destructive):

    npm run db nuke

    ⚠ This deletes all data, volumes, and network, then starts with a clean state!

  • Prisma migrate fails / connection refused → Make sure DB is running:

    npm run db boot

    Then:

    npx prisma generate
npx prisma migrate dev

  • Changes to .env.local not applied → Rerun:

    npm run dev

  • No .env keys → Ensure env/.env.base or env/.env.local exist.

Ping @mahid797 if you run into setup issues.

7️⃣ Notes

  • Avoid editing .env directly — edit .env.local (and optionally .env.base) & use npm run dev or npm run env instead
  • All env files in /env are gitignored except .env.example
  • Only local environment is relevant for development — you don’t need to worry about other runtime envs for day-to-day work

Non-local envs:

Note: This is primarily for testing other environments; local development should always use .env.local.

By default npm run dev builds from .env.local. To target another env, use this command:

npm run dev -- <target>
  • Starts dev mode using .env.<target> (overlays .env.base if present)
  • Affects this run only; the next npm run dev is local again

Example: npm run dev -- prod uses keys from .env.prod (& .env.base if it exists) and runs the app.

Clone this wiki locally