feat: update documentation structure and add deployment guide

docs/DEPLOYMENT.md

@@ -0,0 +1,142 @@
+# Deployment Guide (Coolify)
+
+This guide provides two supported deployment paths for Arbitrade on Coolify:
+
+- Build directly from Git repository in Coolify.
+- Deploy prebuilt container image: `git.allucanget.biz/allucanget/arbitrade:latest`.
+
+Reference docs:
+
+- Coolify Applications: https://coolify.io/docs/applications
+- Coolify Build Packs: https://coolify.io/docs/applications/build-packs
+- Coolify Dockerfile Build Pack: https://coolify.io/docs/applications/build-packs/dockerfile
+- Coolify Nixpacks Build Pack: https://coolify.io/docs/applications/build-packs/nixpacks
+- Coolify CI/CD (Git providers): https://coolify.io/docs/applications/ci-cd
+- Coolify Gitea integration: https://coolify.io/docs/applications/ci-cd/gitea/integration
+- Coolify environment variables: https://coolify.io/docs/knowledge-base/environment-variables
+- Coolify persistent storage: https://coolify.io/docs/knowledge-base/persistent-storage
+- Coolify health checks: https://coolify.io/docs/knowledge-base/health-checks
+- Coolify Docker registry credentials: https://coolify.io/docs/knowledge-base/docker/registry
+
+## Common Runtime Configuration
+
+Use these values in both deployment modes.
+
+### Port and health
+
+- Container port: `9090`
+- Health check path: `/health`
+- Protocol: HTTP
+
+### Persistent storage
+
+- Add a persistent volume
+- Mount path: `/app/data`
+- Set DB path to: `DUCKDB_PATH=/app/data/arbitrade.duckdb`
+
+### Required environment variables
+
+- `APP_ENV=prod`
+- `APP_HOST=0.0.0.0`
+- `APP_PORT=9090`
+- `DUCKDB_PATH=/app/data/arbitrade.duckdb`
+- `LOG_LEVEL=INFO`
+- `LOG_JSON=true`
+- `KRAKEN_API_KEY=<set-in-coolify-secret>`
+- `KRAKEN_API_SECRET=<set-in-coolify-secret>`
+- `KRAKEN_API_KEY_PERMISSIONS=query,trade`
+- `FERNET_KEY=<set-in-coolify-secret>`
+
+Notes:
+
+- Store secrets in Coolify secret variables, not in Git.
+- Keep Kraken key scope minimal (query + trade, no withdrawal).
+
+## Option A: Build in Coolify from Git Repository
+
+Recommended when you want Coolify to build from source and optionally auto-deploy on commits.
+
+1. Open your Coolify project and select Create New Resource.
+2. Choose deployment source:
+   - Public repo: use `Public repository` and provide HTTPS URL.
+   - Private Gitea repo: use deploy key flow from the Gitea guide.
+
+3. Set repository URL for this project:
+   - `https://git.allucanget.biz/allucanget/arbitrade.git` (public)
+   - or SSH URL if private deploy key is used.
+
+4. Choose build pack:
+   - Prefer `Dockerfile` for this repo, because Docker build behavior is explicitly defined.
+   - Use `Nixpacks` only if you intentionally want auto-detected build logic.
+
+5. Configure branch and base directory:
+   - Branch: your deploy branch (for example `main`)
+   - Base directory: `/`
+
+6. Configure network:
+   - Exposed port: `9090`
+   - Domain: set your Coolify domain/custom domain
+
+7. Configure environment variables and secrets from the Common Runtime Configuration section.
+8. Add persistent storage mount `/app/data`.
+9. Configure health check:
+   - Path: `/health`
+   - Ensure container includes `curl` or `wget` if using UI-defined checks.
+
+10. Click Deploy and verify:
+    - Deployment logs complete successfully.
+    - `GET /health` returns success.
+
+Optional (Git webhook auto-deploy with Gitea):
+
+1. In Coolify resource, open `Webhooks` and copy Manual Git Webhook URL.
+2. Set webhook secret in Coolify.
+3. In Gitea repo settings, add webhook URL + same secret and enable Push events.
+4. Push a commit and confirm Coolify triggers deploy.
+
+## Option B: Deploy Prebuilt Image from Container Registry
+
+Recommended when CI publishes the image and Coolify only runs it.
+
+Image:
+
+- `git.allucanget.biz/allucanget/arbitrade:latest`
+
+1. Ensure CI publishes the image before first deployment.
+2. In Coolify, select Create New Resource.
+3. Choose Application deployment based on Docker Image.
+4. Set image reference:
+   - Registry: `git.allucanget.biz`
+   - Image: `git.allucanget.biz/allucanget/arbitrade:latest`
+
+5. Configure registry credentials in Coolify if your registry requires auth.
+6. Leave build/install/start commands empty unless you need overrides.
+7. Set network and health:
+   - Exposed port: `9090`
+   - Health check path: `/health`
+
+8. Add environment variables and secrets from the Common Runtime Configuration section.
+9. Add persistent storage mount `/app/data`.
+10. Deploy and verify:
+    - Logs show container start success.
+    - `GET /health` returns success.
+
+Update flow for new releases:
+
+- Push code and let CI publish a new `latest` image.
+- Trigger redeploy in Coolify for this resource.
+
+## Quick Troubleshooting
+
+- `No available server` from proxy:
+- Check health check path/port and app bind (`APP_HOST=0.0.0.0`, `APP_PORT=9090`).
+- Verify health check is passing in Coolify.
+- `TemplateNotFound: dashboard.html` at runtime:
+- Ensure the deployed image/wheel includes package templates under `arbitrade/web/templates/*`.
+- If you build from source, do not remove packaged template files under `src/arbitrade/web/templates`.
+- DB resets after deploy:
+- Confirm persistent mount exists at `/app/data` and `DUCKDB_PATH` points there.
+- Registry pull fails:
+- Re-check Docker registry credentials in Coolify.
+- App starts but unavailable externally:
+- Confirm exposed port is `9090` and domain is attached to this resource.