Getting started¶

Installation¶

uv add bluefox-yml

Or with pip:

pip install bluefox-yml

Create a manifest¶

Create a bluefox.yml file in your project root:

bluefox.yml

version: 1
name: my-saas

compute:
  app:
    port: 8000

data:
  engine: postgres
  version: 17
  migrate: "uv run alembic upgrade head"

in-memory:
  engine: redis
  version: 7

Required fields¶

Field	Description
`version`	Manifest version. Must be `1`.
`name`	DNS-safe app name (lowercase, digits, hyphens, 3-63 chars).
`compute`	At least one compute process.

Optional fields¶

Field	Description
`data`	Database primitive (`postgres` in v1).
`in-memory`	In-memory store (`redis` in v1).

Load and validate¶

from bluefox_yml import load_manifest, ManifestError, format_error

try:
    manifest = load_manifest("bluefox.yml")
except ManifestError as e:
    print(format_error(e))
    raise SystemExit(1)

The load_manifest function:

Reads the YAML file
Validates all fields against the schema
Returns a typed Manifest object
Raises ManifestError with clear messages on any problem

Compute processes¶

Each key under compute is a process name. The key becomes the process mode.

compute:
  app:
    port: 8000        # routable — gets a healthcheck at /health
  worker: {}          # background process — no port

Rules:

At most one process may declare a port.
Processes with a port get a default healthcheck: /health.
You can override the healthcheck path: healthcheck: /ready.
Workers (no port) cannot set a healthcheck.

Data primitives¶

data:
  engine: postgres
  version: 17
  migrate: "uv run alembic upgrade head"

engine — currently only postgres is supported.
version — positive integer (engine major version).
migrate — optional migration command run on deploy.

In-memory primitives¶

in-memory:
  engine: redis
  version: 7

engine — currently only redis is supported.
version — positive integer (engine major version).

Helper methods¶

Once loaded, the manifest provides helpers for the platform:

manifest = load_manifest()

# Docker service names
manifest.service_name("app")       # "my-saas_app"
manifest.db_service_name()         # "my-saas-db"
manifest.redis_service_name()      # "my-saas-redis"

# Container images
manifest.image_tag(3)              # "localhost:5000/my-saas:v3"
manifest.db_image()                # "postgres:17-alpine"
manifest.redis_image()             # "redis:7-alpine"

# Routing
manifest.routable_process()        # ("app", ComputeProcess(...))

# Environment
manifest.env_vars("app")           # {"APP_NAME": "my-saas", "MODE": "app", "PORT": "8000"}
manifest.env_vars("worker")        # {"APP_NAME": "my-saas", "MODE": "worker"}