feat: Add Docker support and CI/CD workflows documentation; include setup instructions for Docker-based deployment

README.md

@@ -33,3 +33,30 @@ This repository contains detailed developer and architecture documentation in th
 Key architecture documents: see [architecture](docs/architecture/README.md) for the arc42-based architecture documentation.
 
 For contributors: the `routes/`, `models/` and `services/` folders contain the primary application code. Tests and E2E specs are in `tests/`.
+
+## Run with Docker
+
+The repository ships with a multi-stage `Dockerfile` that produces a slim runtime image.
+
+```powershell
+# Build the image locally
+docker build -t calminer:latest .
+
+# Run the container (exposes FastAPI on http://localhost:8000)
+docker run --rm -p 8000:8000 calminer:latest
+
+# Provide environment variables (e.g., database URL)
+docker run --rm -p 8000:8000 -e DATABASE_URL="postgresql://user:pass@host/db" calminer:latest
+```
+
+Use `docker compose` or an orchestrator of your choice to co-locate PostgreSQL/Redis alongside the app when needed. The image expects migrations to be applied before startup.
+
+## CI/CD expectations
+
+CalMiner uses Gitea Actions workflows stored in `.gitea/workflows/`:
+
+- `test.yml` runs style/unit/e2e suites on every push with cached Python dependencies.
+- `build-and-push.yml` builds the Docker image, reuses cached layers, and pushes to the configured registry.
+- `deploy.yml` pulls the pushed image on the target host and restarts the container.
+
+Pipelines assume the following secrets are provisioned in the Gitea instance: `GITEA_USERNAME`, `GITEA_PASSWORD`, `GITEA_REGISTRY`, `SSH_HOST`, `SSH_USERNAME`, and `SSH_PRIVATE_KEY`.