bluefox-cloud — PaaS infrastructure for the Bluefox Stack

Quick start

Install

$ uv add bluefox-cloud

Configure your server

~/.bluefox/cloud.yml

platform_url: https://platform.bluefox.software
server:
  ip: 37.27.83.150
  domain: bluefox.software
  ssh_port: 6161
  user: deploy
cloudflare:
  api_token: xxx
  zone_id: xxx

Deploy a service

deploy.py

from bluefox_cloud.swarm import SwarmClient
from bluefox_cloud.traefik import TraefikConfig

swarm = SwarmClient()
await swarm.create_service(
    image="ghcr.io/my-org/my-app:latest",
    name="my-app",
)

traefik = TraefikConfig("/etc/traefik/dynamic")
traefik.write_app_config(
    app_name="my-app",
    hostnames=["my-app.bluefox.software"],
)

DNS management

Cloudflare DNS integration for subdomains, wildcard records, and custom domain verification. All async via httpx.

dns.py

from bluefox_cloud.cloudflare import CloudflareClient

async with CloudflareClient(api_token) as cf:
    # Point a subdomain at the server
    await cf.upsert_record(
        zone_id,
        name="my-app",
        record_type=DNSRecordType.A,
        content="37.27.83.150",
    )

    # Verify a custom domain
    records = await cf.list_records(zone_id, name="custom.example.com")

What's inside

Docker Swarm

Async wrapper around the Docker SDK. Create, update, scale, and remove services. Run one-shot containers for migrations and health checks.

Traefik routing

Dynamic YAML config generation per app. Supports multiple hostnames, custom domains, and Let's Encrypt TLS via the file provider.

Cloudflare DNS

Full async httpx client for the Cloudflare API. Zone lookup, DNS record CRUD, upsert by name+type, wildcard records, and custom domain verification.

SSH operations

Thin subprocess wrapper for remote commands. Bundled scripts for server hardening and Docker installation via importlib.resources.

Cloud config

Reads and writes ~/.bluefox/cloud.yml. Pydantic V2 models for server, Cloudflare, and platform configuration. Pure data, no network calls.

Zero-downtime deploys

Rolling updates via Docker Swarm with health checks and automatic rollback on failure. No downtime, no manual intervention.

Remote server setup

SSH into a fresh server, harden it, install Docker, and initialize Swarm. All from bundled scripts.

bootstrap.py

from bluefox_cloud.ssh import ssh_run, ssh_upload_and_run, get_bundled_script

# Harden the server
script = get_bundled_script("harden.sh")
result = await ssh_upload_and_run(
    host="37.27.83.150",
    user="root",
    port=22,
    script_path=script,
)

# Check Docker is running
result = await ssh_run(
    host="37.27.83.150",
    user="deploy",
    port=6161,
    command="docker info",
)