Skip to content
Klutch.sh Docs

Deploying a Quickwit App

Introduction

Quickwit is a cloud-native search engine optimized for logs and analytics with object-storage-friendly indexing. Deploying Quickwit 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 API calls.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Quickwit Dockerfile and config (GitHub is the only supported git source)
  • Optional: external object storage (S3-compatible) if you want to offload indexes

For onboarding, see the Quick Start.

Architecture and ports

  • Quickwit’s HTTP API listens on internal port 7280. Choose HTTP traffic and set the internal port to 7280.
  • Persistent storage is recommended for indexes if not using remote object storage.

Repository layout

quickwit/
├── Dockerfile              # Must be at repo root for auto-detection
├── config/quickwit.yaml    # Optional custom configuration
└── 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 quickwit-local .
docker run -p 7280:7280 \
  -v $(pwd)/data:/var/lib/quickwit \
  quickwit-local

Dockerfile for Quickwit (production-ready)

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

FROM quickwit/quickwit:latest


COPY config/quickwit.yaml /quickwit/config/quickwit.yaml


EXPOSE 7280
CMD ["quickwit", "run"]

Notes:

  • Pin to a specific tag (e.g., quickwit/quickwit:0.8.2) for stability.
  • Remove the COPY line if you rely on defaults or provide config via env/remote.

Environment variables (Klutch.sh)

Common settings:

  • QW_HTTP_LISTEN_ADDR=0.0.0.0:7280
  • QW_DATA_DIR=/var/lib/quickwit
  • Optional S3-compatible storage:
    • QW_S3_ENDPOINT=<s3-endpoint>
    • QW_S3_REGION=<region>
    • QW_S3_ACCESS_KEY_ID=<key>
    • QW_S3_SECRET_ACCESS_KEY=<secret>
    • QW_S3_BUCKET=<bucket>

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=quickwit run

Attach persistent volumes

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

  • /var/lib/quickwit — local index storage.

Ensure the path is writable inside the container.

Deploy Quickwit 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 7280.
  4. Add environment variables (listen address, data dir, and any S3 credentials).
  5. Attach a volume at /var/lib/quickwit sized for your indexes.
  6. Deploy. Your API will be reachable at https://example-app.klutch.sh.

Sample API usage

Create an index:

Terminal window
curl -X POST https://example-app.klutch.sh/api/v1/indexes \
  -H "Content-Type: application/json" \
  -d '{"index_id":"logs","doc_mapping":{"mode":"dynamic"}}'

Ingest documents:

Terminal window
curl -X POST https://example-app.klutch.sh/api/v1/indexes/logs/ingest \
  -H "Content-Type: application/json" \
  -d '[{"timestamp":"2024-01-01T00:00:00Z","message":"hello world","level":"info"}]'

Search:

Terminal window
curl "https://example-app.klutch.sh/api/v1/indexes/logs/search?q=message:hello"

Health checks and production tips

  • Use readiness probe on /health to confirm the service is running.
  • Pin image versions and test config changes in staging; redeploy to apply changes.
  • If using S3, keep credentials in Klutch.sh secrets and avoid embedding them in images.
  • Monitor storage usage on /var/lib/quickwit (or your bucket) and adjust retention accordingly.

Quickwit on Klutch.sh delivers reproducible Docker builds, persistent index storage, and managed secrets—without extra YAML or CI steps. Configure ports, storage, and S3 settings, then start indexing and searching your data.