Skip to content
Klutch.sh Docs

Deploying a KrakenD App

Introduction

KrakenD is an open-source, high-performance API gateway. Deploying KrakenD with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and optional persistence for configuration—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample configuration, and production tips for reliable API aggregation.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your KrakenD configuration (GitHub is the only supported git source)
  • Docker familiarity and Go/JSON config basics
  • Optional Redis or backend services you aggregate

For platform onboarding, see the Quick Start.

Architecture and ports

  • KrakenD serves HTTP; set the internal container port to 8080.
  • If you add TCP-dependent backends (databases, caches), deploy them as separate Klutch.sh TCP apps exposed on port 8000 and connect on their native ports.
  • Persistent storage is optional; mount if you edit configs at runtime.

Repository layout

krakend/
├── krakend.json            # Primary configuration file
├── config/                 # Additional partials or templates
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

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

Installation (local) and starter commands

Validate your config locally before pushing to GitHub:

Terminal window
docker run --rm -v $(pwd):/etc/krakend -p 8080:8080 devopsfaith/krakend run -c /etc/krakend/krakend.json

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec krakend run -c /etc/krakend/krakend.json

Make it executable with chmod +x start.sh.

Dockerfile for KrakenD (production-ready)

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

FROM devopsfaith/krakend:2.5


WORKDIR /etc/krakend


COPY krakend.json /etc/krakend/krakend.json
COPY config /etc/krakend/config


EXPOSE 8080
CMD ["run", "-c", "/etc/krakend/krakend.json"]

Notes:

  • Pin the image tag for reproducible builds.
  • If you use the Enterprise or EE features, adjust the base image accordingly.

Environment variables (Klutch.sh)

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

  • PORT=8080
  • KRAKEND_CONFIG=/etc/krakend/krakend.json
  • Backend secrets or tokens (e.g., AUTH_TOKEN, API_KEY_<SERVICE>)
  • Any dynamic values you template into krakend.json

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo KrakenD uses prebuilt image"
  • NIXPACKS_START_CMD=krakend run -c /etc/krakend/krakend.json
  • NIXPACKS_GO_VERSION=1.21

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

Attach persistent volumes

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

  • /etc/krakend — optional if you edit configs at runtime.
  • /var/log/krakend — optional if you persist logs locally.

Ensure these paths are writable inside the container.

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

Sample krakend.json snippet

{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "name": "klutch-gateway",
  "port": 8080,
  "endpoints": [
    {
      "endpoint": "/hello",
      "method": "GET",
      "backend": [
        {
          "url_pattern": "/",
          "host": ["https://httpbin.org"],
          "encoding": "json"
        }
      ]
    }
  ]
}

Health checks and production tips

  • Add a reverse proxy health check hitting /__health or /__debug/info.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep image tags pinned and update intentionally.
  • Monitor logs and traffic; resize volumes if you persist logs on disk.
  • Store secrets in Klutch.sh variables; avoid embedding in krakend.json.

KrakenD on Klutch.sh combines reproducible Docker builds with managed secrets, optional persistent config/log storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8080 configured, you can ship a performant API gateway without extra YAML or workflow overhead.