Skip to content
Klutch.sh Docs

Deploying a Loki App

Introduction

Loki is a log aggregation system from Grafana optimized for indexing and querying logs efficiently. Deploying Loki with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for log data—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample queries, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Loki config (GitHub is the only supported git source)
  • Docker familiarity and basic Loki configuration knowledge
  • Storage for log chunks and indexes

For platform onboarding, see the Quick Start.

Architecture and ports

  • Loki serves HTTP on port 3100; set the internal container port to 3100 and choose HTTP traffic in Klutch.sh.
  • Persistent storage is required for /loki to store chunks and indexes.
  • If you run Promtail or other agents, deploy them separately and point them to Loki’s HTTP endpoint.

Repository layout

loki/
├── Dockerfile              # Must be at repo root for auto-detection
├── config.yaml             # Loki configuration
├── data/                   # Persistent data (mount as volume)
└── README.md

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

Installation (local) and starter commands

Test Loki locally before pushing to GitHub:

Terminal window
docker run --rm -p 3100:3100 \
  -v $(pwd)/config.yaml:/etc/loki/local-config.yaml \
  -v $(pwd)/data:/loki \
  grafana/loki:2.9.3 -config.file=/etc/loki/local-config.yaml

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec loki -config.file=/etc/loki/local-config.yaml

Make it executable with chmod +x start.sh.

Dockerfile for Loki (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM grafana/loki:2.9.3


WORKDIR /etc/loki


COPY config.yaml /etc/loki/config.yaml


EXPOSE 3100
CMD ["-config.file=/etc/loki/config.yaml"]

Notes:

  • Pin the Loki image tag for reproducible behavior.
  • Adjust config paths or flags if you use a custom configuration layout.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=3100
  • LOKI_CONFIG_FILE=/etc/loki/config.yaml
  • Any S3/object storage credentials if you use remote storage (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET_NAME)
  • Optional: LOKI_LOG_LEVEL=info

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Loki uses prebuilt image"
  • NIXPACKS_START_CMD=loki -config.file=/etc/loki/config.yaml
  • NIXPACKS_GO_VERSION=1.21

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /loki — required for local chunk/index storage.
  • /etc/loki — optional if you keep configs on disk and edit them at runtime.

Ensure these paths are writable inside the container.

Deploy Loki 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.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Loki.
  3. Set the internal port to 3100.
  4. Add the environment variables above (config path, storage credentials, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /loki (and /etc/loki if used), selecting sizes that match your log retention.
  6. Deploy. Your Loki endpoint will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample query (LogQL)

Query logs using LogQL (with Grafana or curl):

Terminal window
curl -G "https://example-app.klutch.sh/loki/api/v1/query" \
  --data-urlencode 'query={job="promtail"} |~ "error"' \
  --data-urlencode 'limit=20'

Health checks and production tips

  • Use a reverse proxy probe to /ready or /metrics for health monitoring.
  • Enforce HTTPS at the edge; forward HTTP to port 3100 internally.
  • Keep image tags pinned; upgrade intentionally after testing.
  • Monitor disk usage on /loki and resize volumes before they fill.
  • If using object storage, validate credentials and bucket permissions.

Loki on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for logs, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 3100 configured, you can run reliable log aggregation without extra YAML or workflow overhead.