# AnchorHost Backend
**The API and control plane behind AnchorHost.**
[](https://git.anchorhost.eu/anchorhost.eu/anchorhost-backend/actions)
---
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.
```bash
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:
```bash
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:
```text
git.anchorhost.eu/anchorhost.eu/anchorhost-backend:backend
git.anchorhost.eu/anchorhost.eu/anchorhost-backend:main-
```
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:
```bash
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
```text
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](LICENSE).