tellscoin/doc/build-and-deploy.md

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:

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.