Skip to content

Troubleshooting

Solutions for common Bifolk deployment issues.

Target Audience: System administrators

General Approach

  1. Check logs: docker logs bifolk-app --tail 100
  2. Verify configuration: docker compose config
  3. Run Django check: docker compose exec bifolk-app python manage.py check
  4. Test connectivity: docker compose exec bifolk-db pg_isready -U bifolk

Container Issues

Container Exits Immediately

Check logs for the cause:

docker logs bifolk-app

Common causes:

Error Cause Solution
ImproperlyConfigured Missing or invalid .env Verify .env exists and values are correct
OperationalError: could not connect Database not ready Wait, then docker compose restart bifolk-app
ProgrammingError: relation does not exist Missing migrations docker compose exec bifolk-app python manage.py migrate

Container Restarts Repeatedly

# Check restart count
docker inspect bifolk-app --format '{{.RestartCount}}'

# Check resource usage
docker stats bifolk-app --no-stream

Port conflict:

# Find what is using the port
sudo lsof -i :8000

# Change port in .env if needed
# APP_PORT=8001

Build Fails

# Rebuild without cache
docker compose build --no-cache bifolk-app

Database Issues

Cannot Connect to Database

# Check database container is running
docker ps | grep bifolk-db

# Check database health
docker compose exec bifolk-db pg_isready -U bifolk

# Verify DB_HOST in .env (must be "bifolk-db", not "localhost")
grep DB_HOST .env

# Check Docker network
docker network inspect bifolknet

Authentication Failed

FATAL: password authentication failed for user "bifolk"

The password in .env or secrets/db_password.txt does not match PostgreSQL. Either update the secret file or reset the PostgreSQL password:

# Reset password in PostgreSQL to match your secret
PASS=$(cat secrets/db_password.txt)
echo "ALTER USER bifolk WITH PASSWORD '$PASS';" | \
  docker compose exec -T bifolk-db psql -U postgres

docker compose restart bifolk-app

Database Does Not Exist

docker compose exec bifolk-db psql -U bifolk -d postgres -c "CREATE DATABASE bifolk;"
docker compose exec bifolk-app python manage.py migrate
docker compose restart bifolk-app

Permission Problems

Cannot Read Secret Files

# Run the permissions script
bash scripts/bifolk_set_permissions.sh

# Restart
docker compose restart

Media Upload Fails

# Fix media directory ownership inside the container
docker compose exec bifolk-app chown -R django:django /bifolk/media

SQLite Permission Denied (Development)

# Fix database file permissions
chmod 664 app/db.sqlite3
chmod 775 app/

Configuration Issues

bifolk.json Not Generated

The configuration file is generated at container startup. If missing:

# Check entrypoint logs
docker logs bifolk-app | head -20

# Manually trigger generation
docker compose exec bifolk-app python /bifolk/generate_config.py

# Restart
docker compose restart bifolk-app

ALLOWED_HOSTS Error

DisallowedHost at / - Invalid HTTP_HOST header: 'example.com'

Add your domain to DJANGO_ALLOWED_HOSTS in .env:

DJANGO_ALLOWED_HOSTS=example.com,www.example.com,localhost

Then restart: docker compose restart bifolk-app

Static Files Not Loading

If the web interface shows unstyled HTML:

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

# Restart
docker compose restart bifolk-app

# Clear browser cache (Ctrl+Shift+R)

Email Issues

Emails Not Sending

# Verify email configuration
grep EMAIL .env

# Test sending
docker compose exec bifolk-app python manage.py shell -c "
from django.core.mail import send_mail
send_mail('Test', 'Test message', 'from@example.com', ['to@example.com'])
"

Common fixes:

  • Gmail requires an App Password (not your regular password)
  • Port 587 requires EMAIL_USE_TLS=True, EMAIL_USE_SSL=False
  • Port 465 requires EMAIL_USE_TLS=False, EMAIL_USE_SSL=True — setting both to True causes a connection error
  • When DEBUG=True, emails go to console instead of SMTP

Performance Issues

Slow Response Times

# Check resource usage
docker stats --no-stream

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

# Check for long-running queries
docker compose exec bifolk-db psql -U bifolk -d bifolk -c "
  SELECT pid, now() - query_start AS duration, query
  FROM pg_stat_activity
  WHERE state = 'active' AND now() - query_start > interval '5 seconds';"

Disk Space Full

# Check disk usage
df -h
docker system df

# Clean Docker resources
docker system prune -a -f

Getting Help

When reporting issues, collect the following:

# Application logs
docker logs bifolk-app > bifolk-app.log

# Database logs
docker logs bifolk-db > bifolk-db.log

# Container status
docker ps -a > container-status.txt

# Django check
docker compose exec bifolk-app python manage.py check > django-check.txt

# System info
docker version > system-info.txt
uname -a >> system-info.txt

Note

Always redact secrets and passwords before sharing configuration files.