anchorhost-backend/README.md

AnchorHost Backend

The API and control plane behind AnchorHost.

---

AnchorHost Backend serves the platform's HTTP API and WebSocket connection for account, billing, domain, server, and support operations. It integrates with PostgreSQL, Kubernetes, Stripe, OAuth providers, SMTP, and deSEC.

Start locally

Requires Python 3.12 and access to a PostgreSQL database for a production-like run. SQLite remains available for isolated local development.

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Set DATABASE_URL and a persistent JWT_SECRET in .env, then start the API and WebSocket service together:

python app.py

The HTTP API listens on http://localhost:8080 and the WebSocket service listens on port 8081 by default. The health endpoint is GET /health.

Build and publish

Pushes to main build the container and publish these tags to the Gitea Container Registry:

git.anchorhost.eu/anchorhost.eu/anchorhost-backend:backend
git.anchorhost.eu/anchorhost.eu/anchorhost-backend:main-<commit>

The workflow needs a repository secret named REGISTRY_TOKEN with package read and write access. Run it manually from Actions → Build and publish Docker image when needed.

Build the image locally with:

docker build -t anchorhost-backend:local .

Configuration

Variable	Purpose
DATABASE_URL	PostgreSQL URL in production; SQLite URL or file path for local development.
JWT_SECRET	Persistent random secret of at least 32 characters.
PORT, WS_PORT	HTTP and WebSocket listen ports; defaults are 8080 and 8081.
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET	Stripe checkout and webhook integration.
GOOGLE_*, APPLE_*	OAuth client and callback configuration.
DESEC_API_TOKEN, BASE_DOMAIN	DNS and domain management.
SMTP_*, BASE_URL, FRONTEND_URL	Transactional email settings and links.
KUBECONFIG	Optional local kubeconfig path; in-cluster credentials are used in Kubernetes.

Copy .env.example as a starting point. Keep production values in deployment secrets; do not commit .env or credentials.

Project structure

app.py                  Application entry point
application.py          Flask application factory
routes/                  HTTP endpoints grouped by feature
database_service.py      Schema initialization and database operations
*_service.py             Feature services and integrations
server_*.py              Server lifecycle, access, capacity, and billing
websocket_service.py     WebSocket server and client sessions
main.py                  Background workers and process startup

License

MIT © 2026 Wiktor A. Falkowski. See LICENSE.