Skip to content

Upgrading

Guide for upgrading Bifolk to a new version.

Target Audience: System administrators

Before You Upgrade

Complete this checklist before starting:

  • Read the release notes for breaking changes
  • Back up the database (see Backup & Restore)
  • Back up media files and configuration (.env, secrets/)
  • Ensure sufficient disk space
  • Notify users of planned downtime

Check Current Version

# Git version
git describe --tags --always

# Django version
docker compose exec bifolk-app python -c "import django; print(django.get_version())"

Standard Upgrade Procedure

Step 1: Back Up

# Database backup (PostgreSQL)
docker compose exec bifolk-db pg_dump -U bifolk bifolk -F c > backup-pre-upgrade-$(date +%Y%m%d).dump

# Media files
tar -czf media-backup-$(date +%Y%m%d).tar.gz -C app/media .

# Configuration
tar -czf config-backup-$(date +%Y%m%d).tar.gz .env config/

Step 2: Stop the Application

docker compose stop bifolk-app

Step 3: Pull Latest Code

git fetch origin

# Checkout a specific version (recommended)
git checkout v1.3.0

# Or pull latest from main
git checkout main && git pull origin main

Step 4: Rebuild and Migrate

# Rebuild Docker image
docker compose build bifolk-app

# Apply database migrations
docker compose run --rm bifolk-app python manage.py migrate

# Update static files
docker compose run --rm bifolk-app python manage.py collectstatic --no-input

Step 5: Start and Verify

# Start the application
docker compose up -d

# Check logs for errors
docker logs bifolk-app --tail 100

# Verify the web interface
curl -I http://localhost:8000

# Run Django system check
docker compose exec bifolk-app python manage.py check --database default

Step 6: Post-Upgrade Verification

  • Log in as admin user
  • Verify existing hives and inspections display correctly
  • Test creating a new record
  • Check organization switching works
  • Monitor logs for 24 hours

Quick Upgrade (Development Only)

Warning

Only use this for development environments.

git pull origin main
docker compose down
docker compose up -d --build
docker compose exec bifolk-app python manage.py migrate

Database Migrations

Check Pending Migrations

# Show all migrations and their status
docker compose exec bifolk-app python manage.py showmigrations

# Show only unapplied
docker compose exec bifolk-app python manage.py showmigrations --plan | grep "\[ \]"

Apply Migrations

# Always back up first
docker compose exec bifolk-db pg_dump -U bifolk bifolk -F c > backup-pre-migration.dump

# Apply
docker compose exec bifolk-app python manage.py migrate

Handling Failed Migrations

# Rollback a specific app to a previous migration
docker compose exec bifolk-app python manage.py migrate hives 0003_previous_migration

# If unrecoverable, restore from backup
# See Rollback section below

Rollback

If an upgrade fails, restore to the previous state.

Full Rollback

# Stop the application
docker compose stop bifolk-app

# Restore database from backup
docker compose exec -T bifolk-db psql -U bifolk -c "DROP DATABASE bifolk;"
docker compose exec -T bifolk-db psql -U bifolk -c "CREATE DATABASE bifolk;"
cat backup-pre-upgrade-YYYYMMDD.dump | docker compose exec -T bifolk-db pg_restore -U bifolk -d bifolk -F c

# Checkout previous version
git checkout v1.2.0

# Rebuild and start
docker compose build bifolk-app
docker compose up -d

# Verify
curl -I http://localhost:8000

Migration-Only Rollback

# Rollback a specific app to a known-good migration
docker compose exec bifolk-app python manage.py migrate hives 0003_previous_migration

# Restart
docker compose restart bifolk-app