Skip to content
Klutch.sh Docs

Deploying a KeyDB App

Introduction

KeyDB is a high-performance, multi-threaded Redis-compatible database. Deploying KeyDB with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for in-memory data persisted to disk—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for reliable caching and data durability.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your KeyDB configuration (GitHub is the only supported git source)
  • Docker familiarity and basic Redis/KeyDB knowledge
  • Storage for append-only files (AOF) and snapshots

For setup basics, see the Quick Start.

Architecture and ports

  • KeyDB listens on TCP port 6379; set the internal container port to 6379 and choose TCP traffic in Klutch.sh.
  • Persistent storage is required for /data to retain snapshots/AOF.
  • For replication, expose additional ports as needed or configure replication via environment variables.

Repository layout

keydb/
├── keydb.conf              # Optional custom config
├── Dockerfile              # Must be at repo root for auto-detection
├── scripts/                # Helper scripts (optional)
└── README.md

Keep secrets (passwords, TLS certs) in Klutch.sh environment variables, not in Git.

Installation (local) and starter commands

Quick local run:

Terminal window
docker run --rm -p 6379:6379 \
  -v $(pwd)/data:/data \
  eqalpha/keydb:alpine \
  keydb-server /etc/keydb/keydb.conf --appendonly yes

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec keydb-server /etc/keydb/keydb.conf --appendonly yes

Make it executable with chmod +x start.sh.

Dockerfile for KeyDB (production-ready)

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

FROM eqalpha/keydb:alpine


WORKDIR /app


# Copy custom config if provided
COPY keydb.conf /etc/keydb/keydb.conf


EXPOSE 6379
CMD ["keydb-server", "/etc/keydb/keydb.conf", "--appendonly", "yes"]

Notes:

  • Pin the image tag (e.g., eqalpha/keydb:6.3.4-alpine) for reproducible behavior.
  • Add TLS certs via a volume and reference them in keydb.conf if needed.

Environment variables (Klutch.sh)

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

  • PORT=6379
  • KEYDB_PASSWORD=<strong-password> (if using requirepass in config)
  • KEYDB_APPENDONLY=yes
  • KEYDB_SAVE=900 1 (example snapshot policy)
  • KEYDB_MAXMEMORY=512mb (adjust as needed)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo KeyDB uses prebuilt image"
  • NIXPACKS_START_CMD=keydb-server /etc/keydb/keydb.conf --appendonly yes
  • NIXPACKS_JDK_VERSION=17 (not typically needed, but listed for completeness)

These keep KeyDB compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

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

  • /data — required for AOF/snapshots.
  • /etc/keydb — optional if you want to persist custom configs or TLS certs.

Ensure these paths are writable inside the container.

Deploy KeyDB 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 TCP traffic for KeyDB.
  3. Set the internal port to 6379.
  4. Add the environment variables above (password, append-only settings, memory limits, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /data (and /etc/keydb if used), selecting sizes that fit your persistence and configuration needs.
  6. Deploy. Your KeyDB instance will be reachable at example-app.klutch.sh:8000 over TCP for clients.

Sample code (Node.js client)

import { createClient } from "redis";


const client = createClient({
  url: "redis://:PASSWORD@example-app.klutch.sh:8000",
});


await client.connect();
await client.set("hello", "keydb-on-klutch");
const value = await client.get("hello");
console.log(value);
await client.disconnect();

Health checks and production tips

  • Use PING or INFO via your monitoring stack to verify health.
  • Enforce authentication and TLS in production; keep credentials in Klutch.sh secrets.
  • Monitor memory and disk usage; adjust maxmemory and resize /data as needed.
  • Keep image tags pinned; upgrade intentionally.
  • For replication or sharding, deploy multiple KeyDB instances with appropriate config and connect them accordingly.

KeyDB on Klutch.sh combines reproducible Docker builds with managed secrets, persistent volumes for AOF/snapshots, and flexible TCP routing. With the Dockerfile at the repo root and ports set to 6379 internally (8000 externally for clients), you can deliver fast, durable caching and data storage without extra YAML or workflow overhead.