diff --git a/.env.development b/.env.development
new file mode 100644
index 000000000..e7e744ecc
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 855f83d1d..8e50d09a9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,6 +30,7 @@ yarn-error.log*
 # env files
 .env*
 !.env.local.example
+!.env.development
 
 # vercel
 .vercel
diff --git a/README.md b/README.md
index 5b0f72fcb..c7ef7026e 100644
--- a/README.md
+++ b/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
diff --git a/db/envConfig.ts b/db/envConfig.ts
index c28050a6a..0ef9757e4 100644
--- a/db/envConfig.ts
+++ b/db/envConfig.ts
@@ -1,4 +1,6 @@
 import { loadEnvConfig } from "@next/env";
  
 const projectDir = process.cwd();
-loadEnvConfig(projectDir);
\ No newline at end of file
+// 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");
diff --git a/docker-compose.development.yml b/docker-compose.development.yml
new file mode 100644
index 000000000..f50f75a86
--- /dev/null
+++ b/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:
diff --git a/package.json b/package.json
index 95c53e081..a2a121695 100644
--- a/package.json
+++ b/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",