Skip to main content

Hanami Docker Installation Guide (up to v1.5.x)

Scope • Clean installation of Hanami 1.5.x on a Linux host.

Prerequisites​

RequirementMandatory?Check / Notes
Sudo access✓sudo -v (or sudo su) should succeed.
Docker Engine✓Docker 24 and above – verify with docker --version.
Elasticsearch 7.14+ / 8✓• Cluster reachable from the host (curl -u user:pwd https://<es-host>:9200). • Service account with index-level read/write rights. • Record host, port, user & password for customer-standalone.yml.
Open TCP port✓Hanami listens on 8080 by default. If you map to 80 set server.port: 80 in customer.yml and ensure the port is free / allowed by the firewall.
Cognizone Nexus access✓Credentials to download hanami-package-X.Y.Z.zip.
External triplestore (GraphDB, Virtuoso, …)optionalOnly if you don’t use Hanami’s embedded store. • SPARQL endpoint must be reachable. • Provide a read/write account for CRUD and SPARQL UPDATE. • Configure in customer-standalone.yml → rdfStore*.
External IAM / OAuth2 (ADFS, Keycloak, …)optionalNeeded only if you import security-iam.yml. • Client ID & secret issued. • Token issuer URI reachable from Hanami.
Paired application (e.g. Catalogue)optionalRequired when you enable hanami.sync.eventTransmission. • Sync API reachable (http://<catalogue-host>:80). • Application user/password configured exactly the same.

Tip —keep optional rows if you plan to add those integrations later; Hanami will ignore unused blocks until you enable the corresponding feature flags.​

1 · Download the artefact​

curl -u <user>:<password> -O \
  https://nexus-direct.cogni.zone/repository/ep-hanami/zone/cogni/ep/hanami/ep-hanami/1.5.0/ep-hanami-1.5.0.zip

2 · Extract the artefact​

unzip ep-hanami-1.5.0.zip

Expected output

  • ep-hanami-1.5.0.tar – Docker image
  • ext/ – default configuration

3 · (If present) stop the current container​

sudo docker stop ep-hanami-container
sudo docker rm   ep-hanami-container

4 · Load the Docker image​

sudo docker load -i ep-hanami-1.5.0.tar

5 · Copy / update configuration​

  1. Backup the current ext, backups, logs directories (if any exists)

    sudo cp -r /opt/hanami-ext      /opt/hanami-ext-backup-$(date +%F)
    sudo cp -r /opt/hanami-backups  /opt/hanami-backups-backup-$(date +%F)
    sudo cp -r /opt/hanami-logs  /opt/hanami-logs-backup-$(date +%F)

  2. Clean the directory (if it exists) (keep only environment‑specific YAMLs)

    sudo find /opt/hanami-ext \( \
        ! -path "/opt/hanami-ext/config" \
        ! -path "/opt/hanami-ext/config/customer.yml" \
        ! -path "/opt/hanami-ext/config/customer-standalone.yml" \
        ! -path "/opt/hanami-ext/config/customer-workflow.yml" \
        ! -path "/opt/hanami-ext/config/security.yml" \
      \) -type f -exec rm -f {} +

Environment‑specific YAMLs should stay:

  • /opt/hanami-ext/config/customer.yml
  • /opt/hanami-ext/config/customer-standalone.yml
  • /opt/hanami-ext/config/security.yml
  1. Copy the new defaults
    sudo cp -r ./ext/* /opt/hanami-ext/

6 · Prepare configuration files (MANDATORY)​

Use existing Environment‑specific YAMLs or modify the example configuration files to match your environment. See examples with oauth installation or Basic Auth installation.

Templates with the suffix .example must be converted to real config files and adjusted:

# Work inside the extracted directory
cd ext/config

# Mandatory main config
cp customer.yml.example customer.yml

# Mandatory security settings
cp security.yml.example security.yml

# Optional profiles – copy the ones you will activate via --spring.profiles.active
cp customer-standalone.yml.example   customer-standalone.yml   # if you use the standalone profile
# cp customer-<yourprofile>.yml.example customer-<yourprofile>.yml  # additional custom profile

Edit each newly created .yml and replace placeholder values (database URL, credentials, API keys, roles, etc.).

Tip: a minimal customer.yml requires at least the server: block and a valid storage: configuration.

External triplestore configuration (optional)​

If you want Hanami to persist data in an external RDF triplestore instead of the embedded store, add the following block to every profile that should connect to it (commonly customer-standalone.yml).

1 · Triplestores with repository/workspace concept (e.g. GraphDB)​

hanami:
  customer:
    template-arguments:
      rdfStore: "http://<host>:7200/repositories/<repository-name>"
      rdfStoreUser: "<username>"
      rdfStorePassword: "<password>"

2 · Plain SPARQL endpoints (e.g. Virtuoso, Fuseki)​

hanami:
  customer:
    template-arguments:
      # Virtuoso
      rdfStore: "http://<host>:8890/sparql"
      # Fuseki – replace <dataset>
      # rdfStore: "http://<host>:3030/<dataset>/sparql"
      rdfStoreUser: "<username>"
      rdfStorePassword: "<password>"

Important:
• The target triplestore or sparql endpoint (and its repository/dataset if applicable) must already exist – Hanami will not create it.
• Make sure the rdfStoreUser account has both read and write permissions.
• Omit rdfStoreUser and rdfStorePassword if the endpoint is publicly accessible without authentication.
• Adapt the URL scheme (HTTP/HTTPS), host, port, and path to match your environment.

When finished, copy the entire ext/ directory to the host location:

sudo cp -r ../ext/* /opt/hanami-ext/

7 · Run the container​

Prepare folders if missing:

sudo mkdir -p /opt/hanami-ext
sudo mkdir -p /opt/hanami-backups
sudo mkdir -p /opt/hanami-logs

Run the container:

sudo docker run -d \
  --name ep-hanami-container \
  --network host \
  --restart unless-stopped \
  -v /opt/hanami-ext:/opt/hanami/ext \
  -v /opt/hanami-backups:/opt/hanami/backups \
  -v /opt/hanami-logs:/opt/hanami/logs \
  ep-hanami:1.5.0 \
  --spring.profiles.active=standalone,workflow

Parameter reference​

FlagPurpose
--nameHuman‑friendly container name.
--network hostPublishes container ports directly on the host. Hanami binds to 8080 by default (see below for overrides).
--restart unless-stoppedAuto‑restarts on failure or host reboot.
-v /opt/hanami-ext:/opt/hanami/extMounts custom configuration.
-v /opt/hanami/backups:/opt/hanami/backupsPersists backups.
--spring.profiles.activestandalone enables customer-standalone.yml; workflow enables customer-workflow.yml. Remove a profile if you do not use it.

Changing the port​

Hanami’s embedded server listens on 8080 by default. To switch to another port (e.g. 80):

# /opt/hanami-ext/customer.yml
server:
  port: 80

Then restart the container:

sudo docker restart ep-hanami-container

8 · Watch the logs​

sudo docker logs -f ep-hanami-container

Look for a successful startup message and indexing progress.

Troubleshooting​

SymptomPossible causeFix
Container exits immediatelyMissing / malformed files in /opt/hanami-ext.Verify presence & permissions.
bind: address already in useSelected port already bound.sudo lsof -i :<port> → stop conflicting service or change customer.yml.
Config changes not appliedContainer not restarted.sudo docker restart ep-hanami-container.
No backups writtenVolume not mounted or path wrong.Confirm mount points (docker inspect ep-hanami-container).