Skip to content
Klutch.sh Docs

Deploying a ZincSearch App

Introduction

ZincSearch is a lightweight Elasticsearch alternative with a simple API and built-in UI. This guide shows how to containerize ZincSearch with a Dockerfile, configure credentials, persist indexes, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM public.ecr.aws/zinclabs/zincsearch:latest


# Default ZincSearch port
ENV PORT=4080
EXPOSE 4080

Required environment variables

  • ZINC_FIRST_ADMIN_USER – admin username
  • ZINC_FIRST_ADMIN_PASSWORD – admin password
  • ZINC_DATA_PATH=/data
  • PORT=4080 – internal port

Optional environment variables

  • ZINC_SERVER_ADDRESS=0.0.0.0
  • ZINC_TELEMETRY=false
  • ZINC_LOG_LEVEL=info

Persistence

Persist indexes and configuration:

  • Mount path: /data
  • Size: based on expected index size and retention

Networking

  • Protocol: HTTP
  • Internal port: 4080
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 4080 inside the container.
Terminal window
curl -I http://localhost:4080/healthz

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 4080.
  5. Add environment variables for ZINC_FIRST_ADMIN_USER, ZINC_FIRST_ADMIN_PASSWORD, and data path. Mark secrets as sensitive.
  6. Attach a persistent volume at /data sized for your indexes.
  7. Deploy. After the app starts, log in to the UI with your admin credentials and create your first index.

Verification

  • UI: open https://example-app.klutch.sh and confirm the ZincSearch dashboard loads.

  • Health:

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

Next steps

  • Secure access with strong credentials and restrict exposure to trusted clients.
  • Configure index retention and backups for the /data volume.
  • Integrate your applications using the ZincSearch API to ingest and query logs or documents.