Skip to content
Klutch.sh Docs

Deploying an ImmuDB App

Introduction

ImmuDB is an open-source, immutable database written in Go. Deploying ImmuDB with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for tamper-proof ledgers—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure, auditable data.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your ImmuDB config (GitHub is the only supported git source)
  • Docker familiarity and basic knowledge of ImmuDB’s gRPC/HTTP interfaces
  • Credentials or network access for any clients that will connect to the database

For platform setup, see the Quick Start.

Architecture and ports

  • ImmuDB exposes gRPC on port 3322 and an optional REST console on port 8080.
  • On Klutch.sh, choose TCP traffic for the database endpoint; set the internal port to 3322. The service will be reachable externally on port 8000 for TCP apps.
  • If you want the HTTP console, create a separate HTTP app pointing to internal port 8080.
  • Persistent storage is required for the data directory.

Repository layout

immudb/
├── config/                 # Optional config files
├── Dockerfile              # Must be at repo root for auto-detection
├── README.md
└── .env.example            # Template only; no secrets

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

Installation (local) and starter commands

Run ImmuDB locally with Docker for quick testing:

Terminal window
docker run --rm -p 3322:3322 -p 8080:8080 \
  -v $(pwd)/data:/var/lib/immudb \
  codenotary/immudb:latest

If you build from source, a simple start script could be:

#!/usr/bin/env bash
set -euo pipefail
./immudb --address 0.0.0.0 --port 3322 --dir /var/lib/immudb

Make it executable with chmod +x start.sh.

Dockerfile for ImmuDB (production-ready)

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

FROM codenotary/immudb:latest


WORKDIR /app


# Copy optional configs or TLS materials
COPY config /app/config


# Expose ImmuDB gRPC port
EXPOSE 3322


CMD ["immudb", "--config", "/app/config/immudb.toml", "--dir", "/var/lib/immudb"]

Notes:

  • Pin the image tag (e.g., :1.5.3) for reproducible builds.
  • If you use TLS, mount certs via a volume and reference them in immudb.toml.

Environment variables (Klutch.sh)

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

  • IMMUDB_ADDRESS=0.0.0.0
  • IMMUDB_PORT=3322
  • IMMUDB_DIR=/var/lib/immudb
  • IMMUDB_AUTH=true
  • IMMUDB_MTLS=false (set true and configure certs if required)
  • IMMUDB_PGSQL_SERVER=false (enable if you expose the PostgreSQL wire protocol)
  • IMMUDB_ADMIN_PASSWORD=<secure-password>

If you deploy without the Dockerfile and want Nixpacks overrides for a source build:

  • NIXPACKS_BUILD_CMD=go build -o immudb ./cmd/immudb
  • NIXPACKS_START_CMD=./immudb --address 0.0.0.0 --port 3322 --dir /var/lib/immudb
  • NIXPACKS_GO_VERSION=1.21

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

Attach persistent volumes

Add mount paths and sizes in Klutch.sh (no names required):

  • /var/lib/immudb — required for database storage.
  • /app/config — optional if you keep runtime-configurable files on disk.

Ensure these paths are writable by the container user.

Deploy ImmuDB 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. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  4. Choose TCP traffic for ImmuDB.
  5. Set the internal port to 3322.
  6. Add the environment variables above (addresses, auth, admin password, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach a persistent volume for /var/lib/immudb (and /app/config if needed), selecting sizes that fit your data growth.
  8. Deploy. Your database will be reachable at example-app.klutch.sh:8000 over TCP; connect your clients to that host and port.

For the optional HTTP console, create a separate app with HTTP traffic, internal port 8080, and the same codebase.

Health checks and production tips

  • Use ImmuDB’s /health (HTTP) or gRPC health service for monitoring.
  • Rotate admin credentials and secrets regularly; store them only as Klutch.sh secrets.
  • Enable TLS/MTLS for production and keep certificates mounted via volumes.
  • Monitor volume usage for /var/lib/immudb and resize before it fills.
  • Pin image and Go versions for reproducible builds.

ImmuDB on Klutch.sh combines reproducible Docker builds with managed secrets, durable volumes, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 3322 for the database (8000 externally for TCP clients), you can run an auditable, tamper-evident data store without extra YAML or workflow overhead.