Skip to main content

Hanami Docker Update Guide — ≥ 1.3.0 → 1.5.x

Scope • Upgrade an existing Hanami deployment running any version ≥ 1.3.0 to 1.5.x 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 paired application is reachable from Hanami.
Sync credentialsObtain username and password for the paired application 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 (or any other v1.5.x)​

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

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/

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:
  backup:
    enabled: true
  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

These config changes are sufficient to update the configuration for hanami from any version 1.3.0 up to v1.5.x. Also see full configuration examples with oauth installation or Basic Auth installation.

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

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

7 · Watch the logs​

sudo docker logs -f ep-hanami-container

Look for a successful startup message and indexing progress.

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.