Docker Local Startup

June 16, 2026 · View on GitHub

This page explains the Docker workflows for contributors. Use it when you are developing the Web UI, debugging the deployment stack, or need the platform services that the Python-only CLI does not require.

Choose a Mode

Mode	Command	Use when
Local infrastructure	`./dev.sh infra` or `.\dev.ps1 infra`	You run the backend and frontend on the host, but want PostgreSQL, Redis, RustFS, mailcatcher, and the code-server proxy in Docker. Recommended for daily development.
Full local stack	`./dev.sh full` or `.\dev.ps1 full`	You want Docker to build and run backend, worker, frontend, and infrastructure from the local source tree. Useful for deployment debugging.
Image deployment	`./start.sh --debug`	You want to run already-published deployment images, with debug ports exposed. Useful for release verification.

Run all commands from the docker/ directory.

Prerequisites

Docker Engine with the Compose plugin (docker compose version)
Enough local disk space for PostgreSQL, Redis, RustFS, backend, frontend, and task-runner images
A writable project home directory for generated user projects

On Linux, the backend mounts /var/run/docker.sock so tasks can launch isolated runtime containers. Make sure your user can access Docker.

Install Docker

This project uses Docker Compose v2 through the docker compose command. Verify the installation after setup:

docker version
docker compose version

Windows: Docker Desktop

Use Docker Desktop for Windows for local development.

Confirm Windows meets Docker Desktop's current system requirements.
Enable WSL 2 on Windows if it is not already enabled.
Download and run Docker Desktop Installer.exe.
Use per-user installation unless your organization requires all-users installation.
When the installer asks for the backend, select Use WSL 2 instead of Hyper-V.
Start Docker Desktop from the Start menu and accept the Docker Desktop terms.
Open PowerShell and verify:

docker version
docker compose version

For this project, keep Docker Desktop running while using .\dev.ps1 .... Use Linux containers through WSL 2; Windows containers are not supported by the local compose stack.

Docker Desktop licensing depends on your organization type and size. Check Docker's current subscription terms on the official install page before using it in a company environment.

macOS: Docker Desktop

Install Docker Desktop for Mac, start Docker Desktop from /Applications, accept the Docker Desktop terms, and verify:

docker version
docker compose version

Linux: Docker Engine

Install Docker Engine for your distribution, then install the Docker Compose plugin if it is not included by your package source.

After installation, make sure your shell can access Docker:

docker version
docker compose version

If docker version fails with a permission error, either run Docker commands with sudo or follow Docker's post-installation steps for non-root access.

Create `.env`

Copy the local example and edit required values:

cd docker
cp .env.develop.local.example .env

Windows PowerShell:

cd docker
Copy-Item .env.develop.local.example .env

Set these values before starting services:

Variable	Purpose
`SECRET_KEY`	Application secret. Generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"`.
`PROVIDER_ENCRYPTION_KEY`	Stable encryption key for stored provider credentials. Generate it the same way and do not rotate it casually.
`FIRST_SUPERUSER` / `FIRST_SUPERUSER_PASSWORD`	Initial administrator account.
`POSTGRES_PASSWORD`	PostgreSQL password.
`REDIS_PASSWORD`	Redis password.
`RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY`	RustFS object storage credentials.
`HOST_PROJECT_HOME` / `DOCKER_PROJECT_HOME`	Host and container project-home paths. For local debugging they should point to the same absolute path.

For host-run backend development, keep the service endpoints pointed at localhost:

POSTGRES_SERVER=localhost
REDIS_HOST=localhost
RUSTFS_ENDPOINT=http://localhost:9000
AUTH_BACKEND_URL=http://host.docker.internal:8000
FRONTEND_HOST=http://localhost:5173
CHAT_TUNE_CONTAINER_NETWORK=false

Local Infrastructure Mode

Start only the infrastructure services:

cd docker
./dev.sh infra

Windows PowerShell:

cd docker
.\dev.ps1 infra

This uses compose.yml plus compose.override.yml. The override exposes infrastructure ports and disables the application containers so you can run backend and frontend directly on the host.

Exposed services:

Service	URL / port
PostgreSQL	`localhost:5432`
Redis	`localhost:6379`
RustFS API	`http://localhost:9000`
RustFS console	`http://localhost:9001`
Adminer	`http://localhost:8080`
Mailcatcher UI	`http://localhost:1081`
Mailcatcher SMTP	`localhost:1025`
Code-server proxy	`http://localhost:8083`

Then start the backend on the host:

cd ../src/backend
uv sync
uv run alembic upgrade head
uv run fastapi dev app/main.py

Start a worker in another shell when testing async tasks:

cd ../src/backend
uv run celery -A app.core.celery worker --loglevel=info --concurrency=2

Start the frontend:

cd ../src/frontend
bun install
bun run dev

The backend reads ../../docker/.env by default, so keep running backend commands from src/backend.

Full Local Stack Mode

Build and run the full stack from local source with debug ports:

cd docker
./dev.sh full

Windows PowerShell:

cd docker
.\dev.ps1 full

This uses compose.yml plus compose.deploy.debug.yml and enables the debug profile. It runs backend, worker, frontend, infrastructure, Adminer, and Flower in Docker.

Useful endpoints:

Service	URL / port
Frontend	`http://localhost:${FRONTEND_PORT}`; default from `.env` is `18041`
Backend API	`http://localhost:8000`
Adminer	`http://localhost:8080`
Flower	`http://localhost:5555`
RustFS console	`http://localhost:9001`

Tail logs:

./dev.sh logs
./dev.sh logs backend worker

Windows PowerShell:

.\dev.ps1 logs
.\dev.ps1 logs backend worker

Show service status:

./dev.sh ps

Windows PowerShell:

.\dev.ps1 ps

Image Deployment Debug Mode

Use start.sh when you want deployment images instead of local builds:

cd docker
TAG=v1.0.0 ./start.sh start --debug

--debug includes compose.deploy.debug.yml, enables the debug profile, and exposes PostgreSQL, Redis, RustFS, backend, Adminer, and Flower ports.

Stop and Clean Up

Stop containers without removing them:

./dev.sh stop

Windows PowerShell:

.\dev.ps1 stop

Remove compose containers and orphans while keeping bind-mounted data under docker/app-data/:

./dev.sh remove

Windows PowerShell:

.\dev.ps1 remove

For image-based deployments:

./start.sh stop --debug
./start.sh remove --debug

Troubleshooting

Symptom	Likely cause	Fix
`Missing docker/.env`	The local env file was not created	Run `cp .env.develop.local.example .env` in `docker/` and edit required values.
Compose reports `Variable not set`	Required secrets are still blank	Fill every required value in `.env`.
Backend cannot connect to DB or Redis	`.env` still points to Docker service names while backend runs on the host	Use `POSTGRES_SERVER=localhost` and `REDIS_HOST=localhost`.
Stored provider credentials disappear after restart	`PROVIDER_ENCRYPTION_KEY` changed or was empty	Set a stable `PROVIDER_ENCRYPTION_KEY` and keep it unchanged for that database.
Task containers cannot access generated files	`HOST_PROJECT_HOME` and `DOCKER_PROJECT_HOME` do not match the local path expectation	Use the same absolute path for local debugging and ensure it exists.
Ports are already in use	Another service is using the debug port	Change the relevant port in `.env` or stop the conflicting process.