Skip to content
Klutch.sh Docs

Deploying an IRIS App

Introduction

IRIS is an open-source messaging and notification platform. Deploying IRIS with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for configuration and message state—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and operational best practices.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your IRIS source/config (GitHub is the only supported git source)
  • Docker familiarity and Python/Node basics (IRIS services may use both)
  • Database credentials (PostgreSQL/MySQL) and optional Redis for caching/queues
  • Optional object storage credentials if storing attachments externally

For platform onboarding, review the Quick Start.

Architecture and ports

  • Serve IRIS over HTTP; set the internal container port to 8080.
  • Databases and Redis should run as separate Klutch.sh TCP apps. Expose them on port 8000 and connect internally on native ports (5432/3306 for DB, 6379 for Redis).
  • Persistent storage is recommended for configs, logs, and any local message cache.

Repository layout

iris/
├── config/                 # App configuration and secrets templates
├── src/                    # Service code
├── scripts/                # Helper scripts for setup/health/migrations
├── Dockerfile              # Must be at repo root for auto-detection
├── requirements.txt        # If Python-based
├── package.json            # If Node components exist
└── .env.example            # Template only; no secrets

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

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub (Python example):

Terminal window
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export PORT=8080
python -m iris

If your project uses Node for UI or worker processes, add:

Terminal window
pnpm install
pnpm build
pnpm start -- --port 8080

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f package.json ]; then pnpm install --frozen-lockfile && pnpm build; fi
python -m iris

Make it executable with chmod +x start.sh.

Dockerfile for IRIS (production-ready)

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

FROM python:3.11-slim AS base
WORKDIR /app


# System deps for builds
RUN apt-get update && apt-get install -y build-essential curl && rm -rf /var/lib/apt/lists/*


# Python dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt


# Node build (if you ship a web UI)
FROM node:18-alpine AS ui
WORKDIR /app
COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build


# Final runtime
FROM python:3.11-slim
WORKDIR /app
ENV PORT=8080


COPY --from=base /usr/local/lib/python3.11 /usr/local/lib/python3.11
COPY --from=base /usr/local/bin /usr/local/bin
COPY . .


# If you built a UI, copy its dist (adjust path as needed)
COPY --from=ui /app/dist /app/dist


EXPOSE 8080
CMD ["python", "-m", "iris"]

Notes:

  • If IRIS is purely Python, drop the Node stage. If it is purely Node, convert the base image to node:18-alpine and use a Node start command.
  • For native modules, install build tools in the build stage (apt-get install -y gcc g++ make).

Environment variables (Klutch.sh)

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

  • PORT=8080
  • APP_BASE_URL=https://example-app.klutch.sh
  • DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db> (or mysql://)
  • REDIS_URL=redis://<user>:<password>@<host>:<port> (if using Redis)
  • JWT_SECRET or APP_SECRET (depending on IRIS config)
  • LOG_LEVEL=info

If you deploy without a Dockerfile and want Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="pip install -r requirements.txt && pnpm install --frozen-lockfile && pnpm build"
  • NIXPACKS_START_CMD=python -m iris
  • NIXPACKS_PYTHON_VERSION=3.11
  • NIXPACKS_NODE_VERSION=18 (only if building a web UI)

These ensure IRIS builds and starts correctly with Nixpacks when a Dockerfile is absent.

Attach persistent volumes

If your deployment stores configs, message cache, or uploads on disk, add mount paths and sizes in Klutch.sh (no names required):

  • /app/config — configuration and templates you want writable.
  • /app/storage — optional cache or uploaded files.

Ensure these paths are writable inside the container.

Deploy IRIS 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 IRIS.
  5. Set the internal port to 8080.
  6. Add the environment variables above (database, Redis, secrets, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach persistent volumes for /app/config or /app/storage if you need them, choosing sizes that fit your data.
  8. Deploy. Your app will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For databases 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/3306/6379).

Health checks and production tips

  • Add a /health endpoint that verifies DB/Redis connectivity.
  • Pin Python/Node versions for reproducible builds; keep lockfiles committed.
  • Monitor storage usage on mounted paths and resize before they fill.
  • Back up your database regularly; do not rely on container filesystems for durability.
  • Enforce HTTPS at the edge; terminate TLS before forwarding to 8080 if desired.

IRIS on Klutch.sh combines reproducible Docker builds with managed secrets, optional persistent volumes, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the app (8000 externally for TCP databases or caches), you can deliver reliable messaging and notification services without extra YAML or workflow overhead.