diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..6ee3258a9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,77 @@
+# Navidrome — Development Notes
+
+## Running with Docker Compose
+
+The dev stack splits the backend and frontend into separate services with hot-reload.
+
+```bash
+# First run (builds Go image, downloads all deps — takes a few minutes)
+docker compose -f docker-compose.dev.yml up --build
+
+# Subsequent runs
+docker compose -f docker-compose.dev.yml up
+```
+
+| Service  | Port | Description                          |
+|----------|------|--------------------------------------|
+| backend  | 4633 | Go server with reflex hot-reload     |
+| frontend | 4533 | Vite dev server — open this in browser |
+
+The frontend proxies `/auth`, `/api`, `/rest`, and `/backgrounds` requests to the backend automatically.
+
+```bash
+docker compose -f docker-compose.dev.yml logs -f backend   # backend logs
+docker compose -f docker-compose.dev.yml logs -f frontend  # frontend logs
+docker compose -f docker-compose.dev.yml down              # stop everything
+```
+
+## Running without Docker
+
+```bash
+make setup   # one-time: installs Go and Node dependencies
+make dev     # starts both services with hot-reload
+```
+
+## Database
+
+Navidrome uses **SQLite only** — there is no Postgres or MySQL support. The database file is persisted in `./data/navidrome.db` (bind-mounted into the container at `/data`).
+
+### Inspecting the database
+
+From your host (requires `sqlite3`):
+
+```bash
+sqlite3 ./data/navidrome.db
+```
+
+From inside the running backend container:
+
+```bash
+docker compose -f docker-compose.dev.yml exec backend sqlite3 /data/navidrome.db
+```
+
+Useful SQLite commands:
+
+```sql
+.tables               -- list all tables
+.schema media_file    -- show a table's schema
+SELECT * FROM user;   -- query data
+.quit                 -- exit
+```
+
+## Configuration
+
+App config lives in `navidrome.toml`. Environment variables (prefixed `ND_`) override it. The Docker Compose file sets:
+
+| Variable                    | Value             |
+|-----------------------------|-------------------|
+| `ND_PORT`                   | `4633`            |
+| `ND_MUSICFOLDER`            | `/music`          |
+| `ND_DATAFOLDER`             | `/data`           |
+| `ND_LOGLEVEL`               | `info`            |
+| `ND_ENABLEINSIGHTSCOLLECTOR`| `false`           |
+| `ND_DEVAUTOCREATEADMINPASSWORD` | `admin`      |
+
+The default dev credentials are **`admin` / `admin`** (set via `ND_DEVAUTOCREATEADMINPASSWORD`).
+
+The music folder maps to `./music` (project root) inside the container. Drop audio files there and the scanner will pick them up.
diff --git a/Dockerfile.dev b/Dockerfile.dev
new file mode 100644
index 000000000..2aab902b5
--- /dev/null
+++ b/Dockerfile.dev
@@ -0,0 +1,7 @@
+FROM golang:1.26
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    sqlite3 libsqlite3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
diff --git a/README.md b/README.md
index 0ae5bdfaf..09dae5368 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,37 @@ please file a [GitHub issue](https://github.com/navidrome/navidrome/issues) or j
 [themes](https://www.navidrome.org/docs/developers/creating-themes)), please join the chat in our 
 [Discord server](https://discord.gg/xh7j7yF). 
 
+## Local Development
+
+The easiest way to run the full stack locally is with Docker Compose. It starts the Go backend and Vite frontend as separate services with hot-reload enabled.
+
+**Prerequisites:** Docker and Docker Compose.
+
+```bash
+# First run — builds the Go image and downloads all dependencies
+docker compose -f docker-compose.dev.yml up --build
+
+# Subsequent runs
+docker compose -f docker-compose.dev.yml up
+```
+
+Open **http://localhost:4533**. Default credentials are **`admin` / `admin`**. Drop your audio files into the `music/` folder at the project root — the scanner picks them up automatically.
+
+```bash
+# Run in the background
+docker compose -f docker-compose.dev.yml up -d
+
+# Follow logs
+docker compose -f docker-compose.dev.yml logs -f
+
+# Stop
+docker compose -f docker-compose.dev.yml down
+```
+
+Both services support hot-reload: editing `.go` files restarts the backend via `reflex`, and editing frontend source triggers Vite's HMR.
+
+> See [CLAUDE.md](CLAUDE.md) for additional development notes, including how to inspect the database.
+
 ## Installation
 
 See instructions on the [project's website](https://www.navidrome.org/docs/installation/)
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 000000000..0d9713896
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,41 @@
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    ports:
+      - "4633:4633"
+    volumes:
+      - .:/workspace
+      - ./music:/music:ro
+      - ./data:/data
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
+    environment:
+      ND_PORT: "4633"
+      ND_MUSICFOLDER: /music
+      ND_DATAFOLDER: /data
+      ND_LOGLEVEL: info
+      ND_ENABLEINSIGHTSCOLLECTOR: "false"
+      ND_DEVAUTOCREATEADMINPASSWORD: "admin"
+    command: sh -c "mkdir -p ui/build/3rdparty && touch ui/build/3rdparty/placeholder && go mod download && go tool reflex -d none -c reflex.conf"
+
+  frontend:
+    image: node:24
+    working_dir: /app
+    ports:
+      - "4533:4533"
+    volumes:
+      - ./ui:/app
+      - node-modules:/app/node_modules
+    environment:
+      PORT: "4533"
+      BACKEND_HOST: backend
+    command: sh -c "npm ci && npm start"
+    depends_on:
+      - backend
+
+volumes:
+  go-mod-cache:
+  go-build-cache:
+  node-modules: