Longhorn

advanced

Cloud-native distributed block storage for Kubernetes.

Overview

Longhorn is an open-source, cloud-native distributed block storage system designed specifically for Kubernetes environments. Originally developed by Rancher Labs and now a CNCF sandbox project, Longhorn addresses the persistent storage challenges in containerized environments by providing enterprise-grade features like snapshots, backups, and disaster recovery through a lightweight, microservices-based architecture. Unlike traditional storage solutions, Longhorn runs entirely in userspace and leverages existing disk resources on Kubernetes nodes to create replicated block storage. This Docker Compose configuration demonstrates a simplified version of Longhorn's engine component, primarily intended for development and testing purposes. The longhorn-engine container operates in privileged mode to access host devices and provides basic block storage functionality through its launch-simple-longhorn command. While this setup lacks the full distributed capabilities and management features available in a complete Kubernetes deployment, it allows developers to experiment with Longhorn's core storage engine and understand its fundamental operations. This configuration is particularly valuable for developers working on Kubernetes storage solutions, platform engineers evaluating distributed storage options, and DevOps teams who need to understand Longhorn's behavior before deploying it in production Kubernetes clusters. The simplified Docker setup enables rapid prototyping and testing without the complexity of a full Kubernetes environment, making it ideal for development workflows and educational purposes.

Key Features

Userspace block storage engine with direct device access through privileged container mode
Replicated volume architecture supporting multiple copies across different nodes
Snapshot functionality for point-in-time volume recovery and data protection
Incremental backup system with support for S3, NFS, and other external storage backends
Built-in volume encryption using Linux kernel crypto API for data-at-rest protection
Dynamic volume provisioning with automatic replica placement and scheduling
Volume expansion capabilities allowing online resizing without downtime
Disaster recovery features including cross-cluster volume replication and backup restoration

Common Use Cases

1Kubernetes persistent storage for stateful applications like databases and file systems
2Development environment setup for testing storage-dependent applications before Kubernetes deployment
3Bare metal Kubernetes clusters requiring distributed block storage without cloud provider dependencies
4Edge computing scenarios where traditional SAN/NAS storage is unavailable or impractical
5Disaster recovery implementations needing automated backup and cross-site replication
6HomeLab and self-hosted infrastructure requiring enterprise-grade storage features
7Educational environments for learning distributed storage concepts and Kubernetes storage classes

Prerequisites

Docker host with privileged container support and access to block devices
Minimum 4GB RAM and 20GB available disk space for storage operations
Linux kernel version 4.19 or higher with device-mapper and filesystem modules
Understanding of block storage concepts, volumes, and Kubernetes storage classes
Network connectivity on port 9500 for storage engine API communication
Root or sudo access for device mounting and privileged container operations

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1# Longhorn is primarily for Kubernetes
2# This is a development/test setup
3services: 
4  longhorn-engine: 
5    image: longhornio/longhorn-engine:v1.5.3
6    container_name: longhorn-engine
7    privileged: true
8    command: launch-simple-longhorn
9    volumes: 
10      - /dev:/host/dev
11      - longhorn_data:/volume
12    ports: 
13      - "9500:9500"
14
15volumes: 
16  longhorn_data:

.env Template

.env

1# For Kubernetes, use Helm chart instead

Usage Notes

1Docs: https://longhorn.io/docs/
2Designed for Kubernetes - install via Helm: helm install longhorn longhorn/longhorn
3This Docker setup is for development/testing only
4Features: snapshots, backups to S3/NFS, replicated volumes
5Web UI for managing volumes, snapshots, backups
6For bare metal Kubernetes - not cloud managed K8s

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3# Longhorn is primarily for Kubernetes
4# This is a development/test setup
5services:
6  longhorn-engine:
7    image: longhornio/longhorn-engine:v1.5.3
8    container_name: longhorn-engine
9    privileged: true
10    command: launch-simple-longhorn
11    volumes:
12      - /dev:/host/dev
13      - longhorn_data:/volume
14    ports:
15      - "9500:9500"
16
17volumes:
18  longhorn_data:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# For Kubernetes, use Helm chart instead
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/longhorn/run | bash

Troubleshooting

Permission denied accessing /dev devices: Ensure Docker daemon runs with sufficient privileges and host devices are properly mounted
Volume mount failures with 'no space left on device': Check available disk space on Docker host and verify volume size limits
Connection refused on port 9500: Verify firewall settings and ensure container networking allows access to the engine API port
Longhorn engine crashes with device mapper errors: Update kernel to version 4.19+ and ensure device-mapper modules are loaded
Slow volume operations or timeouts: Check disk I/O performance and consider using faster storage backend or adjusting timeout values
Container fails to start with 'launch-simple-longhorn command not found': Verify Longhorn engine image version compatibility and update to v1.5.3 or newer

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

longhorn

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download