Skip to main content

Hanami Docker Update Guide — ≥ 1.5.0 → 1.6.x

Scope • Upgrade an existing Hanami deployment running any version ≥ 1.5.0 to 1.6.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 ±30 min of downtime (container restart).
Backups verifiedEnsure recent backups exist in /opt/hanami-backups.

1 · Download release 1.6.1​

curl -u <user>:<password> -O \
  https://nexus-direct.cogni.zone/repository/ep-hanami/zone/cogni/ep/hanami/ep-hanami/1.6.1/ep-hanami-1.6.1.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.6.1.zip

4 · Load the Docker image​

sudo docker load -i ep-hanami-1.6.1.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​

No changes.

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

No changes.

5.4 security.yml​

No changes.

6 · Run the 1.6.1 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.6.1 \
  --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:1.5.0

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