Installation

System Requirements

Requirement	Minimum	Recommended
CPU	2 cores	4 cores
RAM	2 GB	8 GB
Disk	4 GB	20 GB
OS	Linux, macOS, Windows (WSL2)	Ubuntu 22.04 LTS
Runtime	Docker 24+ or Podman 4+	Docker 24+

Service Ports (default)

Service	Port	Description
Dashboard	3000	Admin web UI
Policy Engine	3001	REST API
API Gateway	3002	AI proxy
PostgreSQL	5432	Internal — not exposed by default
Redis	6379	Internal — not exposed by default

Environment Variables

The installer generates .env automatically from .env.example. Key variables you may need to customise after installation:

Variable	Description	Default
ADMIN_EMAIL	Initial admin account email	Set at install
ADMIN_PASSWORD	Initial admin account password	Auto-generated
JWT_SECRET	JWT signing secret	Auto-generated
POSTGRES_PASSWORD	Database password	Auto-generated
KEYCLOAK_ENABLED	Enable SSO via Keycloak	false
ALLOWED_ORIGINS	CORS allowed origins	http://localhost:3000
NODE_ENV	Runtime mode	production

Do not commit .env to version control — it contains secrets.

API Gateway

To route your OpenAI or Anthropic API calls through BitDrip, point your application's base URL at the gateway:

# Instead of:
OPENAI_BASE_URL=https://api.openai.com/v1

# Use:
OPENAI_BASE_URL=http://localhost:3002/openai/v1

The gateway forwards the request to the upstream API only after the Policy Engine approves the content.

User Management

Add users in the Admin Dashboard: Users → Invite.

Invited users receive an email with a setup link and sign in with their organisation email.

For SSO (Keycloak / SAML / OIDC) see SSO below.

SSO

Set KEYCLOAK_ENABLED=true in .env and configure:

KEYCLOAK_URL=https://your-keycloak-host
KEYCLOAK_REALM=bitdrip
KEYCLOAK_CLIENT_ID=bitdrip-web

BitDrip ships a pre-configured Keycloak service. Start it with:

docker compose --profile sso up -d

Upgrading

Find the latest version number at portal.bitdrip.app after signing in, or in your welcome email download link.

# Download the new bundle from your account at portal.bitdrip.app
tar -xzf bitdrip-<new-version>.tar.gz
cd bitdrip-<new-version>
cp ../bitdrip-<old-version>/license.jwt ./license.jwt
cp ../bitdrip-<old-version>/.env ./.env
bash install.sh

The installer detects the existing installation and performs a rolling update.

Uninstalling

docker compose down -v   # removes containers and volumes

Export compliance reports and audit logs from the dashboard before uninstalling if you need to retain them.