Version: 1.4 (Current)

Docker

Docker installation

More information on supported platforms and installation guides on the official Docker documentation https://docs.docker.com/engine/install/

Ubuntu

To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions:

Ubuntu Oracular 24.10
Ubuntu Noble 24.04 (LTS)
Ubuntu Jammy 22.04 (LTS)
Ubuntu Focal 20.04 (LTS)

Set the Docker apt repository:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

To install the latest version, run:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify that the installation is successful with:

sudo docker run hello-world

Debian

To install Docker Engine, you need the 64-bit version of one of these Debian versions:

Debian Trixie 13 (testing)
Debian Bookworm 12 (stable)
Debian Bullseye 11 (oldstable)

Set up Docker's apt repository:

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

To install the latest version, run:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify that the installation is successful with:

sudo docker run hello-world

Red Hat

To install Docker Engine, you need a maintained version of one of the following RHEL versions:

RHEL 8
RHEL 9

Set up the repository

Install the dnf-plugins-core package (which provides the commands to manage your DNF repositories) and set up the repository.

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

To install the latest version, run:

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This command installs Docker, but it doesn't start Docker.

Start Docker Engine:

sudo systemctl enable --now docker

Verify that the installation is successful with:

sudo docker run hello-world

Fedora

To install Docker Engine, you need a maintained version of one of the following Fedora versions:

Fedora 42
Fedora 41
Fedora 40

Set up the repository

Install the dnf-plugins-core package (which provides the commands to manage your DNF repositories) and set up the repository.

sudo dnf -y install dnf-plugins-core
sudo dnf-3 config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

To install the latest version, run:

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

This command installs Docker, but it doesn't start Docker.

Start Docker Engine:

sudo systemctl enable --now docker

Verify that the installation is successful with:

sudo docker run hello-world

Windows

Prerequisites:

A 64-bit version of Windows 10 or newer
CPU with virtualization support
WSL 2 enabled

To install WSL on windows run on a cmd

wsl --install

If you have WSL already installed ensure it's updated to WSL 2

wsl --update
wsl --set-default-version 2

Download and Install Docker Desktop from the official website https://docs.docker.com/get-started/get-docker/

Follow the prompts to install Docker Desktop, ensuring "Install required Windows components for WSL 2" is checked.

Restart if needed.

Verify that both Docker and Docker compose are installed with:

docker --version
docker compose version

docker run hello-world

Deploy ToBeAlert

After Docker Engine is installed, deploy ToBeAlert with Docker Compose.

1. Choose an installation directory and prepare host folders

Pick any directory on the host where you will keep docker-compose.yaml and local bind mounts. There is no fixed folder name or path — the examples below use the shell variable INSTALL_PATH; set it to whatever you prefer (for example /opt/tobealert or ~/tobealert).

export INSTALL_PATH=/opt/tobealert   # example only — change to your chosen path

mkdir -p "$INSTALL_PATH/data/backups"
sudo chown -R 1000:1000 "$INSTALL_PATH/data/backups"
sudo chmod -R 775 "$INSTALL_PATH/data/backups"

The backend runs as UID 1000. The bind mount for backups must be writable by that user.

Configuration (/tobealert/config/tobealertd.conf) is created automatically on first start inside the container. You do not need to mount a config volume unless you want to persist edits on the host.

2. Log in to Docker Hub

docker login -u YOUR_USERNAME

3. Create `docker-compose.yaml`

Save the following as docker-compose.yaml inside $INSTALL_PATH (the directory you chose in step 1). Paths in the file such as ./data/backups are relative to that file — they are not tied to a specific host path name.

networks:
  tobealert-network:
    driver: bridge

services:
  tobealert-bbdd:
    image: postgres:17.5-alpine
    container_name: tobealert-bbdd
    environment:
      POSTGRES_USER: tobealert
      POSTGRES_PASSWORD: tobealert
      POSTGRES_DB: tobealert
      TZ: Europe/Madrid
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    # Tuning for a dedicated database host (adjust to the host's RAM; see Management → Diagnostics):
    # shared_buffers ≈ 25 % of RAM, effective_cache_size ≈ 50-75 %, work_mem 16-64 MB, random_page_cost 1.1 on SSD
    command: >
      postgres -c shared_buffers=1GB -c effective_cache_size=3GB -c work_mem=32MB -c maintenance_work_mem=256MB
               -c random_page_cost=1.1 -c shared_preload_libraries=pg_stat_statements
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U tobealert"]
      interval: 2s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - tobealert-network

  tobealert-redis:
    image: redis:latest
    container_name: tobealert-redis
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 2s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    networks:
      - tobealert-network

  tobealert-backend:
    image: tobek8s/tobealert-backend:latest
    container_name: tobealert-backend
    environment:
      ADMIN_USER: tbadmin
      ADMIN_PASSWORD: changeme
      DATABASE_URL: postgres://tobealert:tobealert@tobealert-bbdd:5432/tobealert
      REDIS_HOST: tobealert-redis
      REDIS_PORT: "6379"
      TZ: Europe/Madrid
    ports:
      - "9000:9000"
    volumes:
      - ./data/backups:/tobealert/backups
      - tools_data:/tobealert/tools
      - license_data:/tobealert/license
      - instructions_data:/tobealert/instructions
      - patches_data:/tobealert/patches
    depends_on:
      tobealert-bbdd:
        condition: service_healthy
      tobealert-redis:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - tobealert-network

  tobealert-frontend:
    image: tobek8s/tobealert-frontend:latest
    container_name: tobealert-frontend
    environment:
      BASE_URL: http://localhost
      API_URL: http://localhost:9000
      BACKEND_SERVICE: tobealert-backend
      BACKEND_PORT: "9000"
    ports:
      - "8005:8080"
    depends_on:
      - tobealert-backend
    restart: unless-stopped
    networks:
      - tobealert-network

volumes:
  postgres_data:
  tools_data:
  instructions_data:
  license_data:
  patches_data:

The patches_data volume (/tobealert/patches) keeps signed hotfix bundles across container recreations.

warning

Set ADMIN_PASSWORD before the first backend start. After the bootstrap user exists in the database, changing this env var does not update the password — see Bootstrap / ADMIN_PASSWORD.

4. Environment variables (summary)

Service	Variable	Value in example above
Backend	`ADMIN_USER` / `ADMIN_PASSWORD`	Bootstrap admin
Backend	`DATABASE_URL`	`postgres://tobealert:tobealert@tobealert-bbdd:5432/tobealert`

Database performance

The command: line above shows the PostgreSQL settings worth tuning on a dedicated database host. The defaults of the official image (128 MB shared_buffers, 4 MB work_mem) are meant for small installs. After changing them, run Management → Diagnostics to confirm the server settings probe is green; with pg_stat_statements preloaded, the diagnostics also list the slowest queries. Run CREATE EXTENSION pg_stat_statements; once in the database to enable it.

Full reference: Settings file and environment variables.

5. Start the stack

Run Compose from $INSTALL_PATH (where docker-compose.yaml lives):

cd "$INSTALL_PATH"
docker compose up -d

Check logs (from the same directory):

docker compose logs -f tobealert-backend

Health check:

curl -s http://localhost:9000/api/health

GET /api/health needs no login and answers 200 when the database, Redis and the Celery workers respond, 503 otherwise (JSON body with one entry per component). It is the endpoint to give an external monitor or a Compose healthcheck; GET /api/management/healthcheck still works and feeds the Status page. See External health endpoint.

To let Compose restart or gate on the backend's own health, add a healthcheck to the tobealert-backend service (the image includes curl):

    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:9000/api/health >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Open the UI at http://localhost:8005/tobealert (mapped port 8005 → container 8080).

To publish the same stack at https://your-domain, follow HTTPS and TLS (TLS proxy in front of the frontend, plus SSL_CERT / SSL_KEY on the backend).

6. First start behaviour

On first backend start, the entrypoint:

Copies /tobealert/config/tobealertd.conf.example → /tobealert/config/tobealertd.conf (if missing)
Replaces SECRET_KEY = 'CHANGEME' with a random key
Creates the bootstrap UI user from ADMIN_USER / ADMIN_PASSWORD only if that user does not already exist (later env changes to ADMIN_PASSWORD are ignored — details)

Open the UI and complete License setup — Online (license key) when the host can reach the licensing server, or Offline (license file) on air-gapped sites.

Other platforms

HTTPS and TLS — publish the stack at https://your-domain
Linux — same variables; external PostgreSQL or network_mode: host notes
Windows — same layout; example host paths such as C:/tobealert/...
Kubernetes — manifests; BACKEND_SERVICE = Kubernetes Service name

Docker installation​

Ubuntu​

Set the Docker apt repository:​

To install the latest version, run:​

Verify that the installation is successful with:​

Debian​

Set up Docker's apt repository:​

To install the latest version, run:​

Verify that the installation is successful with:​

Red Hat​

Set up the repository​

To install the latest version, run:​

Start Docker Engine:​

Verify that the installation is successful with:​

Fedora​

Set up the repository​

To install the latest version, run:​

Start Docker Engine:​

Verify that the installation is successful with:​

Windows​

Deploy ToBeAlert​

1. Choose an installation directory and prepare host folders​

2. Log in to Docker Hub​

3. Create docker-compose.yaml​

4. Environment variables (summary)​

5. Start the stack​

6. First start behaviour​

Other platforms​

Docker installation

Ubuntu

Set the Docker apt repository:

To install the latest version, run:

Verify that the installation is successful with:

Debian

Set up Docker's apt repository:

To install the latest version, run:

Verify that the installation is successful with:

Red Hat

Set up the repository

To install the latest version, run:

Start Docker Engine:

Verify that the installation is successful with:

Fedora

Set up the repository

To install the latest version, run:

Start Docker Engine:

Verify that the installation is successful with:

Windows

Deploy ToBeAlert

1. Choose an installation directory and prepare host folders

2. Log in to Docker Hub

3. Create `docker-compose.yaml`

4. Environment variables (summary)

5. Start the stack

6. First start behaviour

Other platforms