Start here

ClusterD Quickstart

Install a minimal single-node ClusterD cluster from Debian packages, let systemd manage the master and agent, and verify that the cluster is ready.

Before you begin

A small cluster for learning and testing.

This guide describes one master and one agent on the same Debian host. It is intended for local development and evaluation, not production high availability.

A supported 64-bit Debian system; the example below uses Debian bookworm
cgroups v2, required by ClusterD from version 1.11.0-0.6.0 onward
Root or sudo access

01 / Install the package

Configure the AVENTER Debian repository.

The AVENTER repository provides the Debian packages for ClusterD. The repository instructions use the aventer-mesos package name and support Debian bullseye, bookworm, and newer published distributions.

sudo apt-get update
sudo apt-get install -y curl software-properties-common
curl https://www.aventer.biz/assets/support_aventer.asc | sudo apt-key add -
sudo add-apt-repository 'deb http://rpm.aventer.biz/Debian/bookworm bookworm main'
sudo apt-get update
sudo apt-get install -y aventer-mesos

If you use a different supported Debian release, replace both bookworm values with its repository codename. See the package repository for the available distributions.

02 / Configure

Set up one local master and agent.

The package installs systemd units named mesos-master.service and mesos-agent.service. Their init wrapper reads options from files in /etc/mesos-master and /etc/mesos-agent.

sudo mkdir -p /etc/mesos-master /etc/mesos-agent

echo 127.0.0.1 | sudo tee /etc/mesos-master/ip
echo /var/lib/mesos | sudo tee /etc/mesos-master/work_dir

echo 127.0.0.1 | sudo tee /etc/mesos-agent/ip
echo 127.0.0.1:5050 | sudo tee /etc/mesos-agent/master
echo /var/lib/mesos | sudo tee /etc/mesos-agent/work_dir

These settings keep the cluster local to the host. For a multi-node or production setup, use the full configuration and operations documentation.

03 / Start with systemd

Enable and start both services.

systemd starts the master and agent, restarts them if necessary, and keeps them running after reboot.

sudo systemctl daemon-reload
sudo systemctl enable --now mesos-master.service
sudo systemctl enable --now mesos-agent.service

Inspect the service state and recent logs if the cluster does not come up:

systemctl status mesos-master.service mesos-agent.service
journalctl -u mesos-master.service -u mesos-agent.service

04 / Verify

Check that the cluster is reachable.

Open the local ClusterD web interface:

http://127.0.0.1:5050

You should see the master and the connected agent. Frameworks can now register with the master and launch tasks against the available resources.

Read the full documentation Download options

05 / ClusterD WebUI

Add the new browser interface.

The new React-based ClusterD WebUI is maintained separately. It provides a live overview of the cluster, agents, frameworks, tasks, resources, and master details, with light and dark themes.

Build it and copy the production files into the directory served by the master:

git clone https://github.com/m3scluster/clusterd-webui
cd clusterd-webui
make build
sudo install -d /usr/share/mesos/webui2
sudo cp -a ui/build/. /usr/share/mesos/webui2/

Tell the master where the WebUI files are located, then restart the master service:

echo /usr/share/mesos/webui2 | sudo tee /etc/mesos-master/webui_dir
sudo systemctl restart mesos-master.service

Open the UI at http://127.0.0.1:5050/#/. The WebUI uses the same ClusterD master and requires the credentials configured for that master when authentication is enabled.

For deployment details, development proxy settings, and the complete feature list, read the ClusterD WebUI documentation on GitHub .