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