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)

BitDrip has two tiers. Server ports are exposed by the installer on whichever machine you run install.sh. Workstation ports are local to each end-user device.

Server (runs once on your infrastructure):

Service	Port	Description
Dashboard	3000	Admin web UI
Policy Engine	3002	REST API — workstations and dashboard connect here
PostgreSQL	5432	Internal — not exposed outside Docker network
Redis	6379	Internal — not exposed outside Docker network

Workstation (runs on each end-user device):

Service	Port	Description
Proxy Daemon	3001	MITM proxy, PAC server, health endpoint

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.

CA Certificate Setup

BitDrip uses a local MITM proxy to intercept HTTPS traffic to AI services. This requires a custom CA certificate that browsers and the OS trust. Run these two commands once per host before starting the proxy:

# Generate a CA keypair (stored in the OS keychain via keytar)
bitdrip cert generate

# Install the CA cert into all trust stores
bitdrip cert install

bitdrip cert install covers:

• macOS — System Keychain via security add-trusted-cert
• Linux Debian/Ubuntu — /usr/local/share/ca-certificates/ + update-ca-certificates
• Linux RHEL/Fedora — /etc/pki/ca-trust/source/anchors/ + update-ca-trust
• Firefox — NSS database at ~/.mozilla/firefox/*/cert9.db via certutil
• Chrome — NSS database at ~/.pki/nssdb via certutil

After installation, browsers and CLI tools will trust the proxy's dynamically generated certificates without warnings.

Troubleshooting: browser shows a security warning

"Be careful. Something doesn't look right" / "Your connection is not private"

This warning means the proxy is intercepting traffic correctly — but the CA certificate hasn't been trusted by the browser yet. This is the same setup step required by any MITM proxy (Burp Suite, Charles, mitmproxy) and only needs to be done once per device.

Step 1: Verify the CA certificate exists

bitdrip cert status

If this prints subject, dates, and a fingerprint, the CA is generated. If it says "No CA certificate found", run bitdrip cert generate first.

Step 2: Install and trust the CA

bitdrip cert install

On Linux, this requires sudo for the system trust store and certutil for Firefox/Chrome NSS databases. If certutil is not installed:

# Fedora / RHEL
sudo dnf install nss-tools

# Debian / Ubuntu
sudo apt install libnss3-tools

Step 3: Fully quit and relaunch your browser

This is the most commonly missed step. Browsers load the NSS trust store once at startup — closing a tab or window is not enough.

• Firefox: File → Quit (or pkill firefox), then relaunch
• Chrome / Chromium: Quit all windows, then relaunch

After relaunching, navigate to an AI service and the warning should be gone.

Why can't I click "Advanced" and add an exception?

Sites like chat.openai.com, claude.ai, and api.anthropic.com use HTTP Strict Transport Security (HSTS), which instructs browsers to refuse any certificate exception. The only fix is to have the CA trusted — there is no bypass.

Manual Firefox trust (if certutil install fails)

1. Open Firefox → Settings → Privacy & Security → Certificates → View Certificates
2. Import tab → navigate to ~/.bitdrip/ca.crt
3. Check "Trust this CA to identify websites" → OK
4. Fully quit and relaunch Firefox

Proxy Daemon

The proxy daemon (port 3001) is a local HTTPS MITM proxy. It intercepts TLS connections to AI API domains (OpenAI, Anthropic, Claude.ai, Google Gemini, and others), evaluates the request body against the Policy Engine, and either blocks with HTTP 403 or forwards to the upstream API.

Traffic is routed through the proxy automatically via a PAC file served at http://localhost:3001/proxy.pac. The tray app and bitdrip proxy enable activate this PAC file via the system proxy settings, covering both browsers and CLI tools transparently.

Starting the proxy daemon

bitdrip proxy start

This starts the proxy daemon as a systemd service (Linux) or launchd service (macOS) and activates the PAC file via system proxy settings.

Enabling and disabling

# Activate PAC routing (browser + system proxy)
bitdrip proxy enable

# Deactivate PAC routing without stopping the daemon
bitdrip proxy disable

# Check current status
bitdrip proxy status

No environment variable exports are required. With the MITM proxy, CLI tools such as claude, openai, Cursor, and Copilot CLI are protected automatically through the system proxy settings — no base URL changes needed.

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

Kubernetes (Helm)

A Helm chart is included at deploy/helm/bitdrip/ for teams running Kubernetes.

Requirements:

• Helm 3.x
• A Kubernetes cluster with a StorageClass configured
• GHCR pull credentials (create a Kubernetes secret from your GitHub personal access token or use the credentials printed by install.sh)

Basic install:

helm install bitdrip ./deploy/helm/bitdrip \
  --set image.tag=2.2.15 \
  --set policyEngine.secrets.databaseUrl="postgresql://..." \
  --set policyEngine.secrets.redisUrl="redis://..." \
  --set policyEngine.secrets.jwtSecret="..." \
  --set policyEngine.secrets.hmacSecret="..." \
  --set policyEngine.licenseSecret="<base64-encoded license.jwt>"

See deploy/helm/bitdrip/values.yaml for the full set of configuration options, including ingress rules, TLS termination, replica counts, and resource limits.

Upgrading

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

The installer bundle includes upgrade.sh for in-place upgrades:

bash upgrade.sh

This pulls the latest image version from GHCR (pinned to BITDRIP_VERSION in .env) and restarts the containers. Your .env, license.jwt, and PostgreSQL data are preserved.

To upgrade manually from a new bundle:

# 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.