Docker Clean Installation 1.8.x (HTTPS)

This guide describes how to install Hanami 1.8.x with HTTPS enabled. For HTTP installation, see Docker Clean Installation 1.8.x.

0 · Prerequisites

Requirement	Mandatory?	Check / Notes
Sudo access	✓	sudo -v (or sudo su) should succeed.
Docker 24+	✓	docker --version
Elasticsearch 7.14–	✓	Cluster reachable; service user with R/W on indices.
TCP port 443 open	✓	Hanami will expose 443 for HTTPS.
SSL certificates	✓	Server certificate, intermediate CA, and private key.
Nexus credentials	✓	Needed to download the ZIP artefact.
External triplestore	optional	Configure if you don't use the embedded store.
External IAM/OAuth2	optional	Required only when env.hanami.security.iam: true.

---

1 · Download release 1.8.0

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

---

2 · Extract the artefact

unzip hanami-1.8.0.zip

Expected files:

hanami-1.8.0.tar   # Docker image
ext/               # Default configuration

---

3 · (If present) stop & remove an old container

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

---

4 · Load the Docker image

sudo docker load -i hanami-1.8.0.tar

---

5 · Stage the ext directory

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

Resulting layout:

/opt/hanami-ext/config
 ├─ customer-env.yml.example   ← template
 ├─ customer.yml               ← keep as‑is
 ├─ customer-iam.yml           ← keep as‑is
 └─ customer-workflow.yml      ← keep as‑is

---

6 · Prepare SSL certificates

6.1 · Create 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 PKCS#12 keystore

# Set a secure password
KEYSTORE_PASS='YourSecurePassword'

# Create 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 · Create truststore for external services

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

sudo mkdir -p /opt/hanami-certs

# 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 one customer-env.yml

1. Copy the template:

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

2. Open it and replace placeholders. Update URLs to use HTTPS if applicable:

   env:
     hanami:
       elasticsearch:
         url: "https://es.example.com:9200"  # Use HTTPS if available
         username: "hanami_svc"
         password: "********"
       triplestore:
         url: "https://triplestore:7200/repositories/data"  # Use HTTPS if available
         username: "sparql_user"
         password: "********"

---

9 · Create optional directories

sudo mkdir -p /opt/hanami-backups
sudo mkdir -p /opt/hanami-logs

---

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

---

11 · Verify container is running

sudo docker ps | grep hanami

---

12 · 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).

---

13 · Check logs

If issues arise:

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

---

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

• Ensure all external service certificates are added to the truststore
• Verify network connectivity to external services
• Check that service URLs use the correct protocol (http vs https)