Installing Horreum on bare-metal machine

This guide documents production installation on bare-metal (or virtualized) server.

Setup database

You need PostgreSQL 12 (or later) installed; setup is out of scope of this guide. Create a new database for the application called horreum and limited-priviledge user appuser with a secure password:

export PGHOST=
export PGPORT=5432
export PGUSER=dbadmin
export PGPASSWORD="Curr3ntAdm!nPwd"
psql -c "CREATE DATABASE horreum" postgres
export PGDATABASE=horreum
psql -c "CREATE ROLE \"appuser\" noinherit login password 'SecurEpaSSw0!2D';" postgres

Now set up database structure using the scripts in resources directory. Keep the value used in DBSECRET secret, too.

export DBSECRET=$(cat /dev/random | head -c 33 | base64)
psql -f structure.sql
psql -f auxiliary.sql
psql -c "INSERT INTO dbsecret (passphrase) VALUES ('$DBSECRET');"
psql -f policies.sql
psql -c "GRANT select, insert, delete, update ON ALL TABLES IN SCHEMA public TO \"appuser\";"
psql -c "REVOKE ALL ON dbsecret FROM \"appuser\";"
psql -c "GRANT ALL ON ALL sequences IN SCHEMA public TO \"appuser\";"

Now you need to setup a Keycloak user and database:

psql -c "CREATE ROLE \"keycloakuser\" noinherit login password 'An0th3rPA55w0rD';"
psql -c "CREATE DATABASE keycloak WITH OWNER = 'keycloakuser';"

Keycloak setup

Before starting Keycloak you should adjust the realm definition; for clients horreum and horreum-ui you need to adjust these URLs:

For complete Keycloak setup please refer to Keycloak Getting Started - you can also use existing Keycloak instance.

To import the realm use these system properties:

./bin/standalone.sh \
    -Dkeycloak.profile.feature.upload_scripts=enabled \
    -Dkeycloak.migration.action=import \
    -Dkeycloak.migration.provider=singleFile \
    -Dkeycloak.migration.file=/path/to/keycloak-horreum.json \

When Keycloak starts you should access its admin console and create team roles, users and assign them appropriatelly. For correct integration with Grafana please remember to set email for each user (this will be used purely to match Grafana identities).

You should also open horreum client, switch to ‘Credentials’ tab and record the Secret (UUID identifier).

Starting Horreum

Horreum is a Quarkus application and is configured using one of these:

You should set up these variables:

# Do not use DB superuser! SQL executed by Horreum might be compromised.
# Secret generated during database setup
# This URL must be accessible from Horreum, but does not have to be exposed to the world
# Make sure to include the /auth path. This URL must be externally accessible.
# Secret found in Keycloak console
# You might also want to set the IP the webserver is listening to

If you’re not running Horreum behind a trusted proxy providing edge TLS termination you should set up Quarkus to use HTTPS; Check out certificates configuration options.

With all this in you can finally start Horreum as any other Java application (note: dependencies in repo/target/lib/ must be present):

java -jar repo/target/repo-1.0.0-SNAPSHOT-runner.jar