Skip to content
Klutch.sh Docs

Deploying an InvokeAI App

Introduction

InvokeAI is an open-source Stable Diffusion toolkit for image generation, featuring a React front end and Python backend. Deploying InvokeAI with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for models and outputs—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for GPU-ready image generation.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your InvokeAI code/config (GitHub is the only supported git source)
  • Docker familiarity and Python 3.10+ toolchain knowledge
  • Access to NVIDIA GPU if you intend to run GPU-accelerated inference (ensure your Klutch.sh plan supports it)
  • Storage capacity for model weights, embeddings, and generated assets

For platform basics, review the Quick Start.

Architecture and ports

  • InvokeAI serves its web UI and API over HTTP; set the internal container port to 9090.
  • No additional TCP services are required by default. If you add databases or caches, run them as separate Klutch.sh TCP apps (external TCP port 8000, internal native ports).
  • Persistent storage is required for models, embeddings, and generated outputs.

Repository layout

invokeai/
├── invokeai/               # Backend Python modules
├── invokeai/frontend/      # React frontend
├── configs/                # YAML configs, model paths, UI settings
├── models/                 # Model weights (mount as volume)
├── outputs/                # Generated images (mount as volume)
├── Dockerfile              # Must be at repo root for auto-detection
├── requirements.txt
├── package.json
├── pnpm-lock.yaml          # or yarn.lock / package-lock.json
└── .env.example            # Template only; no secrets

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

Installation (local) and starter commands

Install dependencies locally before pushing to GitHub:

Terminal window
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pnpm install
pnpm build
invokeai --web --host 0.0.0.0 --port 9090

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
invokeai --web --host 0.0.0.0 --port 9090

Make it executable with chmod +x start.sh.

Dockerfile for InvokeAI (production-ready)

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

FROM nvidia/cuda:12.2.2-cudnn8-runtime-ubuntu22.04


WORKDIR /app


# System dependencies
RUN apt-get update && apt-get install -y python3 python3-venv python3-pip git curl build-essential && \
    rm -rf /var/lib/apt/lists/*


# Install Python dependencies
COPY requirements.txt ./
RUN python3 -m venv /opt/venv && \
    /opt/venv/bin/pip install --no-cache-dir -r requirements.txt


# Frontend build
COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
RUN curl -fsSL https://get.pnpm.io/install.sh | sh - && \
    export PATH=\"/root/.local/share/pnpm:$PATH\" && \
    pnpm install --frozen-lockfile


COPY . .
RUN export PATH=\"/root/.local/share/pnpm:$PATH\" && pnpm build


ENV PATH=\"/opt/venv/bin:/root/.local/share/pnpm:$PATH\" \
    INVOKEAI_PORT=9090


EXPOSE 9090
CMD ["invokeai", "--web", "--host", "0.0.0.0", "--port", "9090"]

Notes:

  • Use an NVIDIA CUDA base if you need GPU; for CPU-only, swap to python:3.11-slim and remove CUDA tooling.
  • Keep models/ and outputs/ on volumes to preserve downloads and generations across deploys.

Environment variables (Klutch.sh)

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

  • INVOKEAI_PORT=9090
  • INVOKEAI_ROOT=/app (if your config expects a root path)
  • INVOKEAI_MODEL_DIR=/app/models
  • INVOKEAI_OUTPUT_DIR=/app/outputs
  • PYTHONUNBUFFERED=1
  • NODE_ENV=production

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="pip install -r requirements.txt && pnpm install --frozen-lockfile && pnpm build"
  • NIXPACKS_START_CMD=invokeai --web --host 0.0.0.0 --port 9090
  • NIXPACKS_PYTHON_VERSION=3.11
  • NIXPACKS_NODE_VERSION=18

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

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /app/models — required for model weights and embeddings.
  • /app/outputs — required for generated images and videos.
  • /app/configs — optional if you adjust configs at runtime.

Ensure these paths are writable inside the container.

Deploy InvokeAI 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 InvokeAI.
  3. Set the internal port to `9090`.
  4. Add the environment variables above (model/output paths and any `NIXPACKS_*` overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for `/app/models` and `/app/outputs` (and `/app/configs` if needed), selecting sizes that fit your models and generations.
  6. Deploy. Your InvokeAI UI and API will be reachable at `https://example-app.klutch.sh`; attach a custom domain if desired.

Health checks and production tips

  • Add a /health or lightweight status route in your proxy to monitor uptime.
  • For GPU use, verify CUDA drivers and match the base image version to your hardware.
  • Monitor disk usage on /app/models and /app/outputs; resize volumes before they fill.
  • Pin Python/Node versions and lockfiles for reproducible builds.
  • Enforce HTTPS at the edge and restrict access if your deployment hosts private models.

InvokeAI on Klutch.sh combines reproducible Docker builds with managed secrets, persistent model/output storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 9090 for the app (8000 externally for any TCP companions), you can deliver GPU-ready image generation without extra YAML or workflow overhead.