Skip to content

local-development.md

Latest commit

 

History

History
66 lines (46 loc) · 2.86 KB

local-development.md

File metadata and controls

66 lines (46 loc) · 2.86 KB

Local Development with Dockerized Postgres

Follow these steps when you want to run the Next.js app with npm on your host machine while PostgreSQL runs inside Docker. The flow keeps external services identical to production but lets you iterate with hot reload locally.

1. Prerequisites

  • Docker Desktop (or any Docker runtime) running.
  • Node.js 20+ and npm installed on your host.
  • An .env.local file in app/ that matches your deployment secrets.

2. Start the database container

cd app
LOCAL_DB_PORT=5432 docker compose up -d postgres
  • Change LOCAL_DB_PORT if port 5432 is already occupied on your host.
  • Data persists inside the named postgres_data volume. Use docker compose down -v if you need a clean slate.

3. Create your environment file

  1. Copy the template: cp app/.env.local.example app/.env.local.
  2. Update secrets:
    • DATABASE_URL should target the mapped host port, e.g. postgresql://dibgifts:password@localhost:5432/dibgifts_db.
    • NEXTAUTH_SECRET must be a 32+ character random string.
    • Replace the SMTP block with valid credentials (or point it to a dev SMTP relay like Mailtrap).
    • Provide a real NEXT_PUBLIC_UNSPLASH_ACCESS_KEY if you need banner search.

If you run a remote/deployed Postgres instance instead of the local container, just swap localhost:5432 with that hostname/port.

4. Install dependencies & prepare the DB

cd app
npm install
npm run migration:up  # applies MikroORM migrations to the database
npm run db:init       # optional helper that seeds auth tables
  • Run npm run migration:up every time the entity schema changes.
  • If you connect to an already-seeded production database, skip the init scripts to avoid clobbering data.

5. Launch the Next.js dev server

cd app
npm run dev
  • The app listens on http://localhost:3000 by default. Override with PORT inside .env.local if necessary.
  • The API layer (tRPC + NextAuth) now talks to the Dockerized Postgres instance through the shared DATABASE_URL.

6. Stopping services

  • Stop the app with Ctrl+C in the dev terminal.
  • Stop Postgres when you are done: cd app && docker compose down.
  • Use docker compose logs -f postgres if you need to inspect database output.

7. Troubleshooting tips

  • Connection refused: Ensure the container is healthy (docker ps + check the STATUS). Confirm the host port matches DATABASE_URL.
  • SSL or timezone warnings: Add ?sslmode=disable or other parameters directly to DATABASE_URL if your remote DB requires them.
  • Migrations not applying: Verify the .env.local file exists before running MikroORM CLI commands; they read from the same environment variables.

With this setup you can iterate locally using npm while keeping the database layer isolated inside Docker (or any external Postgres instance) without running the whole stack in containers.