Installation

Prerequisites

• Git
• Docker and Docker Compose installed

Tip

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

Windows 11

On Windows, use Initialize-Bifrost.ps1 in native PowerShell instead of the Bash setup.sh — see Windows 11 deployment below. Docker Desktop must use the WSL2 backend.

Quick Start

1. Clone the repository:

   git clone https://github.com/gobifrost/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.

   

Windows 11 deployment

To deploy Bifrost on Windows, use native PowerShell — no WSL or Bash required. Install Git for Windows and Docker Desktop (with the WSL2 backend enabled), then:

1. Clone and enter the repository:

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

2. Run the PowerShell setup script:

   .\Initialize-Bifrost.ps1

   It prompts for your domain, generates .env with secure secrets, runs docker compose up -d, and prints the access URL. Pass -Domain to skip the prompt; -NoStart to generate .env without launching.

3. Access the application at the printed URL (http://localhost:3000 for a localhost deployment).

Initialize-Bifrost.ps1 is the PowerShell counterpart to setup.sh; it generates the same .env and needs no openssl, sed, or Git Bash.

Note

Developing the platform itself (running ./debug.sh / ./test.sh against the source) is supported on Linux and macOS. On Windows those Bash scripts run through Git Bash or Ubuntu on WSL2, not native PowerShell. For CLI-only workflow development against an existing instance, see Local Development Setup.

If winget fails on a fresh Windows image with 0x8a15000f, set the Windows region, reset winget sources, then retry:

Set-WinHomeLocation -GeoId 244
winget source reset --force
winget source update

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