Skip to content
Klutch.sh Docs

Deploying a Hydra App

Introduction

ORY Hydra is an open-source OAuth2 and OpenID Connect server written in Go. Deploying Hydra with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and flexible HTTP/TCP traffic for admin and public APIs—all from klutch.sh/app. This guide covers installation, repository preparation, Dockerfile configuration, deployment steps, Nixpacks overrides, and production best practices.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Hydra configuration or fork (GitHub is the only supported git source)
  • Docker familiarity and basic OAuth2/OIDC knowledge
  • PostgreSQL or MySQL connection details for Hydra’s data store
  • Optional: Redis or other cache endpoints if you offload sessions

For first-time users, review the Quick Start.

Architecture and ports

  • Hydra exposes two HTTP surfaces: public (4444) and admin (4445). Use 4444 for OAuth flows and 4445 for administrative tasks.
  • In Klutch.sh, set the internal container port to 4444 for the public service. If you want admin traffic separately, deploy a second app on port 4445 or gate it behind access controls.
  • Databases or caches on Klutch.sh should run as TCP apps exposed on port 8000, mapping internally to their native ports (5432 for Postgres, 3306 for MySQL).
  • Hydra is stateless aside from its database. Persistent storage is optional unless you store custom TLS keys or static assets on disk.

Repository layout

hydra/
├── config/                 # hydra.yml and policy files
├── scripts/                # helper scripts (migrations, health checks)
├── Dockerfile              # must be at repo root for auto-detection
├── .env.example            # template only; no secrets
└── README.md

Keep secrets out of Git; manage them via Klutch.sh environment variables.

Installation (local) and starter commands

Install dependencies and run Hydra locally before pushing to GitHub:

Terminal window
docker run --rm -it -p 4444:4444 -p 4445:4445 \
  -e DSN=postgres://user:pass@localhost:5432/hydra?sslmode=disable \
  oryd/hydra:v2 serve all --dangerous-force-http

For projects that build from source, add a helper script:

#!/usr/bin/env bash
set -euo pipefail
hydra migrate sql "$DSN" --yes
exec hydra serve all --config /app/config/hydra.yml

Make it executable with chmod +x scripts/start.sh.

Dockerfile for Hydra (production-ready)

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

FROM oryd/hydra:v2.2.0


WORKDIR /app


# Copy custom config and entrypoint script if you have them
COPY config ./config
COPY scripts/start.sh ./start.sh
RUN chmod +x /app/start.sh


# Recommended public port for Hydra
EXPOSE 4444


CMD ["/app/start.sh"]

Notes:

  • Use your preferred Hydra version tag and pin it for reproducible builds.
  • If you need admin traffic, either expose 4445 in the same container (secured) or run a second app dedicated to the admin API.

Environment variables (Klutch.sh)

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

  • DSN=postgres://<user>:<password>@<host>:<port>/<db>?sslmode=disable (or mysql://)
  • HYDRA_ADMIN_URL=https://example-app.klutch.sh (if you front admin traffic)
  • HYDRA_PUBLIC_URL=https://example-app.klutch.sh
  • SYSTEM_SECRET=<generate-32-byte-secret>
  • DATABASE_MAX_OPEN_CONNS=20 (tune per load)
  • SERVE_PUBLIC_PORT=4444
  • SERVE_ADMIN_PORT=4445
  • OAUTH2_EXPOSE_INTERNAL_ERRORS=false
  • TRACING_PROVIDER=jaeger (optional)

If you deploy without a Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=go build -o hydra ./cmd/hydra
  • NIXPACKS_START_CMD=./hydra serve all --config /app/config/hydra.yml
  • NIXPACKS_GO_VERSION=1.21

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

Attach persistent volumes (optional)

Hydra is stateless when backed by a database, but if you store custom TLS keys or static assets, add mount paths and sizes in Klutch.sh:

  • /app/config/certs — TLS keys and certificates.
  • /app/config/policies — policy files if you manage them on disk.

No volume names are required; only the mount path and size.

Deploy Hydra 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 public Hydra service.
  5. Set the internal port to 4444.
  6. Add the environment variables above (DSN, secrets, URLs, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach persistent volumes if you need to mount certs or policies.
  8. Deploy. Your public endpoints will be available at https://example-app.klutch.sh; secure admin traffic separately if exposed.

For databases on Klutch.sh, create separate TCP apps, expose them on port 8000, and point DSN to those endpoints (internal ports 5432/3306).

Health checks and production tips

  • Add a simple health route via hydra health or proxy a /health path that checks DB connectivity.
  • Rotate SYSTEM_SECRET carefully; changing it invalidates tokens.
  • Enforce HTTPS at the edge and disable --dangerous-force-http in production.
  • Pin Hydra image tags and Go versions for consistent builds.
  • Monitor DB connections and adjust DATABASE_MAX_OPEN_CONNS to avoid saturation.
  • Back up your database regularly; do not rely on container filesystems for durability.

Hydra on Klutch.sh combines reproducible Docker builds with managed secrets, flexible HTTP/TCP routing, and optional persistent mounts for certificates or policies. With the Dockerfile at the repo root and ports set to 4444 for public traffic (and 8000 externally for TCP databases), you can run a compliant OAuth2/OIDC server without extra YAML or workflow overhead.