Boreas

Boreas is a FastAPI background-removal backend built for a narrow job: accept uploads quickly, push heavy work off-request, and stay understandable under load.

Architecture rationale lives in docs/system-design.md. Contributor rules live in CONTRIBUTING.md. Deployment and model-tuning guidance lives in docs/deployment-guide.md. Developer integration guidance lives in docs/integration-guide.md.

What It Does

• POST /v1/media/jobs accepts an image and returns a job id immediately.
• GET /v1/media/jobs/{job_id} returns job state and a result URL when ready.
• GET /v1/media/jobs/{job_id}/stream streams job updates through SSE.
• / exposes a lightweight reachability endpoint for liveness checks.
• /health exposes public runtime health, queue depth, and staging metrics.

Runtime Shape

• app/features/media: public upload API, validation, staging, normalization, ingest worker
• app/features/rembg: background-removal compute and compute worker
• app/features/tasks: hourly ARQ cron cleanup (Redis job state + orphan S3 objects)
• app/features/health: status and health endpoints
• app/core: bootstrap, middleware, config, Redis, ARQ, shared storage primitives

The public request path stays thin. The queue carries job ids, not images. Redis stages uploads briefly, object storage holds prepared sources and final results, and the workers own the expensive work.

start.sh launches the API plus media, compute, and tasks workers. Each worker process is respawned automatically if it exits.

Why It Is Built This Way

• the API should return fast even when processing is expensive
• input normalization and background removal are different responsibilities
• Redis is good for short-lived state handoff, not long-lived file storage
• object lifecycle has to be explicit or it turns into cost and cleanup drift
• contributor ownership should be obvious from the folder layout

The longer explanation is in docs/system-design.md.

Abuse Protection

By default Boreas allows 5/minute per client IP for API reads and uploads.

That is intentionally conservative because uploads and rembg work are expensive. Both limits are environment-configurable through API_RATE_LIMIT and UPLOAD_RATE_LIMIT.

If clients want frequent job updates, SSE is the intended path. Repeated polling will hit the limit faster and costs more.

Object Lifecycle

• staged uploads expire from Redis quickly
• job metadata expires through Redis TTL; terminal jobs are also swept hourly by the tasks worker
• prepared source objects should be deleted immediately after successful compute
• final result objects should expire after one hour through an object storage lifecycle rule
• the hourly tasks cron deletes orphan S3 objects older than JOB_TTL_SECONDS as a safety net

Configure bucket lifecycle for results; the app cron covers failures and misconfiguration.

Configuration

Copy .env.example to .env and set the required values.

Important settings:

• REDIS_URL
• API_RATE_LIMIT
• UPLOAD_RATE_LIMIT
• JOB_TTL_SECONDS
• RESULT_URL_TTL_SECONDS
• MEDIA_SOURCE_MAX_BYTES
• MEDIA_STAGING_TTL_SECONDS
• MEDIA_WORKERS
• BACKGROUND_REMOVAL_WORKERS
• TASKS_WORKERS
• STORAGE_ENDPOINT_URL
• STORAGE_ACCESS_KEY_ID
• STORAGE_SECRET_ACCESS_KEY
• STORAGE_BUCKET_NAME
• REMBG_MODEL
• REMBG_POST_PROCESS_MASK
• REMBG_ALPHA_MATTING
• REMBG_ALPHA_MATTING_FOREGROUND_THRESHOLD
• REMBG_ALPHA_MATTING_BACKGROUND_THRESHOLD
• REMBG_ALPHA_MATTING_ERODE_SIZE
• REMBG_OMP_NUM_THREADS
• REMBG_INFERENCE_TIMEOUT_SECONDS
• STARTUP_DEPENDENCY_MAX_ATTEMPTS
• STARTUP_DEPENDENCY_RETRY_DELAY_SECONDS
• LOG_LEVEL
• AXIOM_TOKEN
• AXIOM_DATASET

If AXIOM_TOKEN is unset, Boreas logs to stdout only. When set, structured logs are also forwarded to the configured Axiom dataset (default boreas-logs).

STARTUP_DEPENDENCY_MAX_ATTEMPTS and STARTUP_DEPENDENCY_RETRY_DELAY_SECONDS control how long Boreas retries Redis and ARQ warmup before failing startup.

Coolify On Hostinger KVM2

For a small CPU-only VPS, keep the deployment conservative:

• keep MEDIA_WORKERS=1
• keep BACKGROUND_REMOVAL_WORKERS=1
• keep TASKS_WORKERS=1
• use REMBG_MODEL=isnet-general-use for a better edge-quality and latency balance than u2netp
• keep REMBG_POST_PROCESS_MASK=true
• leave REMBG_ALPHA_MATTING=false by default and only enable it if you can afford lower throughput for finer edges like hair or fur
• set REMBG_OMP_NUM_THREADS=2 so ONNX does not oversubscribe the VM

If Coolify lets you mount persistent storage, mount U2NET_HOME so model downloads survive redeploys instead of re-downloading on the next cold worker start.

Local Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
./start.sh

VS Code Launching

Use .vscode/launch.json for local debugging.

It includes:

• Boreas API
• Boreas Media Worker
• Boreas Background Removal Worker
• Boreas Tasks Worker
• Boreas API + Workers compound launch

That gives you a clean way to debug the API and all worker processes without relying on the shell script.

Validation

Run the current v1 test surface with:

./.venv/bin/python -m unittest discover -s tests

The suite currently covers:

• ingest lifecycle behavior
• source deletion after compute
• one-hour result URL assumptions
• health metrics payload
• hourly tasks cleanup (Redis + S3 sweep)