Quickstart: SelfHeal v1.0.9

Get from a fresh Linux host to a running SelfHeal UI and valid license in a few steps.

1. Prepare a SelfHeal host

• 64-bit Linux (Ubuntu 20.04+ recommended).
• systemd-based distro (for services).
• SSH access as a sudo-capable user.
• Outbound internet for OpenAI (or compatible) API.

2. Kafka options

SelfHeal uses Kafka to ingest alerts. You can either point it to an existing Kafka cluster, or spin up a single-node lab broker using the helper script.

Option A: Use your existing Kafka

If your organisation already runs Kafka, set the following in /etc/selfheal/selfheal.env to point SelfHeal at it:

KAFKA_BOOTSTRAP=<your-kafka-bootstrap:9092>
KAFKA_BOOTSTRAP_SERVERS=<your-kafka-bootstrap:9092>

# Topics SelfHeal expects
KAFKA_INCOMING_TOPIC=selfheal.alerts.raw.generic
ALERTS_TOPIC=selfheal.alerts.normalized
ACTION_REVIEW_TOPIC=actions-review
ALERTS_DLQ_TOPIC=alerts-dlq

Ask your Kafka/SRE team to create these topics if they do not exist, or adjust the topic names above to match your internal standards.

Option B: Single-node Kafka (lab only)

If you just want to try SelfHeal on a single VM and do not have Kafka yet, you can use the lab helper script selfheal-setup-kafka.sh. This is not a production-grade Kafka setup.

cd ~
curl -fSL https://ganges.app/selfheal/selfheal-setup-kafka.sh -o selfheal-setup-kafka.sh
chmod +x selfheal-setup-kafka.sh
./selfheal-setup-kafka.sh

The script will:

• Download Kafka (KRaft mode, no ZooKeeper).
• Start a single-node broker on localhost:9092.
• Create the required topics: selfheal.alerts.raw.generic, selfheal.alerts.normalized, actions-review, alerts-dlq.

Then set these values in /etc/selfheal/selfheal.env:

KAFKA_BOOTSTRAP=localhost:9092
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
KAFKA_INCOMING_TOPIC=selfheal.alerts.raw.generic
ALERTS_TOPIC=selfheal.alerts.normalized
ACTION_REVIEW_TOPIC=actions-review
ALERTS_DLQ_TOPIC=alerts-dlq

3. Download SelfHeal

From your SelfHeal host, download the tarball from the Ganges portal:

# On the SelfHeal host
curl -fSL https://ganges.app/selfheal/download -o selfheal-1.0.9.tar.gz

mkdir selfheal-install
tar xzf selfheal-1.0.9.tar.gz -C selfheal-install --strip-components=1
cd selfheal-install

4. Run the installer

The installer will install dependencies, copy files into /opt/selfheal, create /etc/selfheal/selfheal.env (if needed), and configure systemd and nginx.

# Still on the SelfHeal host
sudo ./install-selfheal.sh

5. Edit the env file

Open the env file and set the minimum required options:

sudo nano /etc/selfheal/selfheal.env

• OPENAI_API_KEY your real OpenAI or compatible API key.
• DRY_RUN / SELFHEAL_DRY_RUN set to true / 1 for lab mode, or false / 0 to allow real actions on allowlisted hosts.
• SELFHEAL_MODE start with advisor; later try ai_single or ai_loop.
• ALERTS_DB_PATH default /opt/selfheal/rules/rules.db is fine for most setups.
• KAFKA_BOOTSTRAP / KAFKA_BOOTSTRAP_SERVERS as set in step 2 (existing or lab Kafka).

6. Create dashboard login

nginx uses HTTP basic auth. Create an admin user:

sudo htpasswd -c /etc/selfheal/htpasswd selfheal_admin
sudo systemctl reload nginx

7. Verify services

systemctl status selfheal-ui selfheal-action

Then open the dashboard in your browser:

http://<selfheal-host>/

Log in with the username and password you set with htpasswd.

8. Generate a license request

On the SelfHeal host, generate a request code that identifies this cluster:

cd /opt/selfheal
python3 -m licensing.fingerprint > request_code.txt
cat request_code.txt

9. Use Ganges portal to get a license

1. Open the Ganges portal in your browser:
   https://ganges.app/
2. Go to /signup and create an account (magic link to your email).
3. After sign-in, go to /selfheal/license.
4. Paste the contents of request_code.txt.
5. Choose a plan: Free, Freemium, Premium, or Enterprise.
6. Click oeGenerate to get license.json and download it.

10. Upload the license to SelfHeal

Copy license.json to the SelfHeal host and apply it:

# On the SelfHeal host, where license.json is present
curl -s -X POST http://<selfheal-host>:8010/license \
 -H 'content-type: application/json' \
 --data-binary @license.json

curl -s http://<selfheal-host>:8010/license/status | jq

Once the status endpoint shows valid, SelfHeal is licensed and ready.

11. Next steps

• Wire your alerting system (Alertmanager, Datadog, etc.) to SelfHeal 's /webhook.
• Create DB rules and allowlists using the SelfHeal dashboard.
• Start in Advisor mode, then selectively enable Single or Loop modes.

For architecture diagrams, AI modes, and guardrail details, see the full documentation.