# Installation Guide

TIP

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

# Prerequisites

# Hardware

Cytomine is a set of multithreaded tools. A minimum of 8 CPU cores is required. The number of required cores is proportional to the expected activity. The more you want to support active users, the more you need cores. For a server-setup configuration, we recommend to use at least 16 cores.

Regarding memory, a minimum of 8 GB is required, but we recommend at least 16 GB.

Cytomine installation requires about 15GB. You need to provide enough space to store your images (depends on their size). If database backup is enabled, extra-space has to be provided.

# Software

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

# Running App in Cytomine

WARNING

In previous versions, MicroK8s was required for the installation. This is no longer the case.

Cytomine now uses K3s, which is deployed automatically via Docker Compose. No manual installation or configuration is required anymore.

If you previously installed MicroK8s only for Cytomine, you can safely remove it using the following command:

sudo snap remove microk8s

# Installation

This installation procedure is intended for desktop or laptop computers running Debian-based Linux operating systems.

It is expected to have root permissions (sudo privileges in Debian/Ubuntu).

Clone the cytomine repository:

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

Go into the cloned folder:
```
cd cytomine
```
1
Launch cytomine:
```
sudo docker compose up -d
```
1
Once all services are up and running, Cytomine is ready to be used:
- If you have kept the default values your Cytomine is now available on http://127.0.0.1/ (opens new window).
- A default admin account is created with the password password

TIP

If you encounter any issues during installation, refer to the troubleshooting section first.

# Upgrade Cytomine

To upgrade Cytomine to the latest version:

Fetch the latest changes in the cytomine repository:
```
cd cytomine
git pull
```
1
2
Fetch the latest images of each services in Cytomine:
```
sudo docker compose pull
```
1
Restart cytomine with the latest version:
```
sudo docker compose up -d
```
1

# Stop Cytomine

To stop your Cytomine instance:

sudo docker compose down

The server will be stopped, but the data, including databases and images, will be preserved.

# What's Next?

For additional setup options, see the Configuration section.

Configuration →