arbitrade/docs/DEPLOYMENT.md

# 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 PG connection: `PG_HOST=postgres`, `PG_PORT=5432`, `PG_DATABASE=arbitrade`, `PG_USER=arbitrade`, `PG_PASSWORD=arbitrade`

### Required environment variables

- `APP_ENV=prod`
- `APP_HOST=0.0.0.0`
- `APP_PORT=9090`
- `PG_DATABASE=arbitrade`
- `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 PostgreSQL is reachable at `PG_HOST`.
- 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.