Install and start the server

Overview

The Hackolade Model Hub is delivered as a Docker image that you run on a server. Once started, users access the Model Hub from a browser to navigate the data models with capabilities to search, browse, drill-down, where-used, lineage, etc.  The source-of-truth remains the Git repositories where the data models are maintained.

 

You can deploy the Model Hub with Docker Compose, Kubernetes, or any orchestrator that runs containers.  For a straightforward first installation, Docker Compose is recommended.

 

This page explains what each component does and how to configure a typical deployment to connect to a database controlled by the customer while external to the Model Hub container.

 

What gets deployed?

A Model Hub installation is made of different components:

 

Component	Role
model-hub	The Model Hub application. Serves the web UI and APIs. Users connect to this process (default port `3000`)
Database	An external PostgreSQL or Oracle database that stores Model Hub data. You must provision and operate this database yourself.
Filestore volume	Persistent disk space for files the Model Hub keeps on disk (under `/home/node/.hub`). You must retain this volume across restarts and upgrades.
Secrets	Sensitive values such as the database password. Prefer Docker secrets (or your platform’s equivalent) over plain environment variables.

 

 

 

 

 

Pull images

Each newx version of Model Hub is published on DockerHub.  You may specify the version to pull with

 

export MODEL_HUB_VERSION=<target-model-hub-version>
docker pull hackolade/model-hub:$MODEL_HUB_VERSION

 

 

The database can be self-standing (installed on a host) or packaged as a container image.

Quick start with Docker Compose and self-standing PostgreSQL database

The example below deploys the Model Hub application against an external PostgreSQL database. For a quick start with PostgreSQL deployed on the same server, check instructions in the next section below.

 

1. Create the project layout

 

model-hub-deploy/
├── docker-compose.yml
└── secrets/
    └── db_password          # single line: the database password

 

 

Create the password file and do not commit it to source control.

 

 

2. Example of docker-compose.yml

Update DB_CONNECTION (and, if needed, DB_USERNAME) so they match your database host, port, database name, and user.

 

services:
  model-hub:
    image: hackolade/model-hub:$MODEL_HUB_VERSION
    deploy:
      restart_policy:
        condition: always
        delay: 5s
        window: 30s
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: pg
      DB_CONNECTION: pg://<db-host>:5432/<database>
      DB_USERNAME: <db-user>
      DB_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - "model-hub-filestore-data:/home/node/.hub:rw"
    secrets:
      - db_password

networks:
  default:
    name: hub

volumes:
  model-hub-filestore-data: {}

secrets:
  db_password:
    file: ./secrets/db_password

 

 

where:

Setting	Meaning
DB_TYPE	Database driver. Use pg for PostgreSQL or oracledb for Oracle.
DB_CONNECTION	How the application reaches the database. Format depends on the database (see below).
DB_USERNAME	Database user
DB_PASSWORD_FILE	Path inside the container to a file containing the password.
Port 3000	Default HTTP port of the Model HUB process.
Volume /home/node/.hub	File store where an encryption key is saved. This encryption key is used to encrypt sensitive configuration like Git credentials in the database. Must persist across container recreation.

 

 

3. Start the stack

From the directory that contains docker-compose.yml

 

export MODEL_HUB_VERSION=<target-model-hub-version>
docker compose up -d

 

 

What happens:

1. The model-hub container starts and listens on port 3000

2. When the container starts, it creates the database structure that it needs to run properly.

3. Once the setup is done, the application is ready to be used.

 

 

Check status

 

docker compose ps
docker compose logs -f model-hub

 

 

Open the Model Hub

 

http://<server-hostname-or-ip>:3000

 

It is mandatory to place a reverse proxy in front of the Model Hub and terminate TLS there because Model Hub uses service workers in the browser, which forces the use of HTTPS

 

 

4. Connect to the database

The Model Hub connects to a self-standing SQL database that you provide. Provision the database first, then point the application at it.

 

Database checklist

1. Create an empty database (and schema if required by your standards).

2. Create a dedicated user.

3. Grant that user permission to create, alter, and delete tables in its schema, and to read/write those tables — see Pre-requisites

4. Ensure the Model HUB containers can reach the database host and port.

 

PostgreSQL

These environment variables must be configured to connect Model HUB with your PostgreSQL database

 

DB_TYPE=pg
DB_CONNECTION=pg://<db-host>:5432/<database>
DB_USERNAME=<db-user>
DB_PASSWORD_FILE=/run/secrets/db_password

 

Oracle

These environment variables must be configured to connect Model HUB to your Oracle database

 

DB_TYPE=oracledb
DB_USERNAME=<db-user>
DB_PASSWORD_FILE=/run/secrets/db_password
DB_CONNECTION=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<db-host>)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=<service-name>)))

 

 

DB_CONNECTION is an Oracle Connect descriptor (or Easy Connect string).

 

 

Example Compose snippet:

 

model-hub:
  image: hackolade/model-hub:$MODEL_HUB_VERSION
  environment:
    DB_TYPE: oracledb
    DB_USERNAME: <db-user>
    DB_PASSWORD_FILE: /run/secrets/db_password
    DB_CONNECTION: "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=<db-host>)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=<service-name>)))"
  secrets:
    - db_password

 

 

5. Configure health checks

When you run the official Model Hub image with Docker, a health check is already configured. On other platforms (Kubernetes, for example), configure an equivalent probe.

 

The Model Hub listens on port 3000 and exposes a /health endpoint. A successful check is an HTTP `200` response from that endpoint.

 

Model Hub also exposes a /ready endpoint. It responds with an HTTP `200` when Model Hub finishes the setup of the database.

 

Reference health check from the Dockerfile:

 

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e 'fetch(`http://localhost:3000/health\`).then(x=\>x.status===200?process.exit(0):process.exit(1)).catch(()=\>process.exit(1))'

 

 

Equivalent probes:

 

• Kubernetes liveness: HTTP GET on port 3000, path /health
• Kubernetes readiness: HTTP GET on port 3000, path /ready
• Load balancer: HTTP health check on /ready

 

 

6. Verify the installation

 

1. docker compose ps must show that model-hub running.

2. curl -f http://localhost:3000/health must return HTTP 200.

3. Opening http://<host>:3000 in a browser loads the Model Hub UI.

 

 

7. Stop and upgrade

Stop (keep the filestore volume)

 

docker compose down

 

Warning: do not use the flag to delete volumes, which would delete filestore data.

 

Upgrade

 

1. Always back up the database and the filestore volume before upgrading production systems, as described in Data backup

2. Note the new $MODEL_HUB_VERSION from the Hackolade release notes.

3. Pull the matching model-hub image.

4. Update $MODEL_HUB_VERSION then 

 

run docker compose up -d 

 

and the application will restart.

 

 

 

Quick start with Docker Compose and PostgreSQL

To start quickly with Model Hub, just install a PostgreSQL container within the same Docker Compose file. The example below is ready to be copied into your own server. It uses the official PostgreSQL Docker image and already configures Model Hub to authenticate with it.

 

Attention: you should also pay attention that there is a named volume model-hub-db-data for the database.

 

 

services:
  postgres:
    image: postgres/postgres:18.4-alpine
    deploy:
      restart_policy:
        condition: always
        delay: 5s
        window: 30s
    environment:
      POSTGRES_USER: hck_hub
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
      POSTGRES_DB: hck_hub
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hck_hub -d hck_hub"]
      interval: 30s
      timeout: 5s
      retries: 10
      start_period: 5s
    volumes:
      - 'model-hub-db-data:/var/lib/postgresql:rw'
    secrets:
      - db_password

  model-hub:
    image: hackolade/model-hub:$MODEL_HUB_VERSION
    deploy:
      restart_policy:
        condition: always
        delay: 5s
        window: 30s
    ports:
      - "3000:3000"
    environment:
      DB_TYPE: pg
      DB_CONNECTION: pg://postgres:5432/hck_hub
      DB_USERNAME: hck_hub
      DB_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - "model-hub-filestore-data:/home/node/.hub:rw"
    secrets:
      - db_password

networks:
  default:
    name: hub

volumes:
  model-hub-db-data: {}
  model-hub-filestore-data: {}

secrets:
  db_password:
    file: ./secrets/db_password

 

 

With this Docker Compose, the next step is to run it:

 

export MODEL_HUB_VERSION=<target-model-hub-version>
docker compose up -d