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 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.