diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..2e183e8
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,38 @@
+# Version control
+.git
+.gitignore
+
+# Python caches / virtualenvs
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local environment / secrets — never bake into the image
+.env
+.env.local
+openrouter_key.txt
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local runtime data (mounted as volumes in docker-compose, not baked in)
+data/
+backups/
+app.log
+*.db
+*.sqlite
+
+# Docker artifacts
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Docs / design notes not needed at runtime
+*.md
\ No newline at end of file
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..a1849fc
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,33 @@
+# BalanceBoard environment configuration
+# Copy this file to .env and edit values for your deployment:
+#   cp .env.example .env
+
+# --- Flask ---
+# Secret key for session signing. CHANGE THIS in production (use a long random string).
+SECRET_KEY=change-this-secret-key-in-production
+
+# Allow browsing the public feed without an account (true/false).
+ALLOW_ANONYMOUS_ACCESS=true
+
+# App branding (optional).
+APP_NAME=BalanceBoard
+LOGO_PATH=logo.png
+
+# --- Database ---
+# A full SQLAlchemy URI takes precedence over the POSTGRES_* vars below.
+# Example: postgresql+psycopg2://balanceboard:balanceboard123@localhost:5432/balanceboard
+DATABASE_URL=
+
+# Used when DATABASE_URL is empty. docker-compose sets these for the app container;
+# for local dev, point these at your own PostgreSQL instance.
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=balanceboard
+POSTGRES_PASSWORD=balanceboard123
+POSTGRES_DB=balanceboard
+
+# --- Auth0 (optional; leave blank to disable OAuth login) ---
+AUTH0_DOMAIN=
+AUTH0_CLIENT_ID=
+AUTH0_CLIENT_SECRET=
+AUTH0_AUDIENCE=
\ No newline at end of file
diff --git a/README.md b/README.md
index 05f8a4b..fea322a 100644
--- a/README.md
+++ b/README.md
@@ -58,26 +58,41 @@ A Reddit-style content aggregator that collects posts from multiple platforms (R
    ```
 
 7. **Access the application**
-   - Open browser to `http://localhost:5000`
+   - Open browser to `http://localhost:5021`
    - Create an account or browse anonymously
 
 ### Docker Deployment
 
-1. **Build the image**
+The included `docker-compose.yml` runs the app plus a PostgreSQL database, with persistent volumes for the database, collected posts, and backups.
+
+1. **Configure environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env — at minimum set SECRET_KEY to a long random string
+   ```
+
+2. **Build and start the stack**
+   ```bash
+   docker compose up -d --build
+   ```
+
+3. **Access the application**
+   - Open browser to `http://localhost:5021`
+   - Create an account or browse anonymously
+
+Useful commands:
+   ```bash
+   docker compose logs -f app     # follow app logs
+   docker compose down             # stop the stack (keeps data volumes)
+   docker compose down -v          # stop and delete all data volumes
+   ```
+
+To publish the image to the registry instead of building locally:
    ```bash
    docker build -t git.scorpi.us/chelsea/balanceboard:latest .
-   ```
-
-2. **Push to registry**
-   ```bash
    docker push git.scorpi.us/chelsea/balanceboard:latest
    ```
 
-3. **Deploy with docker-compose**
-   ```bash
-   docker-compose up -d
-   ```
-
 See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.
 
 ## Configuration
diff --git a/docker-compose.yml b/docker-compose.yml
index e8285b8..2ef9e5d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,5 +1,3 @@
-version: '3.8'
-
 services:
   postgres:
     image: postgres:15