# Label Studio + PostgreSQL + Redis

> Data labeling platform with enterprise features for ML training data.

- Category: AI & Machine Learning
- Difficulty: intermediate
- Components: label-studio, postgresql, redis, nginx
- Tags: label-studio, annotation, labeling, ml-data, training-data
- Source: https://docker.recipes/ai-ml/label-studio-enterprise

## Overview

Label Studio is an open-source data labeling platform developed by Heartex that enables teams to create high-quality training datasets for machine learning projects. Originally launched in 2019, Label Studio has become a leading solution for annotating text, images, audio, video, and time series data, supporting over 20 different ML tasks from text classification to object detection. The platform provides a web-based interface where teams can configure custom labeling templates, manage annotator workflows, and export labeled data in formats compatible with popular ML frameworks like TensorFlow, PyTorch, and scikit-learn.

This enterprise-grade stack combines Label Studio with PostgreSQL for robust data persistence and Redis for high-performance caching and session management. PostgreSQL stores all project configurations, user data, annotations, and metadata with ACID compliance, ensuring data integrity even during concurrent labeling sessions. Redis accelerates the platform by caching frequently accessed data, managing real-time collaboration features, and handling background task queues for data import/export operations. NGINX serves as the reverse proxy, efficiently delivering static assets like images and documents while load balancing requests to the Label Studio application server.

Data science teams, ML engineers, and organizations building custom AI models should deploy this stack when they need a scalable, production-ready annotation platform. Unlike basic labeling tools, this configuration supports enterprise features like user authentication, project-based access control, annotation quality metrics, and API integrations. The PostgreSQL backend enables complex queries for annotation analytics and audit trails, while Redis ensures responsive performance even with large datasets and multiple concurrent annotators working on the same projects.

## Features

- Multi-format data support with configurable labeling interfaces for text, images, audio, video, HTML, and time series data
- PostgreSQL-backed project management with user roles, annotation versioning, and detailed audit trails
- Redis-powered real-time collaboration enabling multiple annotators to work simultaneously without conflicts
- NGINX-optimized file serving for large media assets with efficient caching and compression
- Advanced annotation quality controls including inter-annotator agreement scoring and review workflows
- API-first architecture with RESTful endpoints for automated data import, export, and integration with ML pipelines
- Flexible labeling templates supporting custom taxonomies, multi-class classification, named entity recognition, and bounding box annotations
- Enterprise authentication integration with LDAP, SSO, and role-based access control for secure multi-team environments

## Use cases

- Computer vision teams annotating large image datasets for object detection, semantic segmentation, and facial recognition models
- NLP projects requiring text classification, named entity recognition, sentiment analysis, and document categorization
- Healthcare organizations labeling medical images, patient records, and clinical trial data with strict compliance requirements
- Autonomous vehicle companies creating training datasets for road sign detection, lane marking, and obstacle identification
- Content moderation teams at social media platforms labeling text posts, images, and videos for harmful content detection
- Research institutions conducting longitudinal studies requiring consistent data annotation across multiple researchers
- E-commerce companies building recommendation systems by labeling product images, descriptions, and customer review sentiment

## Prerequisites

- Minimum 2GB RAM (4GB+ recommended) to support PostgreSQL database operations and Label Studio's web interface
- Docker Engine 20.10+ and Docker Compose 2.0+ for container orchestration and volume management
- Available ports 80, 8080, 5432, and 6379 for NGINX, Label Studio, PostgreSQL, and Redis respectively
- Understanding of data annotation workflows and familiarity with ML training data requirements
- Basic knowledge of PostgreSQL administration for database maintenance and backup procedures
- Storage capacity planning based on dataset size - PostgreSQL data, Redis memory, and Label Studio file storage requirements

## docker-compose.yml

```yaml
services:
  label-studio:
    image: heartexlabs/label-studio:latest
    environment:
      - DJANGO_DB=default
      - POSTGRE_HOST=postgres
      - POSTGRE_PORT=5432
      - POSTGRE_NAME=labelstudio
      - POSTGRE_USER=${POSTGRES_USER}
      - POSTGRE_PASSWORD=${POSTGRES_PASSWORD}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true
      - LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/label-studio/files
    volumes:
      - ls-data:/label-studio/data
      - ls-files:/label-studio/files
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - redis
    networks:
      - labelstudio-network
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=labelstudio
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - labelstudio-network
    restart: unless-stopped

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data
    networks:
      - labelstudio-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ls-files:/files:ro
    ports:
      - "80:80"
    depends_on:
      - label-studio
    networks:
      - labelstudio-network
    restart: unless-stopped

volumes:
  ls-data:
  ls-files:
  postgres-data:
  redis-data:

networks:
  labelstudio-network:
    driver: bridge
```

## .env

```bash
# Label Studio
POSTGRES_USER=labelstudio
POSTGRES_PASSWORD=secure_postgres_password

# Create superuser on first run:
# docker exec -it label-studio label-studio user create
```

## Usage notes

- Label Studio at http://localhost:8080
- Create first user via signup
- Import data from local files or cloud
- Support for text, image, audio, video
- Export in multiple formats

## Troubleshooting

- Label Studio shows 'Database connection failed': Check POSTGRES_USER and POSTGRES_PASSWORD environment variables match between services
- Redis connection timeout errors: Increase Redis memory limit or check if Redis container has sufficient RAM allocation
- File upload failures with large media assets: Configure NGINX client_max_body_size and Label Studio's LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED setting
- PostgreSQL 'too many connections' error: Adjust max_connections in PostgreSQL config or implement connection pooling in Label Studio
- Slow annotation interface loading: Verify Redis is properly connected and consider increasing Redis memory or using Redis persistence
- NGINX 502 Bad Gateway errors: Ensure Label Studio container is fully started before NGINX attempts to proxy requests

