Skip to content
Klutch.sh Docs

Deploying OpenWebUI

OpenWebUI is an open-source web interface for running and interacting with text-to-image models and other generative model backends. It provides a browser UI for submitting prompts, browsing models, and managing jobs. Deploying OpenWebUI on Klutch.sh with a Dockerfile allows full control over the runtime, model storage, and compute configuration (CPU or GPU).

Prerequisites

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your OpenWebUI project (or the official repo cloned into your repository)
  • Basic knowledge of Docker and Git
  • (Recommended) GPU compute if planning to run models that require accelerated inference
  • Persistent volume for storing model files and cached artifacts

1. Project layout

A minimal repository layout for OpenWebUI:

openwebui/
├─ Dockerfile
├─ start.sh
├─ requirements.txt
└─ (optional) config/  # custom config, presets, themes

Place any custom settings, themes, or startup scripts in the repo so Klutch.sh can build the image.

2. Sample Dockerfile

The following Dockerfile demonstrates a simple, reproducible build. Adjust Python version, packages, and build steps to match the OpenWebUI version being used.

FROM python:3.11-slim


# Basic system deps often required for models and WebUIs
RUN apt-get update && apt-get install -y --no-install-recommends \
    git build-essential libsndfile1 ffmpeg curl ca-certificates && \
    rm -rf /var/lib/apt/lists/*


WORKDIR /app


# Copy project files
COPY . /app


# Install Python deps
RUN pip install --no-cache-dir -r requirements.txt


# Create models directory for persistent mounts
RUN mkdir -p /models /data


EXPOSE 3000


# Small entrypoint wrapper to ensure model dir exists and then start the server
COPY start.sh /usr/local/bin/start-openwebui.sh
RUN chmod +x /usr/local/bin/start-openwebui.sh


CMD ["/usr/local/bin/start-openwebui.sh"]

Example start.sh (adjust the startup command to the project):

#!/usr/bin/env bash
set -e


# Ensure mounted directories exist
mkdir -p /models /data


# Example: start the OpenWebUI server (replace with actual CLI)
# If using uvicorn/gunicorn or a bundled server, call that here
python -m openwebui.server --host 0.0.0.0 --port ${PORT:-3000} --models-dir /models

3. Models and Persistent Storage

OpenWebUI relies on model files that are large and should be persisted across deployments. Use Klutch.sh Volumes to attach persistent storage:

  1. In your Klutch.sh app settings, create a new volume (for example openwebui-models).
  2. Mount the volume into the container path /models (or the path your app expects).
  3. Optionally create a second volume for /data or /cache to separate models and runtime cache.

Mount example:

/models  ←  openwebui-models
/data    ←  openwebui-data

When the app starts, models in /models will be available to the server. For first-time boot, upload model files into the volume (via an init job or by seeding the repo with smaller test models).

4. GPU vs CPU: Compute selection

  • For heavy models, select GPU compute (NVIDIA) in the Klutch.sh app creation step. Ensure the chosen image includes CUDA/cuDNN-compatible packages or use an appropriate base image provided by the model vendor.
  • For CPU-only usage, use the python:3.11-slim image and select CPU compute. Performance will be limited.

If using GPU, prefer a base image such as nvidia/cuda:XX.YY-base or a PyTorch/CUDA image that matches the drivers on the host. Verify Klutch.sh supports GPU runtime and the correct driver stack.

5. Environment Variables

Set common environment variables in the Klutch.sh dashboard:

  • PORT — the port your app listens on (defaults to 3000 in the example)
  • MODELS_DIR — optional path if the app supports a configurable models dir
  • Any keys for model hosting services, telemetry, or authentication

6. Deploying to Klutch.sh

  1. Push your repo (including Dockerfile and startup scripts) to GitHub.
  2. In the Klutch.sh dashboard, create a new app and connect the repository.
  3. Set the build context and Dockerfile path if not at the repo root.
  4. Configure the app port (e.g., 3000).
  5. Add environment variables and attach the persistent volume(s) (/models, /data).
  6. If needed, select GPU compute for the app.
  7. Click “Create” to start the build and deployment. Klutch.sh will build the image and run the container.

7. Post-deployment & model management

  • Use the provided Klutch.sh URL to access the OpenWebUI interface.
  • Upload or copy model files into the mounted volume (/models) if they were not seeded during build.
  • For large model transfers, consider uploading to object storage then copying into the attached volume inside a short-lived job or init container.

8. Security and best practices

  • Limit external access to model management endpoints; expose only the UI/API endpoints needed for end users.
  • Use environment variables for secrets and never commit credentials to the repo.
  • Use separate volumes for models and ephemeral caches to simplify backups and restores.
  • Monitor resource usage and scale compute if users experience high latency.

Resources