documentation and env changes

docs/deployment.md

@@ -0,0 +1,70 @@
+# Deployment
+
+This application ships with an immutable, single‑container image that includes PHP‑FPM, Nginx, and your code. By default it uses SQLite and auto‑runs migrations on start.
+
+## Build (locally)
+```bash
+docker build \
+  --target=prod \
+  -t tonehaus-app:latest \
+  -f docker/php/Dockerfile \
+  .
+```
+
+## Run
+```bash
+docker run -d \
+  --name tonehaus \
+  -p 8080:8080 \
+  -e APP_ENV=prod \
+  -e APP_SECRET=change_me \
+  -e SPOTIFY_CLIENT_ID=your_client_id \
+  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
+  tonehaus-app:latest
+```
+
+### Notes
+- Health endpoint: `GET /healthz` (e.g., `curl http://localhost:8080/healthz`)
+- Migrations: `RUN_MIGRATIONS_ON_START=1` by default (safe to re‑run)
+- Cache warmup is executed on boot; `APP_SECRET` is required
+
+## Persistence options
+### SQLite (default)
+- Data file at `var/data/database.sqlite`
+- Use a volume for durability:
+```bash
+docker run -d \
+  -v tonehaus_sqlite:/var/www/html/var/data \
+  ...
+```
+
+### Postgres
+Provide `DATABASE_DRIVER=postgres` and a `DATABASE_URL`, e.g.:
+```
+postgresql://user:password@host:5432/dbname?serverVersion=16&charset=utf8
+```
+You can disable automatic migrations with `RUN_MIGRATIONS_ON_START=0` and run them manually:
+```bash
+docker exec tonehaus php bin/console doctrine:migrations:migrate --no-interaction
+```
+
+## Environment variables
+- `APP_ENV` (`prod` recommended in production)
+- `APP_SECRET` (required; random string)
+- `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
+- `APP_ALLOW_REGISTRATION` (env override for public registration)
+- `DATABASE_DRIVER` (`sqlite` default, or `postgres`)
+- `DATABASE_URL` (when using Postgres)
+- `DATABASE_SQLITE_PATH` (optional)
+- `RUN_MIGRATIONS_ON_START` (default `1`)
+
+## Reverse proxy / TLS
+- Place behind your ingress/proxy (e.g., Nginx, Traefik, or a cloud load balancer)
+- Terminate TLS at the proxy and forward to the container’s port 8080
+- Ensure proxy sends `X-Forwarded-*` headers
+
+## Zero‑downtime tips
+- Build then run a new container alongside the old one, switch traffic at the proxy
+- Keep SQLite on a named volume, or use Postgres for shared state across replicas
+
+