EP Hanami Installation Guide (v1.5.0)

Scope • Clean installation of EP Hanami 1.5.0 on a Linux host.

---

Prerequisites

Requirement	Check / Notes
Sudo access	sudo -v (or sudo su) should succeed.
Docker Engine	Tested with Docker → sudo docker --version.
Open TCP port	Default listening port is 8080. To use another port (e.g. 80) add server.port to customer.yml (see Changing the port) and make sure the chosen port is free.
Access to Cognizone Nexus	Valid credentials for the private repository.

---

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 · 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

Flag	Purpose
--name	Human‑friendly container name.
--network host	Publishes container ports directly on the host. Hanami binds to 8080 by default (see below for overrides).
--restart unless-stopped	Auto‑restarts on failure or host reboot.
-v /opt/hanami-ext:/opt/hanami/ext	Mounts custom configuration.
-v /opt/hanami/backups:/opt/hanami/backups	Persists backups.
--spring.profiles.active	standalone 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

---

6 · Copy / update configuration

1. Backup the current ext directory

   sudo cp -r /opt/hanami-ext /opt/hanami-ext-backup
2. Clean the directory (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 {} +
3. Copy the new defaults

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

---

7 · Prepare configuration files (MANDATORY)

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/

---

8 · Restart to apply configuration

sudo docker restart ep-hanami-container

---

9 · Watch the logs

sudo docker logs -f ep-hanami-container

Look for a successful startup message and indexing progress.

---

Troubleshooting

Symptom	Possible cause	Fix
Container exits immediately	Missing / malformed files in /opt/hanami-ext.	Verify presence & permissions.
bind: address already in use	Selected port already bound.	sudo lsof -i :<port> → stop conflicting service or change customer.yml.
Config changes not applied	Container not restarted.	sudo docker restart ep-hanami-container.
No backups written	Volume not mounted or path wrong.	Confirm mount points (docker inspect ep-hanami-container).