Initial commit

doc/build-and-deploy.md

@@ -0,0 +1,85 @@
+# Build and Deployment
+
+## Runtime Targets
+
+- Local Python process using Uvicorn.
+- Docker container via `Dockerfile`.
+- Docker Compose service via `docker-compose.yml`.
+
+Related references:
+
+- Configuration fields: `doc/environment.md`
+- Architecture: `doc/architecture.md`
+
+## Local Run
+
+Typical local launch command:
+
+```bash
+uvicorn app.main:app --reload --port 8080
+```
+
+Service endpoint:
+
+- `http://localhost:8080`
+
+Notes:
+
+- The app reads environment variables at startup.
+- Database parent directory is created automatically.
+
+## Docker Image Build Rules
+
+Build file: `Dockerfile`
+
+Current build behavior:
+
+1. Base image: `python:3.12-slim`
+2. Install Python dependencies from `requirements.txt`
+3. Copy `app/` and `data/` into image
+4. Expose container port `8080`
+5. Start with Uvicorn on `0.0.0.0:8080`
+
+## Docker Compose Rules
+
+Compose file: `docker-compose.yml`
+
+Dashboard service settings:
+
+- Publishes `8080:8080`
+- Loads environment from `.env`
+- Sets:
+  - `DATA_DIR=/app/data`
+  - `DB_PATH=/app/data/dashboard.db`
+- Mounts volume:
+  - `./data:/app/data`
+- Adds host gateway alias:
+  - `host.docker.internal:host-gateway`
+- Restart policy:
+  - `unless-stopped`
+
+## Persistence Rules
+
+- Persist `./data` on the host to retain:
+  - node settings
+  - chart metric history
+- If `data/dashboard.db` is not persisted, settings and history reset when the container is recreated.
+
+## Network Rules
+
+If the Bitcoin node runs on the Docker host:
+
+- Prefer RPC URL `http://host.docker.internal:8332`.
+
+If using remote node hosts:
+
+- Set RPC URL directly to the node endpoint.
+- Ensure SSH host/credentials are valid for start/restart actions.
+
+## Deployment Checklist
+
+1. Set strong `APP_PASSWORD` or provide `APP_PASSWORD_HASH`.
+2. Set a long random `SESSION_SECRET`.
+3. Set `SESSION_COOKIE_SECURE=true` behind HTTPS.
+4. Persist the database volume.
+5. Restrict dashboard network exposure to trusted operators.