Docker Compose Installation¶

Quick Start¶

Prerequisites: Docker 20.10+ and Docker Compose V2.

Step 1 — Download the compose file¶

curl -LO https://raw.githubusercontent.com/depictio/depictio/stable/docker-compose.yaml

Step 2 — Start¶

docker compose up -d

All services start automatically: MongoDB, Redis, MinIO, backend, viewer, and Celery worker.

Step 3 — Open¶

Service	URL	Credentials
Depictio	http://localhost:5080	(single-user mode, no login)
API docs	http://localhost:8058/docs	—
MinIO console	http://localhost:9001	`minio` / `minio123`

That's it!

Depictio starts in single-user mode by default — no login, no configuration needed.

Exposing to the network?

Single-user mode disables credential enforcement. Before sharing or deploying beyond localhost, switch to multi-user mode and set strong credentials — see Custom credentials below.

Advanced Configuration¶

Everything in this section is optional. The Quick Start defaults work for most users.

Single-user vs Multi-user mode¶

Depictio ships in single-user mode by default: no login, no accounts, one admin user.

Mode	`DEPICTIO_AUTH_SINGLE_USER_MODE`	`DEPICTIO_AUTH_PUBLIC_MODE`	Use case
Single-user (default)	`true`	`false`	Local development, personal use
Multi-user	`false`	`false`	Team deployment with login
Public (read-only)	`false`	`true`	Shared dashboards, no auth required

Switch to multi-user mode and set strong credentials in your .env:

DEPICTIO_AUTH_SINGLE_USER_MODE=false

# Required in multi-user mode — set on first boot
DEPICTIO_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
DEPICTIO_BOOTSTRAP_ADMIN_PASSWORD=changeme

# MinIO password must be ≥ 8 chars and not a known default
DEPICTIO_MINIO_ROOT_PASSWORD=$(openssl rand -base64 12)

Users can then register accounts and log in via the Depictio UI.

Bootstrap is idempotent

The admin account is created only when no non-anonymous admin exists in MongoDB. Changing the bootstrap vars after first boot has no effect.

Expose to the network?

If making Depictio accessible beyond localhost, disable single-user mode and change the MinIO credentials.

Custom Credentials (.env file)¶

To change MinIO credentials or pin a specific version, copy the example file:

cp .env.example .env

Edit .env:

# Application version (default: latest)
DEPICTIO_VERSION=latest

# Admin account — REQUIRED on first boot (all modes)
DEPICTIO_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
DEPICTIO_BOOTSTRAP_ADMIN_PASSWORD=change-me-strong-password-here

# MinIO credentials — REQUIRED, ≥16 chars (enforced at startup from v1.0.0-b1)
DEPICTIO_MINIO_ROOT_USER=myadmin
DEPICTIO_MINIO_ROOT_PASSWORD=change-me-strong-password-here

Bootstrap is idempotent

The admin account is created only on first boot (when no non-anonymous admin exists in MongoDB). Restarting the container or changing the bootstrap vars afterwards has no effect — use the admin UI to manage credentials.

Full reference

Complete env file: .env.complete.example — all 160+ variables with defaults
Configuration Guide: Configuration — common use cases
Full Reference: Environment Reference — all variables

External S3 / Bring Your Own MinIO¶

If you already have a MinIO server or S3-compatible storage, use the dedicated no-minio compose file:

docker compose -f docker-compose/docker-compose.no-minio.yaml up -d

Configure your .env to point to your existing instance:

DEPICTIO_MINIO_ROOT_USER=your-access-key
DEPICTIO_MINIO_ROOT_PASSWORD=your-secret-key
DEPICTIO_MINIO_PUBLIC_URL=https://your-minio-host.example.com
DEPICTIO_MINIO_EXTERNAL_SERVICE=true
# Optional overrides
DEPICTIO_MINIO_EXTERNAL_HOST=your-minio-host.example.com
DEPICTIO_MINIO_EXTERNAL_PORT=9000
DEPICTIO_MINIO_EXTERNAL_PROTOCOL=https

Network Configuration

Set DEPICTIO_MINIO_EXTERNAL_SERVICE=true when MinIO is outside the Docker Compose network.

S3-Compatible Storage

Depictio uses the MinIO client library (S3 API compatible). AWS S3, DigitalOcean Spaces, Backblaze B2, and others may work but have not been officially tested.

Port Configuration¶

Override default ports in .env:

MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001

All default ports:

Service	Default port
Frontend (React viewer)	5080
Backend API	8058
MongoDB	27018
MinIO API	9000
MinIO UI	9001

Development Mode¶

Enable debug logging and hot-reload:

DEPICTIO_DEV_MODE=true docker compose up -d

Or set DEPICTIO_DEV_MODE=true in your .env file.

Background Callbacks (Celery)¶

Depictio uses Celery for asynchronous processing. The depictio-celery-worker container always starts automatically — it is required for the dashboard editor (design mode).

# Configure view-mode behaviour in .env
DEPICTIO_CELERY_ENABLED=true   # false = synchronous view mode (simpler for debugging)

Mode	`DEPICTIO_CELERY_ENABLED`	Behaviour
Design mode (editor)	always on	Non-blocking figure preview — required
View mode	`true`	Async data loading — recommended for production
View mode	`false`	Synchronous — simpler for development

Kubernetes/Helm

Background callbacks are also supported in Kubernetes via the Helm chart (celery.enabled: true by default). See the Kubernetes installation guide.

Managing Services¶

Action	Command
Stop (preserve data)	`docker compose stop`
Stop and remove containers	`docker compose down`
Stop, remove containers and data	`docker compose down -v`
View all logs	`docker compose logs -f`
View one service	`docker compose logs -f depictio-backend`
Check status	`docker compose ps`

Troubleshooting¶

A container fails to start¶

docker compose logs <service_name>

Common causes: port conflict, volume permission error, MongoDB connection failure.

Cannot connect to services¶

Check containers are running: docker compose ps
Confirm you are using the correct ports
Check for firewall rules blocking the connection

Data persistence¶

MongoDB data is stored in ./depictioDB (bind-mount). MinIO data is stored in a named Docker volume (minio_data). Both persist across docker compose down restarts.