Skip to main content

EP Hanami Update Guide — ≥ 1.3.0 → 1.5.0

Scope • Upgrade an existing EP Hanami deployment running any version ≥ 1.3.0 to 1.5.0 while preserving data, backups, and customised configuration.

0 · Before you start​

CheckpointAction
Current versionVerify the running version (docker inspect --format='{{.Config.Image}}' ep-hanami-container).
Paired application URLConfirm host & port where the catalogue is reachable from Hanami.
Sync credentialsObtain username and password for the paired catalogue’s REST sync endpoint.
Maintenance windowPlan for ±5 min of downtime (container restart).
Backups verifiedEnsure recent backups exist in /opt/hanami-backups.

1 · Download release 1.5.0​

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 · Stop & remove the running container​

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

(Only the container is removed; the old image ep-hanami:<old-version> remains for rollback.)

3 · Extract artefact & load image​

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

4 · Backup current configuration​

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

5 · Update configuration files (/opt/hanami-ext/config/)​

5.1 Copy fresh templates (non-destructive)​

# From the extracted ext/ directory
sudo cp -n ext/config/*.example /opt/hanami-ext/config/

-n keeps your existing files; new *.example templates appear beside them for reference.

5.2 customer.yml — mandatory edits​

Append (or adjust) the following blocks without deleting existing keys:

# -------------------------
# Port & access logging
# -------------------------
server:
  port: 80 # Change if default 8080 is sufficient
  tomcat:
    accesslog:
      enabled: true
      directory: /opt/hanami/logs

If using OAuth / reverse proxy headers add forward-headers-strategy:

server:
  port: 80
  forward-headers-strategy: NATIVE
  tomcat:
    accesslog:
      enabled: true
      directory: /opt/hanami/logs

Add the sync block under the existing hanami: section:

hanami:
  sync:
    eventTransmission:
      enabled: true
    catalogue:
      baseUrl: "http://<paired-host>:<port>"
      username: "<sync-user>"
      password: "{noop}<sync-password>"
  # …keep the rest of your hanami:* properties…

Declare the folder for overriding UI assets:

local:
  assets:
    folder: /opt/hanami/ext/override

Create the directory if absent:

sudo mkdir -p /opt/hanami-ext/override

5.3 customer-standalone.yml (or any customer-<profile>.yml)​

  • Remove any local.assets.folder key — now centralised in customer.yml.
  • Merge other changes from the new *.example if relevant.

5.4 security.yml​

Compare your active file with the new security.yml.example and merge any additional roles or scopes:

diff -u security.yml.example /opt/hanami-ext/config/security.yml | less

6 · Run the 1.5.0 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

Profiles: ensure the list matches the customer-<profile>.yml files you keep.

7 · Smoke test​

  1. Browse to http://<host>:<port>** (8080 or the port you configured).
  2. Verify login, search, and Admin › System Info shows version 1.5.0 and sync status.

8 · Rollback (if needed)​

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

# Relaunch the previous image (replace <old-version>)
sudo docker run -d --name ep-hanami-container … ep-hanami:<old-version> …

Restore the /opt/hanami-ext-backup-<date> directory if config changes cause issues.

9 · Post-upgrade cleanup​

  • Remove older images when confident:
    sudo docker images | grep ep-hanami   # list versions
    sudo docker rmi ep-hanami:<old-version>
  • Keep the ext backup for audit.