Knowledge base / Getting started

Installation with Docker or Podman

From the images to the running container, including servers without internet access.

This guide uses docker compose. With Podman, replace it with sudo podman-compose; everything else stays the same.

1. Create the folders

sudo mkdir -p /opt/contracthub/{db,files}
sudo chown 70:70 /opt/contracthub/db && sudo chmod 700 /opt/contracthub/db
sudo chown 1000:1000 /opt/contracthub/files
cd /opt/contracthub

UID 70 is the user postgres in the database image, UID 1000 the user of the application.

2. Get the images

You receive the registry address and the credentials with your trial access or license.

docker login <registry>
docker pull <registry>/contracthub:<version>
docker pull postgres:16-alpine

Always enter a fixed version, not latest. That way it is clear what is running, and going back is one line.

Servers without internet access

Every release comes with a bundle contracthub-images-<version>.tar.gz containing both images, plus a checksum. Copy both files to the server:

sha256sum -c contracthub-images-<version>.tar.gz.sha256
docker load -i contracthub-images-<version>.tar.gz

The images are then called localhost/contracthub:<version> and localhost/postgres:16-alpine. Use these names in compose.yaml.

3. Generate the secrets

openssl rand -hex 24      # database password
openssl rand -base64 48   # SESSION_SECRET
openssl rand -base64 32   # SECRETS_ENCRYPTION_KEY

4. Configuration

/opt/contracthub/postgres.env:

POSTGRES_DB=contracthub
POSTGRES_USER=contracthub
POSTGRES_PASSWORD=<database password>

/opt/contracthub/contracthub.env:

# Address at which users reach Kontris
APP_BASE_URL=https://contracthub.example.com
TZ=Europe/Berlin
# 1 = exactly one reverse proxy in front
TRUST_PROXY=1

DATABASE_URL=postgres://contracthub:<database password>@contracthub-db:5432/contracthub
SESSION_SECRET=<second value>
SECRETS_ENCRYPTION_KEY=<third value>

# Sign-in: local accounts only at first, single sign-on is added later
LOCAL_AUTH_ENABLED=true
OIDC_ENABLED=false

MAIL_ENABLED=false
FILE_STORAGE_PATH=/data/files

Write values without quotes and put comments on their own lines. Then protect the files:

sudo chmod 600 contracthub.env postgres.env

/opt/contracthub/compose.yaml:

name: contracthub

services:
  contracthub-db:
    image: postgres:16-alpine
    container_name: contracthub-db
    restart: always
    env_file: postgres.env
    security_opt: [no-new-privileges:true]
    volumes:
      - ./db:/var/lib/postgresql/data
    networks: [db]
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -q -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
      interval: 10s
      timeout: 5s
      retries: 5

  contracthub:
    image: <registry>/contracthub:<version>
    container_name: contracthub
    restart: always
    env_file: contracthub.env
    user: '1000:1000'
    security_opt: [no-new-privileges:true]
    cap_drop: [ALL]
    ports:
      # reachable locally only; the reverse proxy forwards to it
      - '127.0.0.1:3000:3000'
    volumes:
      - ./files:/data/files
    networks: [db, default]
    depends_on:
      - contracthub-db

networks:
  db:
    internal: true

The database is attached to the internal network db only and cannot be reached from outside. On systems with SELinux (RHEL, Fedora) append :Z to the volumes, for example ./files:/data/files:Z.

5. Start

docker compose up -d
docker compose ps
docker compose logs -f contracthub

Both containers must be running, the database with the status healthy. A single restart of the application right after the first start is normal if the database was not ready yet. The log shows “Kontris … started” with an overview of the settings. If a value is missing or invalid, the application exits with a message that names the variable.

With Podman, this starts the containers after a server reboot:

sudo systemctl enable podman-restart.service

Continue with First sign-in and license.

As of 2026-11-15 · Stuck? Write to us