Skip to content

FAQ & Troubleshooting

This guide is for the local Kohakku development stack.

Quick Triage

Start here before chasing a specific symptom:

docker compose ps
docker compose logs --tail=100 controller celery-worker celery-beat dispatcher postgres redis minio minio-init
make help

Docker Services Won't Start

Symptom: docker compose up -d --build fails, a service restarts in a loop, or Docker reports "port is already allocated".

Diagnose:

docker compose ps
lsof -nP -iTCP -sTCP:LISTEN | egrep ':(8000|8080|5432|6379|9000|9001|8088)\b'
docker system df
docker compose logs --tail=100

Fix:

docker compose down --remove-orphans
docker system prune -f

If local data is disposable, reset the stack completely:

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

Warning

docker compose down -v deletes local Postgres and MinIO data.

Database Migrations Fail

Symptom: make migrate fails, dispatcher-migrate exits non-zero, or schema errors appear.

Diagnose:

docker compose logs postgres controller dispatcher-migrate
docker compose exec -T controller python manage.py showmigrations
docker compose run --rm dispatcher-migrate \
  postgres://postgres:postgres@postgres:5432/kohakku-dispatcher?sslmode=disable status

Fix:

make migrate
docker compose up dispatcher-migrate

If the schema is badly drifted and local data does not matter:

docker compose down -v
docker compose up -d --build
make migrate
make seed

Note

docker/postgres-init/init.sql only runs the first time the Postgres volume is created.

Celery Is Not Picking Up Tasks

Symptom: Controller actions queue work but nothing executes. celery-worker stays quiet.

Diagnose:

docker compose ps celery-worker celery-beat redis
docker compose logs --tail=100 celery-worker celery-beat controller
docker compose exec redis redis-cli -n 0 LLEN celery
docker compose exec -T controller python manage.py shell -c \
  "from django.conf import settings; print(settings.CELERY_BROKER_URL)"

Fix:

docker compose up -d redis celery-worker celery-beat
docker compose restart celery-worker celery-beat controller
  • In Docker Compose, the broker should resolve as redis://redis:6379/0
  • The worker starts with -Q celery, so only the celery queue is consumed by default
  • If you change broker settings, restart the controller and both Celery services

Redis Connection Refused

Symptom: Controller, Celery, or Dispatcher logs show Redis connection errors.

Diagnose:

docker compose ps redis
docker compose logs --tail=100 redis
docker compose exec redis redis-cli ping

Fix:

  • Inside Docker Compose: use hostname redis
  • From the host machine: use localhost
  • Keep the DB split consistent:
DB Usage
redis://.../0 Celery broker
redis://.../1 Cache / sessions
redis://.../2 Dispatcher Redis 
docker compose up -d redis controller celery-worker celery-beat dispatcher

Tests Pass Locally but Fail in CI

Symptom: Tests pass in your shell but fail in GitHub Actions.

Key differences:

  • Controller CI talks to Postgres on localhost:5432 and Redis on localhost:6379
  • Dispatcher CI talks to Postgres on localhost:5438
  • Root Docker Compose uses postgres and redis as container hostnames

Reproduce the CI environment:

cd controller
DJANGO_SECRET_KEY=ci-test-secret-key \
DJANGO_DEBUG=true \
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1 \
POSTGRES_DB=kohakku-controller \
POSTGRES_USER=dbadmin \
POSTGRES_PASSWORD=Password123 \
POSTGRES_HOST=localhost \
POSTGRES_PORT=5432 \
REDIS_URL=redis://localhost:6379/1 \
CELERY_BROKER=redis://localhost:6379/0 \
CELERY_BACKEND=redis://localhost:6379/0 \
python -m pytest --tb=short -q

cd dispatcher
DATABASE_URL=postgres://postgres:postgres@localhost:5438/kohakku-dispatcher?sslmode=disable \
go test ./... -v -count=1

Do not depend on pre-seeded local data in tests.

MinIO Access Errors

Symptom: Skill upload or object storage calls fail. MinIO is up but the bucket is missing.

Diagnose:

docker compose ps minio minio-init controller
docker compose logs --tail=100 minio minio-init controller
curl -f http://localhost:9000/minio/health/live

Fix:

docker compose up minio-init
docker compose restart controller
  • Expected bucket name: kohakku
  • Default dev credentials: minioadmin / minioadmin
  • The root compose file sets USE_S3=true, so the controller expects object storage in local dev

Common Questions

What command should I run first when something looks wrong?

docker compose ps then docker compose logs --tail=100 ... for the affected services.

Can I safely reset my local state?

Yes, with docker compose down -v. This deletes local Postgres and MinIO data.

Why do some settings use redis or postgres and others use localhost?

Inside Docker Compose, services talk to each other by service name. From your host shell or CI service containers, use localhost.

Why does the controller wait on MinIO in local dev?

The root compose stack enables S3-compatible storage with USE_S3=true and waits for minio-init to create the kohakku bucket.

Where should I look for CI truth?

The GitHub Actions workflow files in .github/workflows/ are the source of truth for the CI environment.