5 minutes
Quickstart
Test CloudBroker in about 5 minutes. You need Docker and Docker Compose.
make ingest-azure to get started immediately. Azure pricing uses a public API; no API key required.
Clone and configure
git clone https://github.com/braghettos/cloudbroker
cd cloudbroker
cp .env.example .env
Default .env works for local Docker. No API keys required for development.
Start the stack
make up
make migrate
Starts API + PostgreSQL. Migrations run automatically. API is at http://localhost:8000.
Ingest pricing data
Ingest at least one provider. Azure works without credentials (see callout above):
make ingest-azure
Or use Hetzner (needs HETZNER_API_TOKEN in .env):
make ingest-hetzner
For all providers: make ingest-all (requires credentials for each).
For TCO-aware recommendations, also run: make ingest-egress (or make ingest-all-costs for full cost rates).
Test the recommendation API
Your first recommendation — if you see a ranked list, CloudBroker is working. 🎉
curl -X POST http://localhost:8000/api/recommendations \
-H "Content-Type: application/json" \
-d '{"min_vcpu": 2, "min_ram_gb": 4, "arch": "x86_64", "region_constraint": "EU", "max_price_eur_per_hour": 0.5, "limit": 5}'
Expected response
{
"recommendations": [
{
"instance_type_name": "cx23",
"provider_slug": "hetzner",
"region_slug": "fsn1",
"vcpu": 2,
"ram_gb": 4.0,
"score": 0.9898,
"explain": {
"resource_fit": 1.0,
"normalized_price": 0.9797,
"price_eur_per_hour": 0.0048,
"region_is_eu": true,
"tco_eur_per_hour": null
}
}
]
}If you see a ranked list, CloudBroker is working. ✅
See more example requests → /examples
Optional TCO: add "data_source_provider": "azure", "data_source_region": "westeurope", "estimated_egress_gb_per_hour": 1.0 for total cost breakdown in explain.
What's Next?
Explore more of the CloudBroker ecosystem:
Common issues
make up fails immediately
Ensure Docker and Docker Compose are running. Try docker ps to verify.
/api/recommendations returns an empty list
Ingest at least one provider first. Run make ingest-azure (no credentials needed) or make ingest-hetzner (with HETZNER_API_TOKEN in .env).
Ingestion fails with a credential error
Check .env for the required API keys. Azure works without credentials. See the repo's .env.example for provider-specific vars.
Port 8000 is already in use
Change API_PORT in .env or stop the process using port 8000.