Installation

Prerequisites

• Docker and Docker Compose installed

Tip

Docker Desktop includes Docker Compose. For Linux servers, install both separately.

Quick Start

1. Clone the repository:

   git clone https://github.com/jackmusick/bifrost.git
   cd bifrost

2. Run the setup script:

   ./setup.sh

   This generates .env with secure random secrets for all services.

3. Start all services:

   docker compose up

4. Access the application at http://localhost:3000

   The first user to register becomes the Platform Admin.

Architecture Overview

Docker Compose starts these services:

Service	Purpose
api	FastAPI application - handles HTTP requests
client	React frontend served via nginx
worker	Background job processor (scalable)
scheduler	Runs scheduled workflows and cleanup jobs
postgres	Primary database
pgbouncer	Connection pooler for PostgreSQL
rabbitmq	Message queue for async jobs
redis	Sessions, cache, and sync execution results
minio	S3-compatible object storage for workspace files

Environment Variables

The setup.sh script generates all required secrets automatically. You only need to edit .env for optional features.

Optional Configuration

Variable	Description
BIFROST_DEFAULT_USER_EMAIL	Skip setup wizard by pre-creating admin
BIFROST_DEFAULT_USER_PASSWORD	Password for default admin user
BIFROST_CORS_ORIGINS	Allowed origins for CORS (default: http://localhost:3000)

Single Sign-On (Optional)

SSO providers (Microsoft, Google, OIDC) are configured in the UI, not via environment variables.

See Configure SSO for setup instructions.

Verify Installation

Check service health:

# View all container status
docker compose ps

# Check API health
curl http://localhost:3000/api/health

# View logs
docker compose logs -f api
docker compose logs -f worker

Production Considerations

Security

• Generate cryptographically secure values for BIFROST_SECRET_KEY, POSTGRES_PASSWORD, and RABBITMQ_PASSWORD
• Use a reverse proxy (nginx, Traefik, Caddy) with TLS termination
• Consider using external secret management to populate .env

Scaling Workers

Increase worker replicas for higher throughput:

WORKER_REPLICAS=3 docker compose up

Or scale dynamically:

docker compose up -d --scale worker=3

Kubernetes

For Kubernetes deployments:

• Scheduler must run as a single replica
• Workers can scale horizontally (they download workspace from S3)
• Consider managed PostgreSQL, RabbitMQ, Redis, and S3-compatible storage
• See the k8s/ directory for example manifests

Tip

Workers download workspace files from S3 before execution, enabling horizontal scaling without shared volumes.

Next Steps

• Create your first workflow
• Set up local development
• Configure OAuth integration