Docker Incremental Update 1.8.x (HTTPS)

This guide describes how to update an existing Hanami installation to 1.8.x with HTTPS enabled. For HTTP updates, see Docker Incremental Update 1.8.x.

0 · Before you start

Checkpoint	Action
Current version	Verify the running version (`docker inspect --format='{{.Config.Image}}' hanami-container`).
Maintenance window	Plan ±30 min downtime (container restart).
SSL certificates	Ensure you have server certificate, intermediate CA, and private key ready.

1 · Download release 1.8.0

curl -u <user>:<password> -O \
  <artifact repository url>/hanami-1.8.0.zip

2 · Stop & remove the running container

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

(Only the container is removed; the image hanami:<old> stays for rollback.)

3 · Extract artefact & load image

unzip hanami-1.8.0.zip
sudo docker load -i hanami-1.8.0.tar

4 · Back up all current data

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)

# If you already have TLS/certs directories from previous HTTPS setup
[ -d /opt/hanami-tls ] && sudo cp -r /opt/hanami-tls /opt/hanami-tls-backup-$(date +%F)
[ -d /opt/hanami-certs ] && sudo cp -r /opt/hanami-certs /opt/hanami-certs-backup-$(date +%F)

5 · Replace the ext directory

Delete the old directory completely
```
sudo rm -rf /opt/hanami-ext
```
All previous files are safe in /opt/hanami-ext-backup-$(date +%F) and will serve as reference when populating the new customer-env.yml.

Copy the new defaults

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

Your fresh /opt/hanami-ext/config must contain exactly:

customer-env.yml.example   ← template (do not edit in place)
customer-iam.yml           ← keep as‑is
customer-workflow.yml      ← keep as‑is
customer.yml               ← keep as‑is

6 · Prepare SSL certificates

6.1 · Create or update certificate directory

sudo mkdir -p /opt/hanami-tls

6.2 · Copy certificates

Place your certificates in /opt/hanami-tls:

# Copy your certificates (adjust paths as needed)
sudo cp /path/to/your-server.crt /opt/hanami-tls/server.crt          # Server/leaf certificate
sudo cp /path/to/your-issuer.crt /opt/hanami-tls/issuer.crt          # Intermediate CA
sudo cp /path/to/your-server.key /opt/hanami-tls/server.key          # Private key

# Set permissions
sudo chmod 640 /opt/hanami-tls/*
sudo chown root:root /opt/hanami-tls/*

6.3 · Create or update PKCS#12 keystore

# Set a secure password
KEYSTORE_PASS='YourSecurePassword'

# Remove old keystore if it exists
[ -f /opt/hanami-tls/hanami-keystore.p12 ] && sudo rm /opt/hanami-tls/hanami-keystore.p12

# Create new PKCS#12 keystore
sudo openssl pkcs12 -export \
  -inkey    /opt/hanami-tls/server.key \
  -in       /opt/hanami-tls/server.crt \
  -certfile /opt/hanami-tls/issuer.crt \
  -name hanami \
  -out  /opt/hanami-tls/hanami-keystore.p12 \
  -passout pass:"$KEYSTORE_PASS"

# Set permissions
sudo chmod 640 /opt/hanami-tls/hanami-keystore.p12
sudo chown root:root /opt/hanami-tls/hanami-keystore.p12

7 · Update truststore for external services

When using HTTPS, you need a truststore to verify certificates of external services:

sudo mkdir -p /opt/hanami-certs

# If you have an existing truststore, you can update it
# Otherwise, create a new one

# Import triplestore CA (if using HTTPS)
sudo keytool -importcert -trustcacerts \
  -alias triplestore-ca \
  -file /path/to/triplestore-ca.crt \
  -keystore /opt/hanami-certs/truststore.jks \
  -storepass changeit -noprompt

# Import Elasticsearch CA (if using HTTPS)
sudo keytool -importcert -trustcacerts \
  -alias es-ca \
  -file /path/to/elasticsearch-ca.crt \
  -keystore /opt/hanami-certs/truststore.jks \
  -storepass changeit -noprompt

8 · Create `customer-env.yml` (one per environment)

customer-env.yml.example is only a template. Copy it once per runtime environment (dev, prod …), fill in real values from your backup:

cp /opt/hanami-ext/config/customer-env.yml.example \
   /opt/hanami-ext/config/customer-env.yml

Replace every placeholder with the value that previously lived in the old files. Update URLs to use HTTPS if applicable:

New key	Where it lived before (1.6.x)
`env.hanami.elasticsearch.*`	`customer-standalone.yml: env.hanami.elasticsearch.*`
`env.hanami.triplestore.*`	`customer-standalone.yml: hanami.customer.template-arguments.*`
`env.hanami.catalogue.url`	`customer-standalone.yml: hanami.sync.catalogue.baseUrl`
`env.hanami.security.issuer-uri`	`security.yml: spring.security.oauth2.client.provider.*.issuer-uri`
`env.hanami.security.client-id/secret`	`security.yml: spring.security.oauth2.client.registration.*`

Important: Update service URLs to use HTTPS if those services now support it:

Elasticsearch: https://es.example.com:9200
Triplestore: https://triplestore:7200/repositories/data
Catalogue: https://catalogue.example.com

9 · Run the container with HTTPS

KEYSTORE_PASS='YourSecurePassword'  # Same as used in step 6.3
TRUSTSTORE_PASS='changeit'          # Truststore password from step 7

sudo docker run -d \
  --name 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 \
  -v /opt/hanami-tls:/opt/hanami/tls:ro \
  -v /opt/hanami-certs:/opt/hanami/certs:ro \
  -e JAVA_TOOL_OPTIONS="\
    -Xms6g -Xmx6g \
    -Djavax.net.ssl.trustStore=/opt/hanami/certs/truststore.jks \
    -Djavax.net.ssl.trustStorePassword=${TRUSTSTORE_PASS} \
    -Djavax.net.ssl.trustStoreType=JKS \
    -Dserver.port=443 \
    -Dserver.ssl.enabled=true \
    -Dserver.ssl.key-store=/opt/hanami/tls/hanami-keystore.p12 \
    -Dserver.ssl.key-store-password=${KEYSTORE_PASS} \
    -Dserver.ssl.key-store-type=PKCS12 \
    -Dserver.ssl.key-alias=hanami" \
  hanami:1.8.0 \
  --spring.profiles.active=env,workflow \
  --server.port=443

Add ,iam to --spring.profiles.active if using OAuth2/IAM.

10 · Verify container is running

sudo docker ps | grep hanami

11 · Test the HTTPS endpoint

Test locally with curl:

# Test with certificate verification (adjust hostname as needed)
curl -v https://your-hostname/

# Or test ignoring certificate verification
curl -kv https://localhost/

Expected: You should see a TLS handshake and either a login page or 401 response (if authentication is required).

12 · Check logs

If issues arise:

sudo docker logs hanami-container --tail 50 -f

13 · Health check

Open https://your-hostname/ in browser
Sign in (credentials depend on profile: IAM, basic auth, or standalone)
Navigate to workspaces, items, collections

Rollback procedure

If the update fails:

Stop the new container:

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

Restore the old ext directory:

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

Run the old version (adjust for HTTP or HTTPS as needed):

sudo docker run -d \
  --name 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 \
  hanami:<old-version> \
  --spring.profiles.active=env,workflow \
  --server.port=80  # or 443 with SSL options if previously on HTTPS

Troubleshooting

Certificate issues

Ensure the certificate CN or SAN matches your hostname
Verify the certificate chain is complete (server cert + intermediate CA)
Check keystore password matches in both creation and docker run

Port conflicts

Ensure port 443 is not already in use: sudo netstat -tlnp | grep 443
Stop conflicting services or use a different port

External service connection issues

If external services switched to HTTPS, ensure their URLs are updated in customer-env.yml
Ensure all external service certificates are added to the truststore
Verify network connectivity to external services

Docker Incremental Update 1.8.x (HTTPS)

0 · Before you start​

1 · Download release 1.8.0​

2 · Stop & remove the running container​

3 · Extract artefact & load image​

4 · Back up all current data​

5 · Replace the ext directory​

6 · Prepare SSL certificates​

6.1 · Create or update certificate directory​

6.2 · Copy certificates​

6.3 · Create or update PKCS#12 keystore​

7 · Update truststore for external services​

8 · Create customer-env.yml (one per environment)​

9 · Run the container with HTTPS​

10 · Verify container is running​

11 · Test the HTTPS endpoint​

12 · Check logs​

13 · Health check​

Rollback procedure​

Troubleshooting​

Certificate issues​

Port conflicts​

External service connection issues​