# Huly

> All-in-one project management platform.

- Category: Productivity & Collaboration
- Difficulty: advanced
- Components: huly, mongodb, minio, elastic
- Tags: huly, project-management, linear-alternative, issues
- Source: https://docker.recipes/productivity/huly

## Overview

Huly is an open-source, all-in-one project management platform that serves as a modern alternative to Linear, combining issue tracking, project management, documentation, and team collaboration in a single unified interface. Built for modern development teams, Huly integrates project planning with real-time communication features including chat, virtual office spaces, and collaborative documents, making it a comprehensive workspace solution rather than just another task tracker.

This stack combines Huly's application server with MongoDB for flexible document storage, MinIO for S3-compatible file storage, and Elasticsearch for powerful full-text search capabilities. MongoDB handles Huly's dynamic project data, user information, and issue structures with its schema-flexible document model, while MinIO stores file attachments, images, and document assets with high-performance object storage. Elasticsearch powers Huly's advanced search functionality across projects, issues, documents, and chat messages, enabling teams to quickly locate information across their entire workspace.

Development teams, startups, and organizations seeking a self-hosted Linear alternative will find this configuration particularly valuable, as it provides enterprise-grade project management capabilities without vendor lock-in or per-user pricing. The combination delivers real-time collaboration features, advanced search across all content types, and the scalability to handle growing teams and complex project hierarchies while maintaining complete data ownership and customization control.

## Features

- Linear-style issue tracking with customizable project workflows, sprints, and roadmap visualization
- Real-time collaborative documents with MongoDB change streams for instant synchronization
- Full-text search across issues, projects, documents, and chat using Elasticsearch's relevance scoring
- S3-compatible file attachment storage via MinIO with versioning and lifecycle management
- Virtual office and team chat integration with persistent message history in MongoDB
- Flexible project schema evolution using MongoDB's document-based data model
- High-performance file serving and thumbnail generation through MinIO's object storage
- Advanced search aggregations and filtering across all project data via Elasticsearch

## Use cases

- Self-hosted Linear alternative for development teams wanting data ownership and customization
- Startup project management hub combining issue tracking with team communication and documentation
- Enterprise teams requiring on-premises project management with advanced search capabilities
- Open-source projects needing integrated issue tracking, documentation, and contributor collaboration
- Consulting firms managing multiple client projects with unified communication and file storage
- Remote teams utilizing virtual office features alongside traditional project management workflows
- Organizations transitioning from multiple tools (Jira, Slack, Confluence) to a unified platform

## Prerequisites

- Minimum 6GB RAM (2GB for Elasticsearch, 2GB for Huly, 1GB each for MongoDB and MinIO)
- Docker and Docker Compose with support for named volumes and inter-container networking
- Linux host with vm.max_map_count=262144 for Elasticsearch memory mapping requirements
- Available ports 8087 for Huly web interface and internal container communication
- Understanding of object storage concepts for MinIO configuration and file management
- Basic MongoDB knowledge for backup procedures and user management setup

## docker-compose.yml

```yaml
services:
  huly:
    image: hardcoreeng/huly:latest
    container_name: huly
    restart: unless-stopped
    ports:
      - "8087:8087"
    environment:
      MONGO_URL: mongodb://mongodb:27017
      MINIO_ENDPOINT: minio
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: ${MINIO_PASSWORD}
      ELASTIC_URL: http://elastic:9200
    depends_on:
      - mongodb
      - minio
      - elastic

  mongodb:
    image: mongo:6
    container_name: huly-mongo
    restart: unless-stopped
    volumes:
      - huly_mongo:/data/db

  minio:
    image: minio/minio:latest
    container_name: huly-minio
    command: server /data
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD}
    volumes:
      - huly_minio:/data

  elastic:
    image: elasticsearch:8.11.0
    container_name: huly-elastic
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"
    volumes:
      - huly_elastic:/usr/share/elasticsearch/data

volumes:
  huly_mongo:
  huly_minio:
  huly_elastic:
```

## .env

```bash
MINIO_PASSWORD=changeme123
```

## Usage notes

- Docs: https://huly.io/docs
- Access at http://localhost:8087
- Linear-like issue tracking with projects, sprints, and roadmaps
- Documents, chat, and virtual office features
- Increase Elasticsearch memory: vm.max_map_count=262144
- Modern UI with real-time collaboration

## Troubleshooting

- Elasticsearch container exits with bootstrap checks failed: Run 'sudo sysctl -w vm.max_map_count=262144' and add to /etc/sysctl.conf for persistence
- Huly cannot connect to MongoDB: Verify container networking and ensure MongoDB container is fully started before Huly initialization
- File uploads failing to MinIO: Check MINIO_PASSWORD environment variable matches between Huly and MinIO containers
- Search functionality not working: Confirm Elasticsearch container health and verify ELASTIC_URL environment variable format
- Huly web interface showing 502 errors: Check container logs for port binding conflicts and ensure 8087 is not in use by other services
- MongoDB connection timeouts: Increase MongoDB container memory allocation if handling large project datasets or multiple concurrent users

