Skip to content
Klutch.sh Docs

Deploying a Sensu App

Introduction

Sensu is an open-source monitoring and observability platform with checks, pipelines, and event processing. Deploying Sensu with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide focuses on a single-node backend (no clustering) reachable over HTTP.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Sensu Dockerfile (GitHub is the only supported git source)
  • Admin credentials you will configure for the backend

For onboarding, see the Quick Start.

Architecture and ports

  • Sensu backend serves HTTP on internal port 8080 (API and dashboard). Choose HTTP traffic and set the internal port to 8080.
  • Persistent storage is required for backend state; agents connect to the backend’s API/websocket on the same port in this single-node setup.

Repository layout

sensu/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally:

Terminal window
docker build -t sensu-local .
docker run -p 8080:8080 \
  -e SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=admin \
  -e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=changeme \
  sensu-local

Dockerfile for Sensu (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM sensu/sensu:latest


ENV SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=admin
ENV SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=changeme


EXPOSE 8080
CMD ["sensu-backend", "start", "--state-dir", "/var/lib/sensu"]

Notes:

  • Pin to a specific tag (e.g., sensu/sensu:6.11.0) for stability.
  • This uses a single backend; clustering requires additional coordination and ports not covered here.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=8080
  • SENSU_BACKEND_CLUSTER_ADMIN_USERNAME=<admin-user>
  • SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD=<strong-password>
  • Optional: SENSU_BACKEND_ETCD_INITIAL_CLUSTER=backend=http://127.0.0.1:2380 (single-node default), TLS vars if you terminate TLS at the app

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=sensu-backend start --state-dir /var/lib/sensu

Attach persistent volumes

Add storage in Klutch.sh (path and size only):

  • /var/lib/sensu — backend state and data.

Ensure the path is writable inside the container.

Deploy Sensu on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above (admin credentials and any optional settings).
  5. Attach a volume at /var/lib/sensu sized for your state.
  6. Deploy. Access the API/UI at https://example-app.klutch.sh using the admin credentials.

Sample API usage

Health check:

Terminal window
curl -u admin:changeme https://example-app.klutch.sh/health

List namespaces:

Terminal window
curl -u admin:changeme https://example-app.klutch.sh/api/core/v2/namespaces

Create a basic check (example):

Terminal window
curl -u admin:changeme -X PUT \
  https://example-app.klutch.sh/api/core/v2/namespaces/default/checks/ping \
  -H "Content-Type: application/json" \
  -d '{"command":"ping -c1 127.0.0.1","interval":30,"publish":true,"subscriptions":["system"]}'

Health checks and production tips

  • Add an HTTP readiness probe to /health.
  • Keep admin credentials in Klutch.sh secrets; rotate regularly.
  • Pin image versions and test upgrades in staging before production rollout.
  • Monitor volume usage on /var/lib/sensu; resize before state growth causes issues.

Sensu on Klutch.sh delivers reproducible Docker builds, managed secrets, and persistent backend state—without extra YAML or CI steps. Configure ports, credentials, and storage, then start collecting events and checks.