Installation

Prerequisites

  • Installation targets Debian ≥ 11
  • System ulimit should be raised to minimum 65536
# Append these lines to /etc/security/limits.conf
* soft nofile 65535
* hard nofile 65535

Installation Steps

1. Install Docker

As root, install Docker:

curl -fsSL https://framagit.org/interhop/libre-data-hub/libredatahub/-/raw/3.0.0/install_docker.sh | sh

2. Clone and Configure

As any user in the docker group, clone and configure:

git clone --branch 3.0.0 --single-branch https://framagit.org/interhop/libre-data-hub/libredatahub.git && cd libredatahub

3. Configure Authentication and Environment

Copy and configure the template files:

  1. Authentication: Copy application-auth.yml from either:
    • template.application-auth-oidc.yml for OIDC (e.g., Keycloak)
    • template.application-auth-simple.yml for basic authentication
  2. Environment: Copy .env from template.env with your values

4. Start LibreDataHub 

LDH_UID=$(id -u) DOCKER_GID=$(getent group docker | cut -d: -f3) COMPOSE_PROFILES=ldh,myst,postgres,monitoring,airflow,llm docker compose up -d

Available Profiles:

  • ldh [mandatory]: Jupyter, RStudio, Code-server, CloudBeaver
  • postgres [optional]: PostgreSQL database with CitusDB extension (or use external database)
  • monitoring [optional]: Grafana, Loki, PostgreSQL metrics
  • airflow [optional]: Apache Airflow workflow scheduler
  • llm [optional]: Ollama for local LLM inference (requires GPU)

5. Configure Reverse Proxy (Optional)

Generate nginx configuration:

# Note: .env variables must be configured first
./install_nginx.sh

6. Setup SSL (Optional) 

apt-get install -y nginx certbot python3-certbot-nginx
certbot --nginx

Upgrade

Releases follow semantic versioning. To upgrade:

  1. Read the CHANGELOG for breaking changes

  2. Execute upgrade commands:

# Fetch and checkout new version
git fetch --tags
git checkout 3.0.0

# Pull new images
LDH_UID=$(id -u) DOCKER_GID=$(getent group docker | cut -d: -f3) COMPOSE_PROFILES=ldh,myst,postgres,monitoring,airflow,llm docker compose pull

# Stop current containers
LDH_UID=$(id -u) DOCKER_GID=$(getent group docker | cut -d: -f3) COMPOSE_PROFILES=ldh,myst,postgres,monitoring,airflow,llm docker compose down

# Start with new version
LDH_UID=$(id -u) DOCKER_GID=$(getent group docker | cut -d: -f3) COMPOSE_PROFILES=ldh,myst,postgres,monitoring,airflow,llm docker compose up -d

Users and Groups

LDH groups must meet the below rules:

  • <LDH_INSTANCE>_ADMIN_LDH: for libredatahub superuser, including user session management
  • <LDH_INSTANCE>_LDH_<projectname>: user with in this group will access to projectname
  • <LDH_INSTANCE>_ADMIN_LDH_<projectname>: admin of the projectname

Where <LDH_INSTANCE> is defined in the .env file.

IMPORTANT: Follow this guide to setup keycloak groups or use the template if you use basic auth.

External Database

To use an external PostgreSQL database instead of the built-in instance, configure in .env:

POSTGRES_HOST=your-external-host
POSTGRES_PORT=5432

GPU Support

LibreDataHub provides GPU acceleration for AI/ML workloads when NVIDIA_GPU_COUNT > 0 in your environment configuration.

GPU support enables:

  • PyTorch and TensorFlow GPU acceleration
  • Ollama LLM inference with GPU
  • High-performance deep learning workflows

Documentation

For more detailed information, see the full documentation on GitLab.