BitlBee Docker Container

A Docker container for BitlBee with extensive protocol support via plugins. TLS is built in — the container only listens on port 6697 (IRC over TLS); plaintext is never exposed.

Technical Features

• 🏗️ Multi-architecture support: linux/amd64, linux/arm64
• 🔒 Security-hardened: Non-root user, minimal capabilities, security contexts
• 🔐 TLS-only: stunnel terminates TLS inside the container; BitlBee binds loopback-only
• 📊 Health checks: Built-in monitoring with liveness/readiness probes
• 📦 SBOM generation: Software Bill of Materials for supply chain security
• 🔍 Automated vulnerability scanning: Trivy and Grype scans in CI/CD
• 🚀 Optimized builds: Layer caching and multi-stage builds
• ☸️ Kubernetes-ready: Production-grade manifests included

Supported Protocols

Built-in: BitlBee's built-in protocols

Via Plugins:

• Discord (purple-discord)
• Matrix (purple-matrix)
• Microsoft Teams (purple-teams)
• Slack (slack-libpurple)
• Facebook Messenger (mautrix-meta via built-in Matrix homeserver)
• Mastodon (bitlbee-mastodon)
• Telegram (tdlib-purple)
• WhatsApp (purple-whatsmeow)

Quick Start

Docker

# Create a volume for persistent data
docker volume create bitlbee-data

# Run BitlBee (TLS only — connect your IRC client with SSL/TLS enabled)
docker run -d \
  --name bitlbee \
  --user $(id -u):$(id -g) \
  -p 6697:6697 \
  -v bitlbee-data:/var/lib/bitlbee \
  mbologna/docker-bitlbee:latest

A self-signed TLS certificate is generated automatically on first run and stored in the persistent volume. Replace /var/lib/bitlbee/ssl/bitlbee.pem with your own certificate if needed.

Docker Compose

# Clone repository
git clone https://github.com/mbologna/docker-bitlbee.git
cd docker-bitlbee

# Configure environment
cp .env.example .env
# Edit .env with your UID/GID

# Start services
docker-compose up -d

# Access BitlBee (TLS)
# IRC over TLS: localhost:6697

Docker Compose Configuration

Environment Variables

Create a .env file:

UID=1000                        # User ID for file permissions
GID=1000                        # Group ID for file permissions
BITLBEE_PORT=6697               # BitlBee TLS port (default: 6697)
TZ=UTC                          # Timezone
MATRIX_REGISTRATION_TOKEN=      # Optional: set a fixed Matrix registration token
                                 # (auto-generated on first run if left empty)

Data Persistence

Data is stored in ./data directory or the bitlbee-data named volume.

Kubernetes

# Deploy to cluster
kubectl apply -f k8s/

# Check status
kubectl get pods -n bitlbee

# Access from within cluster (TLS only)
# bitlbee.bitlbee.svc.cluster.local:6697

# Port forward for external access
kubectl port-forward -n bitlbee svc/bitlbee 6697:6697

Kubernetes Configuration

Data Persistence

Managed by PersistentVolumeClaim (default: 128Mi, configurable in k8s/pvc.yaml).

Exposing Services

Edit k8s/ingress.yaml (uncomment the relevant block) to choose between NodePort and LoadBalancer. Both examples expose port 6697 only.

NodePort (for bare-metal clusters):

spec:
  type: NodePort
  ports:
    - name: ircs
      port: 6697
      nodePort: 30697  # Choose 30000-32767

LoadBalancer (for cloud providers):

spec:
  type: LoadBalancer
  ports:
    - name: ircs
      port: 6697

Resource Limits

Edit k8s/deployment.yaml:

resources:
  limits:
    memory: 1Gi    # Increase as needed
    cpu: 2000m
  requests:
    memory: 256Mi
    cpu: 200m

Storage Size

Edit k8s/pvc.yaml:

resources:
  requests:
    storage: 5Gi  # Adjust size

Timezone Configuration

Edit k8s/configmap.yaml:

data:
  TZ: "Europe/Rome"  # Change timezone

Using BitlBee

First-Time Setup

1. Connect to BitlBee with SSL/TLS enabled in your IRC client:

   /server -ssl localhost 6697
   

   Accept the self-signed certificate (or replace it with your own at /var/lib/bitlbee/ssl/bitlbee.pem).

2. Register an account:

   register <password>
   

3. Add a messaging account:

   account add <protocol> <username> <password>
   account <id> on
   

4. Save configuration:

   save
   

Example: Discord

account add discord your-email@example.com your-password
account discord on
save

Example: Facebook Messenger (with 2FA)

Facebook Messenger is bridged via an embedded Matrix homeserver (conduwuit) and a mautrix-meta bridge. Both run inside the same container — no extra services needed.

On first container start, look for the Matrix registration token in the logs:

docker logs bitlbee | grep "registration token"
# or set MATRIX_REGISTRATION_TOKEN in your .env to choose your own

In your IRC client:

1. Register a local Matrix account (one-time setup):

   register_matrix <your-matrix-username> <password> <registration-token>
   

   Or, using the raw Matrix account add:

   account add matrix <username>@localhost <password> http://localhost:6167
   

   When BitlBee asks for a registration token, paste the one from the logs.

2. Enable the account:

   account matrix on
   

3. Start a conversation with the bridge bot to link your Facebook account:

   /msg @facebookbot:localhost login
   

   The bot will guide you through a QR code or link-based login — this works with 2FA and does not use the old (broken) mobile API.

4. Once linked, your Facebook contacts appear as channels/users in BitlBee. Save:

   save
   

Star History