Skip to content
Klutch.sh Docs

Deploying an Imagor App

Introduction

Imagor is an open-source, high-performance image processing server built in Go. Deploying Imagor with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for cached assets—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure, scalable image delivery.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Imagor config or fork (GitHub is the only supported git source)
  • Docker familiarity and basic Go knowledge
  • Optional: S3-compatible object storage credentials for source/destination buckets
  • Optional: Redis if you offload caching

For platform basics, review the Quick Start.

Architecture and ports

  • Imagor serves HTTP; set the internal container port to 8000 (Imagor’s default).
  • If you run Redis or databases on Klutch.sh, deploy them as TCP apps exposed on port 8000 externally and connect on native ports (6379 for Redis).
  • Persistent storage is recommended for cached images if you want warm cache across deploys.

Repository layout

imagor/
├── config/                 # imagor.yml or env files
├── docker/                 # helper scripts (optional)
├── Dockerfile              # must be at repo root for auto-detection
├── go.mod
├── go.sum
└── README.md

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

Installation (local) and starter commands

Build and run Imagor locally before pushing to GitHub:

Terminal window
go mod tidy
go build -o imagor ./cmd/imagor
PORT=8000 ./imagor

Example start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
go build -o imagor ./cmd/imagor
exec ./imagor

Make it executable with chmod +x start.sh.

Dockerfile for Imagor (production-ready)

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

FROM golang:1.21-alpine AS build
WORKDIR /app


RUN apk add --no-cache build-base
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o imagor ./cmd/imagor


FROM alpine:3.18
WORKDIR /app
ENV PORT=8000


COPY --from=build /app/imagor /app/imagor
COPY --from=build /app/config /app/config


EXPOSE 8000
CMD ["/app/imagor"]

Notes:

  • Adjust GOARCH if you need arm64 builds.
  • Copy only necessary config files; avoid shipping secrets in the image.

Environment variables (Klutch.sh)

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

  • PORT=8000
  • IMAGOR_SECRET (signing key for secure URLs)
  • IMAGOR_ENDPOINT=http://0.0.0.0:8000
  • IMAGOR_STORAGE_PATH=/app/cache (if using local cache)
  • IMAGOR_S3_ENDPOINT, IMAGOR_S3_ACCESS_KEY, IMAGOR_S3_SECRET_KEY, IMAGOR_S3_BUCKET (if using S3)
  • REDIS_URL=redis://<user>:<password>@<host>:<port> (if using Redis cache)

If you deploy without a Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=go build -o imagor ./cmd/imagor
  • NIXPACKS_START_CMD=./imagor
  • NIXPACKS_GO_VERSION=1.21

These keep Imagor compatible with the Nixpacks build pipeline when a Dockerfile is absent.

Attach persistent volumes (optional)

If you want cached images to persist across deploys, add mount paths and sizes in Klutch.sh:

  • /app/cache — for local cache storage.

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

Deploy Imagor 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 Imagor.
  5. Set the internal port to 8000.
  6. Add the environment variables above (secrets, storage, S3/Redis, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach a persistent volume for /app/cache if you need cache durability, choosing a size that fits your traffic.
  8. Deploy. Your Imagor server will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For Redis on Klutch.sh, create a separate TCP app, expose it on port 8000, and point REDIS_URL to that endpoint (internal port 6379).

Health checks and production tips

  • Add a /health endpoint or use Imagor’s built-in health handler for uptime monitoring.
  • Pin Go and dependency versions for reproducible builds.
  • Enforce signed URLs with IMAGOR_SECRET to prevent abuse.
  • Monitor cache disk usage and resize the /app/cache volume before it fills.
  • Terminate TLS at the edge; forward HTTP to port 8000 internally.

Imagor on Klutch.sh combines reproducible Docker builds with managed secrets, optional persistent cache volumes, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8000 for the app (and 8000 externally for TCP caches like Redis), you can deliver secure, performant image processing without extra YAML or workflow overhead.