Local dev database via Docker Compose (npm run db:up / db:down)

.env.development

@@ -0,0 +1,12 @@
+# Safe local development defaults, loaded by Next.js (and drizzle-kit via
+# @next/env) in development. Committed on purpose — no secrets here.
+# Override anything in .env.local, which takes precedence and is untracked.
+
+# Local database. docker-compose.development.yml injects this file into
+# the Postgres container (env_file) and reads DB_PORT for the host port
+# mapping; keep DATABASE_URL in sync.
+DB_PORT=5432
+POSTGRES_USER=pagescms
+POSTGRES_PASSWORD=pagescms
+POSTGRES_DB=pagescms
+DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms

.gitignore

@@ -30,6 +30,7 @@ yarn-error.log*
 # env files
 .env*
 !.env.local.example
+!.env.development
 
 # vercel
 .vercel

README.md

@@ -47,12 +47,14 @@ git clone https://github.com/pagescms/pagescms.git
 cd pagescms
 ```
 
-2. Start PostgreSQL locally:
+2. Start PostgreSQL locally (Docker Compose, data persisted in a volume):
 
 ```bash
-docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16
+npm run db:up
 ```
 
+Stop it later with `npm run db:down`.
+
 3. Install dependencies:
 
 ```bash
@@ -62,11 +64,12 @@ npm install
 4. Create `.env.local` with at least:
 
 ```bash
-DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms
 BETTER_AUTH_SECRET=your-random-secret
 CRYPTO_KEY=your-random-secret
 ```
 
+`DATABASE_URL` defaults to the local Docker database (see `.env.development`); set it in `.env.local` only if your database differs.
+
 Optional but useful:
 
 ```bash

db/envConfig.ts

@@ -1,4 +1,6 @@
 import { loadEnvConfig } from "@next/env";
 
 const projectDir = process.cwd();
-loadEnvConfig(projectDir);
+// Without the dev flag, loadEnvConfig runs in production mode and skips
+// .env.development (where the local DATABASE_URL default lives).
+loadEnvConfig(projectDir, process.env.NODE_ENV !== "production");

docker-compose.development.yml

@@ -0,0 +1,24 @@
+# Local development database.
+# Usage: npm run db:up / npm run db:down
+# Container credentials come from .env.development (env_file below);
+# the same file is passed via --env-file in the npm scripts so DB_PORT
+# is available for the port mapping (env_file does not feed ${...}
+# interpolation). Override the host port with `DB_PORT=5433 npm run db:up`.
+name: pagescms-dev
+
+services:
+  db:
+    image: postgres:16
+    env_file: .env.development
+    ports:
+      - "${DB_PORT:?set in .env.development — run via npm run db:up}:5432"
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+
+volumes:
+  db-data:

package.json

@@ -14,8 +14,11 @@
     "postbuild": "npm run db:migrate",
     "start": "next start",
     "lint": "eslint .",
+    "db:up": "docker compose --env-file .env.development -f docker-compose.development.yml up -d --wait",
+    "db:down": "docker compose --env-file .env.development -f docker-compose.development.yml down",
     "db:generate": "npx drizzle-kit generate",
     "db:migrate": "npx drizzle-kit migrate",
+    "db:studio": "npx drizzle-kit studio",
     "auth:generate": "npx @better-auth/cli generate --config ./lib/auth.ts --output ./auth-schema.ts --yes",
     "db:clear-cache": "npx tsx db/scripts/clear-cache.ts",
     "db:collaborators:export": "npx tsx db/scripts/collaborators/export.ts",