Skip to content
Klutch.sh Docs

Deploying a M3DB App

Introduction

M3DB is a distributed time-series database optimized for high-ingest and query performance. Deploying M3DB with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for metrics—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your M3DB config (GitHub is the only supported git source)
  • Docker familiarity and basic M3DB operations
  • Storage for time-series data and indexes

For platform onboarding, see the Quick Start.

Architecture and ports

  • M3DB exposes an HTTP API (coordinator) on port 7201; set the internal container port to 7201 and choose HTTP traffic in Klutch.sh.
  • The M3DB node RPC port is 9003; if clients need RPC access, create a separate Klutch.sh TCP app with internal port 9003 (external 8000).
  • Persistent storage is required for /var/lib/m3db to keep data and commit logs.

Repository layout

m3db/
├── Dockerfile              # Must be at repo root for auto-detection
├── m3dbnode.yaml           # M3DB 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 M3DB locally before pushing to GitHub:

Terminal window
docker run --rm -p 7201:7201 -p 9003:9003 \
  -v $(pwd)/m3dbnode.yaml:/etc/m3db/m3dbnode.yaml \
  -v $(pwd)/data:/var/lib/m3db \
  quay.io/m3db/m3dbnode:latest \
  -f /etc/m3db/m3dbnode.yaml

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec m3dbnode -f /etc/m3db/m3dbnode.yaml

Make it executable with chmod +x start.sh.

Dockerfile for M3DB (production-ready)

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

FROM quay.io/m3db/m3dbnode:latest


WORKDIR /etc/m3db


COPY m3dbnode.yaml /etc/m3db/m3dbnode.yaml


EXPOSE 7201 9003
CMD ["-f", "/etc/m3db/m3dbnode.yaml"]

Notes:

  • Pin the image tag (e.g., quay.io/m3db/m3dbnode:v1.7.0) for reproducible behavior.
  • Adjust the config file path if you customize the layout.

Environment variables (Klutch.sh)

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

  • PORT=7201
  • M3DB_CONFIG_FILE=/etc/m3db/m3dbnode.yaml
  • M3DB_LOG_LEVEL=info (optional)
  • Any cluster-specific seeds or overrides you template into m3dbnode.yaml

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo M3DB uses prebuilt image"
  • NIXPACKS_START_CMD=m3dbnode -f /etc/m3db/m3dbnode.yaml
  • NIXPACKS_GO_VERSION=1.21

Attach persistent volumes

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

  • /var/lib/m3db — required for data and commit logs.
  • /etc/m3db — optional if you edit configs at runtime.

Ensure these paths are writable inside the container.

Deploy M3DB 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 the coordinator API and set the internal port to 7201.
  3. Add the environment variables above (config path, log level, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  4. Attach persistent volumes for /var/lib/m3db (and /etc/m3db if used), selecting sizes that fit your retention plan.
  5. Deploy. Your M3DB coordinator API will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

If you need RPC access on port 9003, create a separate Klutch.sh TCP app with internal port 9003 and connect clients to example-app.klutch.sh:8000.

Sample API usage

Check cluster health via the coordinator API:

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v1/services/m3db/health"

Health checks and production tips

  • Use /health or the coordinator health endpoint for monitoring.
  • Enforce HTTPS at the edge; forward HTTP to port 7201 internally.
  • Pin image tags and test upgrades carefully to avoid data migrations surprises.
  • Monitor disk usage on /var/lib/m3db and resize volumes before they fill.
  • Back up data periodically and verify retention/replication settings in m3dbnode.yaml.

M3DB on Klutch.sh combines reproducible Docker builds with managed secrets, durable storage for metrics, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 7201 (and optional 9003 via TCP), you can run high-performance time-series workloads without extra YAML or workflow overhead.