Deploying Bifolk from GitLab Container Registry

This guide explains how to deploy Bifolk using pre-built Docker images from the GitLab Container Registry.

Prerequisites

• Docker Engine 20.10+ and Docker Compose 2.0+
• Git (to clone repository for configuration files)
• Access to the GitLab Container Registry (public images require no authentication; private images require a token)

Overview

Instead of building Docker images locally, you can use pre-built images published to the GitLab Container Registry. This approach:

• Saves build time - No need to build images on your deployment server
• Ensures consistent deployments - Use the same tested images across environments
• Simplifies updates - Pull new versions with a single command
• Uses verified images - Images are built and tested via CI/CD pipeline

Quick Start

1. Clone Repository (for configuration files)

git clone https://code.wdmt.de/bifolk/bifolk.git
cd bifolk

2. Configure Secrets

Copy the example secrets and configure them with your actual values:

cp -r secrets.example secrets

Edit files in secrets/: - secret_key.txt - Django SECRET_KEY (generate with: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())") - db_password.txt - PostgreSQL password - email_password.txt - SMTP password for email functionality

Set proper permissions:

bash scripts/bifolk_set_permissions.sh

3. Set Up Docker Compose

Copy the example configuration:

cp docker-compose.example.yml docker-compose.yml

Edit docker-compose.yml and set the image URLs:

services:
  bifolk-app:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:latest
  bifolk-docs:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-docs:latest

4. Configure Environment (Optional)

Create a .env file if you need to override default settings:

# Copy example environment file
cp .env.example .env

Edit .env to customize settings like: - DJANGO_DEBUG=False (important for production!) - DJANGO_ALLOWED_HOSTS=your-domain.com - EMAIL_HOST=smtp.example.com - Database settings

5. Pull and Start

# Pull latest images from registry
docker-compose pull

# Start services in background
docker-compose up -d

# View logs
docker-compose logs -f

6. Verify Deployment

Check container status:

docker-compose ps

View application logs:

docker-compose logs -f bifolk-app

Access the application: - Application: http://localhost:8000 - Documentation: http://localhost:8001

Image Tags

Images are published with multiple tags:

Tag	Description	Use Case
stable	Latest versioned release (same as latest v*..)	Production (recommended)
latest	Latest build from next-release branch	Production
v0.x.x	Specific version (semantic versioning)	Production (pinned version)

Tag Examples

# Use stable release (recommended for production)
image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:stable

# Use latest from next-release branch
image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:latest

# Pin to specific version
image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:v0.1.0

Production Deployment Recommendations

1. Use Stable or Specific Version Tags

For production, use the stable tag or specific version tags instead of latest:

services:
  bifolk-app:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:stable  # Always latest release
  bifolk-docs:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-docs:stable

Or pin to a specific version for maximum control:

services:
  bifolk-app:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:v0.1.0  # Pin to specific version
  bifolk-docs:
    image: registry.code.wdmt.de/bifolk/bifolk/bifolk-docs:v0.1.0

This ensures: - Predictable deployments - Easy rollback to previous versions - No unexpected changes from automatic updates

2. Disable Debug Mode

Ensure DJANGO_DEBUG=False in production:

environment:
  - DJANGO_DEBUG=False

3. Configure Allowed Hosts

Set proper allowed hosts for your domain:

environment:
  - DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

4. Use Strong Secrets

• Generate a strong SECRET_KEY
• Use complex database passwords
• Secure email credentials

5. Configure Email

Set up proper SMTP settings for email functionality:

environment:
  - EMAIL_HOST=smtp.example.com
  - EMAIL_PORT=587
  - EMAIL_USE_TLS=True
  - EMAIL_USER=your-email@example.com
  - DEFAULT_FROM_EMAIL=noreply@yourdomain.com

6. Use Reverse Proxy

For production, use a reverse proxy (Nginx, Traefik) for: - SSL/TLS termination - Load balancing - Static file serving - Request filtering

Updating to New Versions

Method 1: Update to Latest Release

# Pull latest images
docker-compose pull

# Recreate containers with new images
docker-compose up -d

# View logs to verify update
docker-compose logs -f bifolk-app

Method 2: Update to Specific Version

1. Edit docker-compose.yml and change the image tags:

image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:v0.2.0

1. Pull and restart:

docker-compose pull
docker-compose up -d

Method 3: Rolling Back

To roll back to a previous version:

1. Edit docker-compose.yml with the previous version tag:

image: registry.code.wdmt.de/bifolk/bifolk/bifolk-app:v0.1.0

1. Pull and restart:

docker-compose pull
docker-compose up -d

Authentication for Private Images

If the registry is private, you need to authenticate with the GitLab Container Registry.

Create Personal Access Token (PAT)

1. Go to GitLab → User Settings → Access Tokens
2. Click "Add new token"
3. Select scope: read_registry
4. Generate token and copy it

Login to Registry

echo YOUR_GITLAB_TOKEN | docker login registry.code.wdmt.de -u YOUR_USERNAME --password-stdin

After authentication, you can pull private images normally.

Monitoring and Maintenance

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f bifolk-app

# Last 100 lines
docker-compose logs --tail=100 bifolk-app

Check Container Health

# Container status
docker-compose ps

# Health check status
docker inspect --format='{{.State.Health.Status}}' bifolk-app

Database Backup

# Backup database
docker exec bifolk-db pg_dump -U bifolk bifolk > backup.sql

# Restore database
docker exec -i bifolk-db psql -U bifolk bifolk < backup.sql

Resource Usage

# Container resource usage
docker stats bifolk-app bifolk-db bifolk-docs

Troubleshooting

Image Pull Fails

Problem: Error response from daemon: manifest for registry.code.wdmt.de/... not found

Solutions: - Verify the image tag exists in the registry (check the GitLab Container Registry page) - Ensure the image URL is correct - If the registry is private, authenticate with a PAT (see Authentication section) - Check internet connectivity

Container Fails to Start

Problem: Container exits immediately after starting

Solutions:

1. Check logs:

   docker-compose logs bifolk-app
   

2. Verify secrets are configured:

   ls -la secrets/
   

3. Ensure database is ready:

   docker-compose logs bifolk-db
   

4. Check environment variables in docker-compose.yml

Database Connection Issues

Problem: could not connect to server: Connection refused

Solutions:

1. Verify DB_HOST is set to bifolk-db (the service name)

2. Check if database container is running:

   docker-compose ps bifolk-db
   

3. Review database logs:

   docker-compose logs bifolk-db
   

4. Verify database credentials in secrets match docker-compose.yml

Permission Denied Errors

Problem: Permission errors accessing volumes or secrets

Solutions:

1. Set correct permissions on secrets:

   bash scripts/bifolk_set_permissions.sh
   

2. Check volume ownership:

   docker-compose exec bifolk-app ls -la /bifolk/static
   

3. Recreate volumes if needed:

   docker-compose down -v
   docker-compose up -d
   

Application Not Accessible

Problem: Cannot access http://localhost:8000

Solutions:

1. Check if port is already in use:

   sudo netstat -tulpn | grep 8000
   

2. Verify container port mapping:

   docker-compose ps
   

3. Check firewall rules (if on remote server)

4. Test with curl:

   curl http://localhost:8000
   

Advanced Configuration

Custom Port Mapping

Change the exposed port in docker-compose.yml:

ports:
  - "8080:8000"  # Access on port 8080

Or use .env file:

APP_PORT=8080

Using External Database

To use an external PostgreSQL database:

1. Remove bifolk-db service from docker-compose.yml
2. Update database environment variables:

environment:
  - DB_HOST=external-db-host.com
  - DB_PORT=5432
  - DB_NAME=bifolk
  - DB_USER=bifolk
  # Set DB_PASSWORD via secret

Multiple Environments

Create separate compose files for different environments:

• docker-compose.prod.yml - Production
• docker-compose.staging.yml - Staging
• docker-compose.dev.yml - Development

Use with:

docker-compose -f docker-compose.prod.yml up -d

See Also

• Installation Guide
• Configuration Guide
• Troubleshooting Guide
• GitLab Container Registry Documentation