Skip to content
Klutch.sh Docs

Deploying a Prometheus App

Introduction

Prometheus is a leading open-source monitoring system with a pull-based scraper and time-series storage. Deploying Prometheus with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample queries.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Prometheus Dockerfile and config (GitHub is the only supported git source)
  • Targets to scrape, reachable from the Prometheus container

For onboarding, see the Quick Start.

Architecture and ports

  • Prometheus serves HTTP on internal port 9090. Choose HTTP traffic and set the internal port to 9090.
  • Persistent storage is recommended to retain time series across deployments.

Repository layout

prometheus/
├── Dockerfile              # Must be at repo root for auto-detection
└── prometheus.yml          # Scrape configuration

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 prometheus-local .
docker run -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  prometheus-local

Dockerfile for Prometheus (production-ready)

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

FROM prom/prometheus:latest


COPY prometheus.yml /etc/prometheus/prometheus.yml


EXPOSE 9090
CMD ["/bin/prometheus", "--config.file=/etc/prometheus/prometheus.yml", "--storage.tsdb.path=/prometheus"]

Notes:

  • Pin to a specific tag (e.g., prom/prometheus:v2.49.1) for stability.
  • The TSDB path is /prometheus; mount a volume there to persist data.

Environment variables (Klutch.sh)

Prometheus primarily uses flags/config. If you need to override in Nixpacks:

  • NIXPACKS_START_CMD=/bin/prometheus --config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/prometheus

Attach persistent volumes

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

  • /prometheus — TSDB data directory.

Ensure it is writable inside the container.

Deploy Prometheus on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile and prometheus.yml 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 9090.
  4. Attach a volume at /prometheus sized for your retention and ingestion rate.
  5. Deploy. Access Prometheus at https://example-app.klutch.sh.

Sample configuration (prometheus.yml)

global:
  scrape_interval: 15s
  evaluation_interval: 15s


scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  - job_name: 'app'
    static_configs:
      - targets: ['your-app:8080']

Adjust targets to match your services reachable from the Prometheus container.

Sample queries and checks

UI/health check:

Terminal window
curl -I https://example-app.klutch.sh/-/ready

Query an example metric:

Terminal window
curl "https://example-app.klutch.sh/api/v1/query?query=up"

Health checks and production tips

  • Use readiness probe /-/ready and liveness probe /-/healthy.
  • Keep scrape targets reachable from the Prometheus container; secure endpoints with auth if needed.
  • Pin image versions and test config changes in staging; reload by redeploying with updated config.
  • Monitor volume usage on /prometheus; resize before retention causes pressure.

Prometheus on Klutch.sh delivers reproducible Docker builds, persistent TSDB storage, and managed configuration—without extra YAML or CI steps. Configure ports, storage, and scrape targets, then start collecting metrics.