Skip to content
Klutch.sh Docs

Deploying a LabelStudio App

Introduction

Label Studio is an open-source data labeling and annotation platform. Deploying Label Studio with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for projects and datasets—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Label Studio code/config (GitHub is the only supported git source)
  • Docker familiarity and Python 3.10+ knowledge
  • Database credentials (PostgreSQL recommended) for production
  • Storage for media, annotations, and logs

For onboarding, see the Quick Start.

Architecture and ports

  • Label Studio serves HTTP on port 8080; set the internal container port to 8080.
  • PostgreSQL and Redis (optional) should run as separate Klutch.sh TCP apps, exposed on port 8000 and connected internally on 5432 and 6379.
  • Persistent storage is required for media uploads and project data.

Repository layout

labelstudio/
├── Dockerfile              # Must be at repo root for auto-detection
├── requirements.txt
├── start.sh                # Optional helper
├── data/                   # Media and project files (mount as volume)
└── .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 and run locally before pushing to GitHub:

Terminal window
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
label-studio start --port 8080

Optional start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec label-studio start --port 8080 --host 0.0.0.0

Make it executable with chmod +x start.sh.

Dockerfile for Label Studio (production-ready)

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

FROM python:3.11-slim


WORKDIR /app


RUN apt-get update && apt-get install -y build-essential git && rm -rf /var/lib/apt/lists/*


COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt


COPY . /app


ENV PORT=8080


EXPOSE 8080
CMD ["label-studio", "start", "--port", "8080", "--host", "0.0.0.0"]

Notes:

  • Add system packages if your labeling tasks need them (e.g., ffmpeg for audio/video).
  • If you prefer gunicorn, replace the CMD with a gunicorn start command.

Environment variables (Klutch.sh)

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

  • PORT=8080
  • LABEL_STUDIO_HOST=https://example-app.klutch.sh
  • DJANGO_DB=default
  • POSTGRES_PASSWORD=<db-password>
  • POSTGRES_USER=<db-user>
  • POSTGRES_NAME=<db-name>
  • POSTGRES_HOST=<db-host>
  • POSTGRES_PORT=5432
  • REDIS_URL=redis://<user>:<password>@<host>:<port> (if using Redis)
  • SECRET_KEY=<secure-django-secret>

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=pip install -r requirements.txt
  • NIXPACKS_START_CMD=label-studio start --port 8080 --host 0.0.0.0
  • NIXPACKS_PYTHON_VERSION=3.11

These keep Label Studio 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/data — required for media uploads, annotations, and project files.
  • /app/logs — optional if you store logs on disk.

Ensure these paths are writable inside the container.

Deploy Label Studio 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 Label Studio.
  3. Set the internal port to 8080.
  4. Add the environment variables above (database, Redis if used, secret key, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/data (and /app/logs if used), selecting sizes that fit your dataset and log needs.
  6. Deploy. Your Label Studio instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For PostgreSQL/Redis on Klutch.sh, create separate TCP apps, expose them on port 8000, and point POSTGRES_HOST or REDIS_URL to those endpoints (internal ports 5432/6379).

Sample API usage

Create a project via API (replace placeholders):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/projects" \
  -H "Authorization: Token <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Image Classification", "description": "Label product photos"}'

Health checks and production tips

  • Add a reverse proxy probe on / or /health to verify the app responds.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Use strong SECRET_KEY and rotate tokens regularly; store secrets only in Klutch.sh.
  • Monitor disk usage on /app/data and resize volumes before they fill.
  • Back up PostgreSQL and uploaded data regularly; do not rely on container filesystems for durability.

Label Studio on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8080 configured, you can run scalable data labeling workflows without extra YAML or workflow overhead.