Docker-Only Development Environment

As an alternative to running Django and Celery on the host, you can run the full stack inside Docker. This requires only Docker — no local Python or Node installation needed.

Prerequisites

Docker and Docker Compose

Setup

Clone the repository

git clone https://github.com/dimagi/open-chat-studio.git
cd open-chat-studio

Create your .env file
```
cp .env.example .env
```
Edit .env and set at minimum SECRET_KEY. The DATABASE_URL and REDIS_URL values in .env are ignored when running via Docker Compose — those are overridden by the compose file to use the container service names.
Build the images
```
docker compose build
```
Start everything
```
docker compose up
```
On first start, Docker Compose will: - Start PostgreSQL and wait until it is healthy - Start Redis - Run python manage.py migrate (the migrate service exits once complete) - Start the Django dev server on http://localhost:8000 - Start a Celery worker and Celery Beat scheduler

Create a superuser

In a separate terminal:

docker compose run --rm web python manage.py createsuperuser

Services

Service	Description
`db`	PostgreSQL with pgvector extension
`redis`	Redis (used as Celery broker and result backend)
`migrate`	Runs `manage.py migrate` on startup, then exits
`web`	Django dev server with auto-reload (`runserver`)
`celery_worker`	Celery worker for background tasks
`celery_beat`	Celery Beat scheduler (uses `django_celery_beat` database scheduler)

Useful commands

Run a management command:

docker compose run --rm web python manage.py <command>

View logs for a specific service:

docker compose logs -f web
docker compose logs -f celery_worker

Rebuild after dependency changes (pyproject.toml / uv.lock):

docker compose build
docker compose up

Stop all services and remove containers:

docker compose down

Troubleshooting

`type "halfvec" does not exist` during migrations

This error means the pgvector extension in your PostgreSQL container is too old. The halfvec type requires pgvector ≥ 0.7.0.

Cause: Your locally cached pgvector/pgvector:pg16 Docker image predates pgvector 0.7.0.

Fix (fresh setup — no data to keep):

docker compose down -v      # removes containers and volumes
docker compose pull db       # fetch the latest pgvector image
docker compose up            # reinitialise and re-run migrations

Fix (existing data to preserve):

docker compose pull db
docker compose up -d --force-recreate db
docker compose exec db psql -U postgres -d open_chat_studio -c "ALTER EXTENSION vector UPDATE;"
docker compose run --rm migrate

Database `open_chat_studio` does not exist

PostgreSQL only creates the database named in POSTGRES_DB when initialising a fresh data volume. If a postgres_data volume already exists from a previous run without the database, you will see this error.

Fix:

docker compose exec db createdb -U postgres open_chat_studio
docker compose run --rm migrate

Or to start completely fresh (deletes all data):

docker compose down -v
docker compose up

Next: Common Development Tasks