Skip to content

Installation Guide

This guide walks you through installing Bifolk using Docker.

Target Audience: System administrators, DevOps engineers

Prerequisites

Docker

  • Docker Engine 20.10 or higher
  • Docker Compose 2.0 or higher
  • Git for cloning the repository
  • At least 1 GB of disk space

Podman

Bifolk also supports deployment with Podman using systemd Quadlets. See the Podman Deployment guide for full instructions.

Quick Start (Development)

The development setup uses SQLite and runs with DEBUG=True.

# Clone repository
git clone <repo-url>
cd bifolk

# Set up environment
cd docker/compose-developement
cp .env.example .env

# Build and start
docker compose up --build

# In a separate terminal, create the superuser
docker compose exec bifolk-app python manage.py createsuperuser

# Optionally load sample data
docker compose exec bifolk-app python manage.py load_sample_data

Access Bifolk at http://localhost:8000.

Docker Compose Setup

Bifolk provides Docker Compose configurations under docker/:

Directory Database Purpose
compose-developement/ SQLite Development and testing

Services

Service Port Purpose
bifolk-app 8000 Main Django application
bifolk-docs 8001 MkDocs documentation server

Volumes

Volume Purpose
bifolk_static Static files (CSS, JS, images)
bifolk_media User-uploaded files (profile photos, hive photos)
bifolk_db SQLite database file
bifolk_logs Application log files

Docker Secrets

Secret File Purpose
bifolk_secret_key secrets/secret_key.txt Django SECRET_KEY
bifolk_email_password secrets/email_password.txt SMTP password
bifolk_oidc_client_secret secrets/oidc_client_secret.txt OIDC client secret

See Docker Secrets for secure configuration.

Container Security

All Bifolk containers are hardened with the following defaults:

  • Non-root user — each service runs as a dedicated unprivileged user
  • cap_drop: ALL — all Linux capabilities dropped by default
  • no-new-privileges: true — prevents privilege escalation inside the container
Service User Capabilities granted
bifolk-app bifolk (system user) CHOWN, SETGID, SETUID (needed by entrypoint to chown volumes and drop to the app user)
bifolk-docs docs (uid/gid 21111) None — all docs files are baked into the image at build time
bifolk-db postgres (managed by image) CHOWN, SETGID, SETUID, FOWNER

The default Compose files do not enforce CPU or memory limits. For production deployments, add deploy.resources constraints to prevent a single service from exhausting host resources:

services:
  bifolk-app:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Adjust values based on your host capacity and workload. Suggested starting points:

Service CPU limit Memory limit CPU reservation Memory reservation
bifolk-app 2.0 1G 0.5 512M
bifolk-db 1.0 512M 0.25 256M
bifolk-docs 0.5 128M 0.1 64M

Production Deployment

For production, adjust the following:

1. Environment Variables

Edit .env:

DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://yourdomain.com

2. Secrets

Update the secret files in secrets/:

# Generate a strong secret key
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())" > secrets/secret_key.txt

# Set secure permissions
bash scripts/bifolk_set_permissions.sh

3. Email Configuration

Configure SMTP for email verification and notifications:

EMAIL_HOST=smtp.yourdomain.com

# For STARTTLS (port 587):
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_USE_SSL=False

# For implicit SSL (port 465), use this instead:
# EMAIL_PORT=465
# EMAIL_USE_TLS=False
# EMAIL_USE_SSL=True

EMAIL_USER=noreply@yourdomain.com
DEFAULT_FROM_EMAIL=noreply@yourdomain.com

4. Reverse Proxy and HTTPS

Set up a reverse proxy (Traefik, Nginx, Caddy) for HTTPS. Bifolk does not handle TLS directly.

Warning

Bifolk must always run behind a reverse proxy in production. Running without one removes HTTP security headers (HSTS, CSP, etc.) and exposes internal endpoints. See Reverse Proxy & Security Headers for required configuration.

For production, use PostgreSQL instead of SQLite. Uncomment the PostgreSQL settings in .env:

DB_ENGINE=django.db.backends.postgresql
DB_NAME=bifolk
DB_USER=bifolk
DB_HOST=bifolk-db
DB_PORT=5432
DB_PASSWORD=your-secure-password

Add a PostgreSQL service to your docker-compose.yml.

Health Check

The container includes a health check endpoint at /health/ that verifies the application is running. Docker uses this to monitor container health.

Next Steps