diff --git a/README.md b/README.md
index e8c7df0..aee167c 100644
--- a/README.md
+++ b/README.md
@@ -2,19 +2,87 @@
 
 FastAPI portfolio website with steampunk design.
 
-## Setup
+## Prerequisites
 
-1. Copy `.env.example` to `.env` and fill in values.
-2. Ensure MariaDB is accessible and create database/user (see spec).
-3. Run: `docker-compose up -d` (from `docker/` directory)
-4. Configure Nginx Proxy Manager to proxy `portfolio.geekbrain.io` to port 8000.
+- Docker & Docker Compose
+- MariaDB server accessible from NAS (10.0.0.16:3306)
+- Nginx Proxy Manager (NPM) installed and configured
+
+## Initial Setup
+
+### 1. Configure Database
+
+On your MariaDB server, run the `docker/init-db.sql` script (or manually):
+
+```sql
+CREATE DATABASE geekbrain_portfolio CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'geekbrain_app'@'%' IDENTIFIED BY 'YOUR_STRONG_PASSWORD';
+GRANT SELECT, INSERT, UPDATE, DELETE ON geekbrain_portfolio.* TO 'geekbrain_app'@'%';
+FLUSH PRIVILEGES;
+```
+
+### 2. Environment Configuration
+
+Copy `.env.example` to `.env` and fill in all required values:
+
+- `DATABASE_URL`: `mysql+aiomysql://geekbrain_app:YOUR_PASSWORD@10.0.0.16:3306/geekbrain_portfolio`
+- `SMTP_USER`: your Gmail address
+- `SMTP_PASSWORD`: Gmail app password (not your regular password)
+- `RECAPTCHA_SITE_KEY` & `RECAPTCHA_SECRET`: from Google reCAPTCHA v2 setup
+- `GITBUCKET_URL`: your GitBucket API endpoint (default provided)
+
+### 3. Deploy with Docker
+
+From the project root:
+
+```bash
+docker-compose -f docker/docker-compose.yml up -d
+```
+
+The app will be available on http://localhost:8000
+
+### 4. Configure Nginx Proxy Manager
+
+Add a new Proxy Host:
+
+- **Domain names:** `portfolio.geekbrain.io` (or your desired domain)
+- **Scheme:** http
+- **Hostname/IP:** IP_of_your_NAS (or `host.docker.internal` if NPM runs on same host)
+- **Port:** 8000
+- **Enable SSL:** Yes (Let's Encrypt)
+- **WebSockets:** No (not needed)
+
+Save and wait for SSL certificate to be issued.
 
 ## Development
 
+Run locally without Docker:
+
 ```bash
 uvicorn app.main:app --reload
 ```
 
-## Spec
+Then visit http://localhost:8000
 
-See `docs/superpowers/specs/2025-03-21-geekbrain-portfolio-design.md` for full specification.
+## Testing
+
+Run all tests:
+
+```bash
+pytest tests/ -v
+```
+
+## Project Structure
+
+See `docs/superpowers/specs/2025-03-21-geekbrain-portfolio-design.md` for full specification and architecture.
+
+## Notes
+
+- GitBucket API is cached for 5 minutes (configurable via `CACHE_TTL`)
+- Contact form includes reCAPTCHA v2 and stores submissions in the database
+- Email notifications are sent via Gmail SMTP
+- All assets are in `app/static/`, templates in `app/templates/`
+
+## License
+
+Proprietary - Geekbrain.io