Docker Compose

Use this guide to start Litefuse from the single-node Docker Compose bundle. The bundle runs Litefuse Web, Litefuse Worker, Postgres, Redis, MinIO, and Doris on the same host.

Prerequisites

• Docker Engine, Docker Desktop, or OrbStack
• Docker Compose v2
• Free ports: 3000, 3030, 5432, 16379, 19090, 19091, 8030, 9030, 9010, 8040, 8060, 9050, 9060

On Apple Silicon machines, Docker may show a linux/amd64 image platform warning. This is a Docker platform notice and does not mean startup failed.

Start Litefuse

Open the directory that contains the self-hosting bundle and run:

bash start.sh

If you are one directory above the bundle:

cd litefuse && bash start.sh

The first run creates a .env file automatically if it does not exist. The generated file includes secrets for authentication, encryption, Postgres, Redis, and MinIO.

The bundled Compose file uses the litefuse/litefuse-web:26.0.0 and litefuse/litefuse-worker:26.0.0 images and runs them with platform: linux/amd64.

Open the Application

After startup, open:

http://localhost:3000

Check the public health endpoint:

curl http://localhost:3000/api/public/health

Expected response:

{"status":"OK","version":"26.0.0"}

Components

Default Docker networks:

• litefuse_default: 10.200.0.0/24
• litefuse_doris_internal: 172.30.0.0/24

Environment Variables

To configure values manually, copy the template first:

cp .env.example .env

Then edit .env and start Litefuse:

bash start.sh

The startup script auto-generates these values when .env is missing:

• NEXTAUTH_SECRET
• SALT
• ENCRYPTION_KEY
• POSTGRES_PASSWORD
• REDIS_AUTH
• MINIO_ROOT_PASSWORD

The application containers use LITEFUSE_* environment variables for Litefuse-specific features:

• LITEFUSE_ENABLE_EXPERIMENTAL_FEATURES
• LITEFUSE_INIT_ORG_ID
• LITEFUSE_INIT_ORG_NAME
• LITEFUSE_INIT_PROJECT_ID
• LITEFUSE_INIT_PROJECT_NAME
• LITEFUSE_INIT_PROJECT_PUBLIC_KEY
• LITEFUSE_INIT_PROJECT_SECRET_KEY
• LITEFUSE_INIT_USER_EMAIL
• LITEFUSE_INIT_USER_NAME
• LITEFUSE_INIT_USER_PASSWORD
• LITEFUSE_ANALYTICS_BACKEND
• LITEFUSE_AUTO_DORIS_MIGRATION_DISABLED
• LITEFUSE_ENABLE_BACKGROUND_MIGRATIONS

The worker also enables S3 batch exports by default:

• LITEFUSE_S3_BATCH_EXPORT_ENABLED=true
• LITEFUSE_S3_BATCH_EXPORT_BUCKET=litefuse
• LITEFUSE_S3_BATCH_EXPORT_PREFIX=exports/
• LITEFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT=http://localhost:19090

ClickHouse compatibility variables remain present, but ClickHouse migrations are disabled because this Compose deployment uses Doris as the analytics backend.

Common Commands

Check service status:

docker compose --env-file .env -f docker-compose.yml ps

Tail logs:

docker compose --env-file .env -f docker-compose.yml logs -f

Stop services while keeping persistent data:

bash stop.sh

Restart services:

bash start.sh

Remove containers, networks, and all volumes:

docker compose --env-file .env -f docker-compose.yml down -v

down -v deletes persistent Postgres, MinIO, and Doris data. Use it only when you no longer need the existing data.

Upgrade

Pull images:

docker compose --env-file .env -f docker-compose.yml pull

Restart Litefuse:

bash start.sh

Backup

Back up Postgres metadata:

docker exec litefuse-postgres pg_dump -U postgres postgres > litefuse-postgres.sql

Persistent data is stored in these Docker volumes:

• litefuse_postgres_data
• litefuse_minio_data
• litefuse_doris_fe_meta
• litefuse_doris_be_storage

Troubleshooting

Network Subnet Conflict

Example error:

invalid pool request: Pool overlaps with other one on this address space

This means an existing Docker network already uses 10.200.0.0/24 or 172.30.0.0/24.

Inspect Docker networks:

docker network ls
docker network inspect <network-name> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

If the old network is not needed, remove it:

docker network rm <network-name>

If the old network must remain, update networks.*.ipam.config.subnet and gateway in docker-compose.yml.

Container Name Conflict

Example error:

Conflict. The container name "/litefuse-doris" is already in use

Find the conflicting container:

docker ps -a --filter name='^/litefuse-doris$'

If the old container is not needed, remove it:

docker rm -f litefuse-doris

Doris Starts Slowly or Becomes Unhealthy

Doris may take time on first boot. Check logs:

docker logs --tail 200 litefuse-doris

If you see proxy-related errors, confirm that the host or Docker runtime is not injecting proxy variables such as http_proxy or https_proxy into the Doris container.

Web or Worker Restarts

Check logs:

docker logs --tail 200 litefuse-web
docker logs --tail 200 litefuse-worker

After changing .env, recreate the web and worker containers:

docker compose --env-file .env -f docker-compose.yml up -d --force-recreate litefuse-web litefuse-worker