Skip to content
Klutch.sh Docs

Deploying a Hyperswitch App

Introduction

Hyperswitch is an open-source payment orchestration platform built in Rust with a PostgreSQL and Redis backbone. Deploying Hyperswitch with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and HTTP/TCP routing for both API and webhook traffic—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure, compliant payment flows.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository with your Hyperswitch fork or configuration (GitHub is the only supported git source)
  • Docker familiarity and Rust toolchain experience
  • PostgreSQL credentials and Redis endpoint for caching/queues
  • TLS certificate/key (optional) if you terminate TLS inside the container

For platform basics, review the Quick Start.

Architecture and ports

  • Hyperswitch serves its API over HTTP; set the internal container port to 8080.
  • PostgreSQL and Redis should run as separate Klutch.sh TCP apps. Expose them on port 8000 and connect internally on their native ports (5432 for Postgres, 6379 for Redis).
  • Persistent storage is optional but recommended for configs, logs, and any custom SSL materials.

Repository layout

hyperswitch/
├── config/                 # app config, certs, secrets templates
├── crates/                 # Rust workspace crates
├── docker/                 # helper scripts (optional)
├── Dockerfile              # must be at repo root for auto-detection
├── Cargo.toml
├── Cargo.lock
└── .env.example            # template only; no secrets

Keep secrets out of Git and store them as Klutch.sh environment variables.

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub:

Terminal window
cargo build --release
cp config/config.example.toml config/config.toml
DATABASE_URL=postgres://user:pass@localhost:5432/hyperswitch \
REDIS_URL=redis://localhost:6379 \
ENCRYPTION_KEY=change-me-32-bytes \
JWT_SECRET=change-me \
./target/release/hyperswitch

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
./target/release/hyperswitch

Make it executable with chmod +x start.sh.

Dockerfile for Hyperswitch (production-ready)

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

FROM rust:1.72-slim AS build
WORKDIR /app


RUN apt-get update && apt-get install -y pkg-config libssl-dev clang && rm -rf /var/lib/apt/lists/*


COPY Cargo.toml Cargo.lock ./
COPY crates ./crates
COPY config ./config
RUN cargo build --release


FROM debian:12-slim
WORKDIR /app


RUN apt-get update && apt-get install -y ca-certificates openssl && rm -rf /var/lib/apt/lists/*


COPY --from=build /app/target/release/hyperswitch /app/hyperswitch
COPY --from=build /app/config /app/config


ENV RUST_LOG=info PORT=8080


EXPOSE 8080
CMD ["/app/hyperswitch"]

Notes:

  • Pin the Rust toolchain as needed for compliance or reproducibility.
  • If you bundle TLS certs, mount them into /app/config/certs and point your config there.

Environment variables (Klutch.sh)

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

  • PORT=8080
  • DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db>
  • REDIS_URL=redis://<user>:<password>@<host>:<port>
  • ENCRYPTION_KEY=<32-byte-key>
  • JWT_SECRET=<jwt-secret>
  • RUST_LOG=info
  • APP_BASE_URL=https://example-app.klutch.sh

If you deploy without a Dockerfile and want Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=cargo build --release
  • NIXPACKS_START_CMD=./target/release/hyperswitch
  • NIXPACKS_GO_VERSION=1.21 (omit for pure Rust; include only if you have Go helpers)
  • NIXPACKS_RUST_VERSION=1.72

These ensure Hyperswitch builds and starts correctly when Nixpacks is used.

Attach persistent volumes (optional)

If you store TLS materials or custom configs on disk, add mount paths and sizes in Klutch.sh:

  • /app/config/certs — TLS keys and certificates.
  • /app/logs — optional log persistence if not shipping to an external sink.

Only mount path and size are required.

Deploy Hyperswitch 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 HTTP traffic for the Hyperswitch API.
  5. Set the internal port to 8080.
  6. Add the environment variables above (database, Redis, encryption, JWT, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach persistent volumes for /app/config/certs or /app/logs if you need them, choosing sizes that match your data requirements.
  8. Deploy. Your API will be reachable at https://example-app.klutch.sh; add custom domains as needed.

For PostgreSQL or Redis on Klutch.sh, create separate TCP apps, expose them on port 8000, and point DATABASE_URL or REDIS_URL to those endpoints (internal ports 5432/6379).

Health checks and production tips

  • Add a /health endpoint that verifies DB and Redis connectivity.
  • Rotate ENCRYPTION_KEY and JWT_SECRET carefully to avoid invalidating tokens unintentionally.
  • Pin dependency versions and Rust toolchain for reproducible builds.
  • Monitor database connections and Redis saturation; tune pool sizes accordingly.
  • Back up databases regularly; do not rely on container filesystems for durability.
  • Enforce HTTPS at the edge; terminate TLS before forwarding to 8080 if desired.

Hyperswitch on Klutch.sh pairs reproducible Docker builds with managed secrets, optional persistent mounts, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the API (and 8000 externally for TCP databases or caches), you can orchestrate payments reliably without extra YAML or workflow overhead.