# Local Installation — All in Docker Compose

TIP

If you experience any issues, please describe your problem precisely in our ticket system on Github. (opens new window)

This guide describes how to run Cytomine locally with all services deployed as Docker containers using the root compose.yaml. This is the simplest local deployment: no Kubernetes knowledge required, everything is managed by Docker Compose.

A k3s container is included automatically to support App Engine task scheduling; it runs as a sidecar and does not require manual configuration.

# Prerequisites

# Hardware

Minimum 8 CPU cores (16+ recommended for multi-user workloads)
Minimum 8 GB RAM (16 GB recommended)
At least 15 GB of free disk space for images and databases

WARNING

The disk on which Docker is installed must not exceed 89% utilisation. Insufficient free space may cause build failures or unstable runtime behaviour.

Check disk usage with:

df -h

# Software

Linux operating system (Ubuntu, Debian, etc.)
Docker Engine (opens new window) v20.10+
Docker Compose (opens new window) v2.0+
Git (opens new window) v2.0+

# Installation

Clone the Cytomine repository:

git clone https://github.com/cytomine/cytomine.git
cd cytomine

1
2

Start all services:
```
docker compose up -d
```
1
First startup takes around 10 minutes to pull all Docker images.
Cytomine is ready when all containers are healthy. Access the UI at:
- Web UI: http://127.0.0.1/ (opens new window)
- Core API: http://127.0.0.1:8080 (opens new window)
- PIMS (image server): http://127.0.0.1:5001 (opens new window)
- IAM (identity): http://127.0.0.1:8070 (opens new window)
- App Engine: http://127.0.0.1:8082 (opens new window)
Default admin credentials: username admin, password password.

TIP

If you encounter issues during startup, refer to the troubleshooting guide.

# Services and Ports

Service	Port	Description
`web-ui`	80	Web user interface
`core`	8080	Main Cytomine API server
`pims`	5001	Image server (PIMS)
`iam`	8070	Identity and access management (Keycloak)
`app-engine`	8082	Algorithm / task runner
`cbir`	6000	Content-based image retrieval
`sam`	8000	Segment Anything Model service
`repository`	8081	Artifact repository
`postgis`	5432	Main PostgreSQL database
`mongo`	27017	Activity / metadata database
`app-engine-db`	5433	App Engine PostgreSQL database
`registry`	5000	Docker image registry for tasks
`k3s`	6443	Kubernetes API (used by App Engine)

# Data Persistence

All persistent data is managed through Docker volumes, except for images and model weights, which are stored under ./data/ by default. You can override this location by setting DATA_PATH before starting:

DATA_PATH=/mnt/data docker compose up -d

Images to import can be placed in a dataset directory. Override with IMPORT_PATH:

IMPORT_PATH=/path/to/slides docker compose up -d

# Building Images Locally

A compose.override.yaml file is provided to build Cytomine service images directly from source instead of pulling them from the registry. This is useful for development:

docker compose up -d --build  # automatically merges compose.override.yaml if present

The override file adds build contexts for: web-ui, pims, iam, app-engine, core, cbir, sam, and repository.

To pull pre-built images instead (ignoring the override):

docker compose -f compose.yaml up -d

# Upgrade Cytomine

Pull the latest repository changes:
```
git pull
```
1
Pull the latest Docker images:
```
docker compose pull
```
1
Restart with the new images:
```
docker compose up -d
```
1

# Stop Cytomine

docker compose down

Data and databases are preserved. To also remove volumes (destructive — deletes all data):

docker compose down -v

# What's Next?

For additional setup options, see the Configuration section.

Configuration →