Troubleshooting¶

Common gotchas and their solutions. Most of these surface during initial setup or after a Docker restart.

macOS: "Could not find the GDAL library" (Homebrew native libs)¶

Symptom — on macOS, make run / make test / any manage.py command crashes at startup with one of:

django.core.exceptions.ImproperlyConfigured: Could not find the GDAL library
    (tried "gdal", "GDAL", "gdal3.10.0", ...). Is GDAL installed?

OSError: cannot load library 'libgobject-2.0-0': dlopen(libgobject-2.0-0, ...)
    ... ctypes.util.find_library() did not manage to locate a library

Cause — the backend loads several Homebrew-installed native libraries at import time: GDAL and GEOS (GeoDjango / PostGIS) and glib/pango/harfbuzz/fontconfig/cairo (WeasyPrint PDF rendering). These live under $(brew --prefix)/lib (/opt/homebrew/lib on Apple Silicon). A macOS system update can change how dyld / Python's ctypes.util.find_library probe for libraries, after which that directory is no longer searched — so the libs "disappear" even though Homebrew still has them installed. GDAL fails first (it's imported earliest); once it's fixed the same failure resurfaces for WeasyPrint's libgobject.

Why the obvious fixes don't work — DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib fixes it in a bare shell, but not through make: /usr/bin/make and /bin/sh are SIP-protected system binaries, and macOS strips all DYLD_* variables from the environment when a protected binary launches. So exporting DYLD_* in ~/.zshrc or the Makefile is silently dropped before the Django process starts. Django's GDAL_LIBRARY_PATH setting would fix GDAL/GEOS but not WeasyPrint, which has no equivalent knob.

Fix (one symlink, SIP-proof, works everywhere) — expose Homebrew's lib dir on dyld's built-in default fallback path ($HOME/lib), which needs no environment variable and therefore survives SIP for make, subagents, and direct uv run alike:

ln -s "$(brew --prefix)/lib" ~/lib

That single symlink resolves GDAL, GEOS, and all of WeasyPrint's native dependencies at once. To undo it: rm ~/lib.

Geo Data Files¶

The geo app requires two data files in src/geo/data/:

Cities CSV missing¶

Migration 0002_load_cities loads src/geo/data/worldcities.csv if present and otherwise falls back to the bundled 50-city src/geo/fixtures/worldcities.mini.csv. The fallback lives outside src/geo/data/ so a bind mount over that directory cannot hide it. The migration only fails with a FileNotFoundError if neither file exists.

IP2Location database¶

A Celery periodic task downloads a fresh IP2Location database every Monday at 04:00 UTC. It requires the IP2LOCATION_TOKEN environment variable.

# .env
IP2LOCATION_TOKEN=your-token-here

# docker-compose example
volumes:
  - ./src/geo/data:/app/src/geo/data  # must be writable by appuser

Apple Wallet Certificates¶

Apple Wallet pass generation requires three PEM certificate files and several environment variables.

Required environment variables¶

# .env
APPLE_TEAM_IDENTIFIER=YOUR_TEAM_ID
APPLE_WALLET_PASS_TYPE_ID=pass.io.letsrevel.events
APPLE_WALLET_TEAM_ID=YOUR_TEAM_ID
APPLE_WALLET_CERT_PATH=/app/src/certs/pass_certificate.pem
APPLE_WALLET_KEY_PATH=/app/src/certs/pass_key.pem
APPLE_WALLET_KEY_PASSWORD=           # can be empty string
APPLE_WALLET_WWDR_CERT_PATH=/app/src/certs/wwdr.pem

Required certificate files¶

Place these in src/certs/:

chmod 644 src/certs/pass_certificate.pem src/certs/wwdr.pem
chmod 600 src/certs/pass_key.pem  # private key (restrict access)

Docker Permissions¶

The production Docker image runs as a non-root user (appuser). This is the most common source of permission errors.

The appuser setup¶

# From Dockerfile
RUN useradd --create-home --system --shell /bin/bash appuser
# ...
USER appuser

All files copied into the image use --chown=appuser:appuser, but mounted volumes inherit permissions from the host.

Fixing volume permission issues¶

If you see PermissionError or EACCES in logs:

# Find appuser's UID inside the container
docker compose exec web id appuser
# uid=999(appuser) gid=999(appuser)

# Fix host directory ownership
sudo chown -R 999:999 ./src/geo/data ./src/certs

chmod -R a+rw ./src/geo/data ./src/certs

Volumes that need write access¶

Volumes that are read-only¶

External Services¶

Most external services have safe defaults for local development. Here's what actually needs configuration:

Required for any development¶

Required for specific features¶

Feature flags¶

Feature Flags¶

Flags that affect development behavior: