dns-proxy-box.git · README.md

revision a86b2875cd436c71a6c7103db26a48795e7f1789 · complete file

# FountainAI Provisioning API

This repository packages the automation layer used to create and manage the FountainAI cluster. The API is defined in [openapi/provisioning-api.yaml](openapi/provisioning-api.yaml) and implemented with FastAPI under `fastapi_app`. It wraps the [Hetzner Cloud OpenAPI](https://docs.hetzner.cloud/cloud.spec.json) to expose a simplified interface for provisioning three small virtual machines:
The cluster is capped at three nodes; bootstrapping calls refuse additional boxes once all are provisioned.

1. a hardened Caddy proxy for all `*.fountain.coach` traffic
2. a Typesense search node
3. a Swift services box running the application containers
4. the live documentation site at <https://fountain.coach> served via Caddy
from a local clone of
[Fountain-Coach/fountain-manifesto](https://github.com/Fountain-Coach/fountain-manifesto)

## Historical Context

Originally these machines were built entirely by hand and DNS was managed through Route&nbsp;53. The process evolved into the Python script `scripts/setup_proxy_box.py`, which automated the repetitive steps. When Hetzner published a full OpenAPI specification we replaced the script with a formal REST contract. DNS migration to Hetzner is now complete—Hetzner manages the `fountain.coach` zone. Version **1.6.0** introduced cluster limits and Typesense diagnostics. The original steps are preserved in [dns-migration.md](dns-migration.md) for reference.

## Usage

Run the API via Docker Compose and invoke the endpoints as needed. Compose
will read a local `.env` file to supply tokens and other settings:

```bash
docker-compose up
```

After the containers start, visit `/docs` to explore the OpenAPI documentation or see the examples in [Docs/fastapi-api](Docs/fastapi-api).

## Versioning Preview

The provisioning spec currently sits at version **1.6.0**. Future releases will mirror the approach used by the [Typesense API specification](https://github.com/typesense/typesense-api-spec), where major versions signal breaking changes and minor versions extend functionality without disruption. The FastAPI application will continue to serve previous stable routes for as long as practical.

## Cluster Overview

All machines share the `fountainproxy` user secured by the `hetzner_deployer_key` SSH key. Traffic enters through the Caddy proxy and is routed internally to the search and application boxes. The API provides endpoints for health checks, environment variable management and Hetzner resource operations. Additional setup guides remain in the `Docs/` directory for reference but the API is now the authoritative interface. The OpenAPI specification under `openapi/provisioning-api.yaml` defines every supported operation—anything not listed there will not be executed.

## Testing

```bash
pytest --cov=scripts --cov=fastapi_app
```