README.md

@@ -24,6 +24,36 @@ Flotilla ──HTTP──▶ Mailship (PUT /subscription/email)
                                         cron fires ──▶ render digest ──▶ SMTP ──▶ email
 ```
 
+## Deployment
+
+The recommended deployment method for mailship is via Docker. Currently the image is not published anywhere. You can build it locally from the repo root with:
+
+```sh
+docker build -t mailship .
+```
+
+The image listens on **port 4738**, expects a writable **`/data`** volume for the SQLite
+database, and runs as a non-root user (`app`) for security hardening.
+
+### Docker Compose (Recommended)
+
+To deploy using Docker Compose copy the environment template, configure your variables, and start:
+
+```sh
+cp .env.template .env
+# Edit .env with your production values (see Configuration section in README)
+docker compose up -d --build
+```
+
+The compose file (`docker-compose.yml`) configures:
+
+- **Automatic restarts** via `restart: unless-stopped`
+- **Named volume** `mailship-data` mounted at `/data` for database persistence
+- **Port 4738** published to the host
+- **Environment variables** passed from your `.env` file with `.env` substitution
+- **Required vars** (`MAILSHIP_SECRET`, `MAILSHIP_URL`, `BASE_URL`, `SMTP_*`) — the
+  compose file uses `${VAR:?required}` to fail early if any are missing
+
 ## Configuration
 
 | Variable | Required | Description |
@@ -147,32 +177,3 @@ result in your browser:
 pnpm run preview:digest
 open digest-preview.html
 ```
-
-## Docker
-
-### Quick start
-
-```sh
-cp .env.template .env
-# Fill in your secrets in .env
-docker compose up -d
-```
-
-### Build and run manually
-
-```sh
-docker build -t mailship .
-docker run -d \
-  -p 4738:4738 \
-  -v mailship-data:/data \
-  --env-file .env \
-  mailship
-```
-
-## Tests
-
-```sh
-pnpm test:unit       # Run unit tests (vitest)
-pnpm test            # Run integration tests (bash E2E)
-pnpm test:server     # Start server for manual testing
-```