Install Verlihub with Docker 🇬🇧 🇨🇳 🇮🇳 🇪🇸 🇨🇿 🇩🇪 🇳🇱 🇫🇷 🇮🇹 🇵🇱 🇷🇴 🇷🇺

What This Guide Builds

This guide creates a Docker based Verlihub installation from the official Verlihub/verlihub source tree. The container compiles Verlihub with CMake, runs the installed vh helper, stores hub files under /var/lib/verlihub, and uses a separate MariaDB container for the Verlihub database.

The upstream repository currently provides source code, CMake build instructions, install notes, and the vh management script. It does not ship a ready Docker Compose stack in the repository root, so the safest Docker setup is to build your own image from the official source and keep database state in named volumes.

Before You Start

• Install Docker Engine and Docker Compose on the host.
• Choose the public hub hostname before running the Verlihub wizard. Example: hub.example.org.
• Open the hub port on the host firewall. Classic NMDC commonly uses 411/tcp; many container deployments use 4111/tcp to avoid privileged low ports.
• Decide where persistent data belongs. The examples below use named Docker volumes for MariaDB and Verlihub configuration.
• Keep database passwords in a private .env file. Do not commit that file to Git.

Create The Docker Project Directory

Create one directory for the build files. The directory can live anywhere on the Docker host.

 mkdir -p verlihub-docker
cd verlihub-docker
touch Dockerfile docker-compose.yml .env
chmod 600 .env 

Add database values to .env. Use your own passwords.

 MARIADB_ROOT_PASSWORD=change-root-password
MARIADB_DATABASE=verlihub
MARIADB_USER=verlihub
MARIADB_PASSWORD=change-hub-password 

Create The Verlihub Dockerfile

The official install notes list GCC, CMake, MySQL client libraries, OpenSSL, ICU, Make, ZLib, PCRE, GetText, MaxMindDB, and optional Lua as the important build dependencies. The Dockerfile below uses a build stage for compilers and a smaller runtime stage for the installed hub.

 FROM debian:12 AS build

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        cmake \
        default-libmysqlclient-dev \
        g++ \
        gettext \
        git \
        libasprintf-dev \
        libicu-dev \
        liblua5.2-dev \
        libmaxminddb-dev \
        libpcre3-dev \
        libssl-dev \
        make \
        zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

RUN git clone --depth=1 https://github.com/Verlihub/verlihub.git /src/verlihub

RUN cmake -S /src/verlihub -B /src/verlihub/build \
        -DCMAKE_INSTALL_PREFIX=/usr/local \
        -DUSE_TLS_PROXY=OFF \
        -DUSE_FEARTLS_PROXY=OFF \
    && cmake --build /src/verlihub/build -j"$(nproc)" \
    && cmake --install /src/verlihub/build

FROM debian:12

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        bash \
        ca-certificates \
        default-mysql-client \
        gettext \
        libicu72 \
        liblua5.2-0 \
        libmaxminddb0 \
        libpcre3 \
        libssl3 \
        procps \
        zlib1g \
    && rm -rf /var/lib/apt/lists/*

COPY --from=build /usr/local /usr/local

RUN ldconfig \
    && useradd -r -m -d /var/lib/verlihub -s /bin/bash verlihub

USER verlihub
WORKDIR /var/lib/verlihub
VOLUME ["/var/lib/verlihub"]
EXPOSE 411 4111 4112

CMD ["bash", "-lc", "vh --run /var/lib/verlihub"] 

Enable -DUSE_TLS_PROXY=ON only when you also build and configure the TLS proxy dependency required by your Verlihub branch. Do not turn on TLS flags and assume NMDCS works without certificates, proxy binaries, and tested firewall rules.

Create docker-compose.yml

This Compose file starts MariaDB and the Verlihub container on one private Docker network. It maps host port 4111 to container port 4111. Change the port if your hub will listen on a different value.

 services:
  db:
    image: mariadb:10.11
    restart: unless-stopped
    env_file: .env
    environment:
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${MARIADB_DATABASE}
      MARIADB_USER: ${MARIADB_USER}
      MARIADB_PASSWORD: ${MARIADB_PASSWORD}
    volumes:
      - verlihub-db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "127.0.0.1", "-u", "root", "-p${MARIADB_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 10

  verlihub:
    build: .
    restart: unless-stopped
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "4111:4111/tcp"
    volumes:
      - verlihub-config:/var/lib/verlihub
    command: ["bash", "-lc", "vh --run /var/lib/verlihub"]

volumes:
  verlihub-db:
  verlihub-config: 

Build The Image

 docker compose build
docker compose up -d db 

Wait until MariaDB is healthy before running the Verlihub install wizard.

 docker compose ps
docker compose logs -f db 

Run The Verlihub Install Wizard

The vh --install helper is interactive. Run it once, answer the database questions, then save the generated configuration into the mounted Verlihub volume.

 docker compose run --rm verlihub bash
vh --install 

Use these values in the wizard when it asks for database access:

If the wizard asks for MySQL administrator credentials, use root and MARIADB_ROOT_PASSWORD from .env. The official vh script can create the database, grant permissions, create tables, write dbconfig, register the master user, and write the initial hub settings.

Start The Hub

 docker compose up -d
docker compose logs -f verlihub 

After startup, test the public port from outside the Docker host. If the host firewall or provider firewall blocks the port, the container can be healthy while DC++ clients still cannot connect.

 docker compose exec verlihub vh --status /var/lib/verlihub
docker compose exec verlihub vh --getconf hub_name /var/lib/verlihub
docker compose exec verlihub vh --getconf listen_port /var/lib/verlihub 

Daily Operations

Upgrade Verlihub Later

Back up the database and configuration volume first. Then rebuild the image from the latest official source and restart the hub.

 docker compose exec db mariadb-dump -u root -p verlihub > verlihub-before-upgrade.sql
docker compose build --pull --no-cache verlihub
docker compose up -d verlihub
docker compose logs -f verlihub 

If a new Verlihub release changes database tables, read the upstream release notes before replacing a production hub. Keep one tested backup that can be restored without pulling fresh images from the internet.

Common Problems

• The hub starts, but clients cannot connect. Check the Compose port mapping, host firewall, provider firewall, and the listen_port value in Verlihub.
• The wizard cannot connect to MySQL. Use db as the hostname from inside the Verlihub container. Do not use localhost unless MariaDB runs in the same container.
• The hub loses settings after rebuild. Confirm the verlihub-config volume is mounted at /var/lib/verlihub.
• Characters look wrong in chat. Set the same database charset and hub locale that your community uses, then restart the hub.
• NMDCS does not work yet. Verlihub TLS proxy support needs the matching proxy build, certificates, ports, and client testing. Get plain NMDC stable first.

Source Links

• Official Verlihub repository
• Official Verlihub install notes
• Official Verlihub wiki