Useful Commands¶

Quick reference for common Bifolk development and administration commands.

Target Audience: Developers, system administrators

Environment Setup¶

# Set Docker Compose context for development
export COMPOSE_FILE=docker/compose-developement/docker-compose.yml
export COMPOSE_PROJECT_NAME=bifolk

# Activate Python virtual environment (for host-side tools)
source venv/bin/activate

Container Management¶

# Start services
docker compose up -d

# Stop services
docker compose stop

# Remove containers and networks
docker compose down

# Rebuild and start
docker compose down && docker compose build && docker compose up -d

# View logs (follow mode)
docker compose logs -f

# Check container status
docker compose ps

Django Management¶

Note

All docker compose exec commands targeting bifolk-app must include -u bifolk. The container runs with cap_drop: ALL, which removes the DAC_OVERRIDE capability. Without it, the default root exec user cannot read bifolk.json (permissions: 600, owner: bifolk).

# Run migrations
docker compose exec -u bifolk bifolk-app python manage.py migrate

# Create migrations
docker compose exec -u bifolk bifolk-app python manage.py makemigrations

# Show migration status
docker compose exec -u bifolk bifolk-app python manage.py showmigrations

# Create superuser
docker compose exec -u bifolk bifolk-app python manage.py createsuperuser

# Collect static files
docker compose exec -u bifolk bifolk-app python manage.py collectstatic --no-input

# Django system check
docker compose exec -u bifolk bifolk-app python manage.py check

# Load sample data
docker compose exec -u bifolk bifolk-app python manage.py load_sample_data

# Clear expired sessions
docker compose exec -u bifolk bifolk-app python manage.py clearsessions

Organization User Management¶

# Add a user to an organization as a member (default role)
docker compose exec -u bifolk bifolk-app python manage.py set_user_role_in_org john 3

# Add a user with a specific role (owner, admin, member, viewer)
docker compose exec -u bifolk bifolk-app python manage.py set_user_role_in_org john 3 --role admin

# Look up organization by name instead of ID
docker compose exec -u bifolk bifolk-app python manage.py set_user_role_in_org john "Maria's Beekeeping"

# Update an existing user's role
docker compose exec -u bifolk bifolk-app python manage.py set_user_role_in_org john 3 --role viewer

# Remove a user from an organization
docker compose exec -u bifolk bifolk-app python manage.py set_user_role_in_org john 3 --remove

Testing¶

# Run full test suite (optimized settings)
docker compose exec -u bifolk bifolk-app bash -c \
  "DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test"

# Run tests for a specific app
docker compose exec -u bifolk bifolk-app bash -c \
  "DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test hives"

# Run a specific test class
docker compose exec -u bifolk bifolk-app bash -c \
  "DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test hives.tests.test_batch_models.BatchModelTests"

# Stop on first failure
docker compose exec -u bifolk bifolk-app bash -c \
  "DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test --failfast"

# Verbose output
docker compose exec -u bifolk bifolk-app bash -c \
  "DJANGO_SETTINGS_MODULE=bifolk.settings_test python manage.py test -v 2"

Tip

Use bifolk.settings_test for faster test execution (optimized password hashing, in-memory database). See app/bifolk/settings_test.py for details.

Type Checking¶

# From host with venv activated
mypy app/ --exclude migrations --ignore-missing-imports

Database Operations¶

SQLite (Development)¶

# Access SQLite shell
docker compose exec -u bifolk bifolk-app sqlite3 /bifolk/db/db.sqlite3

# Common SQLite commands
# .tables                    - List all tables
# .schema <table_name>       - Show table schema
# SELECT * FROM auth_user;   - Query users
# .quit                      - Exit

PostgreSQL (Production)¶

# Access PostgreSQL shell
docker compose exec bifolk-db psql -U bifolk -d bifolk

# Database size
docker compose exec bifolk-db psql -U bifolk -d bifolk -c \
  "SELECT pg_size_pretty(pg_database_size('bifolk'));"

# Vacuum and analyze
docker compose exec bifolk-db psql -U bifolk -d bifolk -c "VACUUM ANALYZE;"

# Quick backup
docker compose exec bifolk-db pg_dump -U bifolk bifolk > backup-$(date +%Y%m%d).sql

Translations¶

# Generate translation messages
cd app && python manage.py makemessages -l de --ignore=venv

# Compile translations
cd app && python manage.py compilemessages -l de

# Check translation coverage
python scripts/translation/check_translations.py

Migration Scripts¶

# Check for pending migrations (host with venv)
bash scripts/check_migrations.sh

# Generate new migrations (host with venv)
bash scripts/generate_migrations.sh

# Set file permissions
bash scripts/bifolk_set_permissions.sh

Vendor Libraries¶

Frontend libraries (Bootstrap, Chart.js, Leaflet, etc.) are committed directly to app/home/static/vendor/ — no Node.js or npm install required. Renovate Bot monitors package.json for new versions and opens a merge request when one is available.

# Check current versions vs latest on npm
python3 scripts/update_vendor.py --check

# Update a single library
python3 scripts/update_vendor.py bootstrap 5.3.9

# Sync all libraries to the versions in package.json
python3 scripts/update_vendor.py --sync

Workflow when Renovate Bot opens a merge request:

Review the library changelog
Run python3 scripts/update_vendor.py <library> <version>
The script downloads files, removes the old directory, and updates all templates
Commit with chore(deps): update <library> to <version>
Close the Renovate merge request (the commit already bumps package.json)

Docker Compose Configurations¶

Directory	Database	Purpose
`docker/compose-developement/`	SQLite	Local development
`docker/compose-postgres/`	PostgreSQL	Production-like testing

Switching Configurations¶

# Development (default)
export COMPOSE_FILE=docker/compose-developement/docker-compose.yml

# PostgreSQL
export COMPOSE_FILE=docker/compose-postgres/docker-compose.yml

# Then use docker compose as usual
docker compose up -d

Useful One-Liners¶

# Count pending migrations
docker compose exec -u bifolk bifolk-app python manage.py showmigrations | grep "\[ \]" | wc -l

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

# List installed packages
docker compose exec -u bifolk bifolk-app pip list

# Quick SQLite backup (development)
docker cp bifolk-app:/bifolk/db/db.sqlite3 ./backup/db-$(date +%Y%m%d).sqlite3

# Restart and follow logs
docker restart bifolk-app && docker logs bifolk-app -f

# Check all Bifolk container health
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | grep bifolk