Setting Up HTTPS for Core Hub Web UI and Secure Web Socket Connections

This guide explains how to enable and configure HTTPS with TLS encryption for secure connections to the Gluesync Core Hub web interface and secure web socket connections between nodes.

Overview

By default, Gluesync CoreHub runs with TLS encryption enabled, with a built-in self-signed certificate coming with the trial kit for Docker. To ensure secure communications, you should generate your own certificates and configure CoreHub to use TLS encryption.

The process involves the following steps:

  1. Generating the required SSL certificates

  2. Configuring CoreHub to use TLS encryption (enabled by default under any docker-compose kit)

  3. Customizing the security configuration file

  4. Configuring the reverse proxy certificate, when a reverse proxy such as Traefik runs in front of Core Hub

Generating SSL Certificates

While the kit comes with self-signed certificates, you may want to generate your own, or use a certificate issued by the PKI of your organization. Here’s how to create a self-signed one:

#!/bin/bash
# Create a directory for certificates
mkdir certs
cd certs

# Generate root CA key (you'll be prompted for a password)
openssl genrsa -des3 -out rootCA.key 4096

# Generate root certificate
openssl req -x509 -new -nodes \
  -key rootCA.key \
  -sha256 \
  -days 1825 \
  -out rootCA.crt \
  -subj "/C=IT/ST=Italy/O=YourOrganization/L=YourCity/OU=YourUnit/CN=gluesync.com"

# Generate Gluesync key
openssl genrsa -out gluesync.com.key 2048

# Generate Certificate Signing Request (CSR)
openssl req -new -sha256 \
  -key gluesync.com.key \
  -subj "/C=IT/ST=Italy/O=YourOrganization/L=YourCity/OU=YourUnit/CN=gluesync.com" \
  -out gluesync.com.csr

# Generate Gluesync certificate, listing every host name and IP address used to reach Gluesync
openssl x509 -req \
  -in gluesync.com.csr \
  -CA rootCA.crt \
  -CAkey rootCA.key \
  -CAcreateserial \
  -out gluesync.com.crt \
  -days 1825 \
  -sha256 \
  -extfile <(printf "subjectAltName=DNS:gluesync.com")

# Create PKCS12 keystore (you'll be prompted for an export password)
openssl pkcs12 -export \
  -name gluesync \
  -in gluesync.com.crt \
  -inkey gluesync.com.key \
  -out gluesync.com.p12

# Convert to Java KeyStore (JKS), answering every password prompt with the export password of the .p12
keytool -importkeystore \
  -destkeystore gluesync.com.jks \
  -srckeystore gluesync.com.p12 \
  -srcstoretype pkcs12 \
  -alias gluesync
Remember to replace the certificate subject information (/C=IT/ST=Italy/O=YourOrganization/…​) and the host names and IP addresses in subjectAltName with your organization’s details.
Browsers check the host name against the Subject Alternative Names (SAN) of the certificate, not against its CN. List in subjectAltName every host name used to reach Gluesync as a DNS: entry and every IP address as an IP: entry, separated by commas (for example DNS:gluesync.example.com,DNS:gluesync,IP:10.0.0.5). An IP address written in a DNS: entry does not match, and the clients that reach Gluesync by that address reject the certificate: browsers with a security warning, Node-based clients such as the AI clients connected to the Core Hub MCP server with ERR_TLS_CERT_ALTNAME_INVALID. When the certificate is issued by your PKI, request the same names and addresses in the CSR.

Keystore format and passwords

Gluesync reads both JKS and PKCS12 keystores: the .p12 file created above can be used directly as the keystore, and the conversion to JKS is optional.

A keystore has two passwords: the password of the keystore and the password of the private key it contains. keytool -importkeystore asks for the password of the new keystore and for the one of the source .p12, and the result depends on the Java version of keytool:

  • keytool from Java 9 or later creates a PKCS12 keystore by default, where the private key takes the keystore password;

  • keytool from Java 8 (for example the one bundled with IBM WebSphere) creates a JKS keystore, where the private key keeps the export password of the .p12.

Use the same password for the .p12 export and for the keystore. Gluesync versions before 2.2.11.9 need the keystore and its private key to share the same password, see Customizing the Security Configuration File. If a JKS keystore already has a different key password, align it to the keystore password with keytool -keypasswd -alias gluesync -keystore gluesync.com.jks.

Check the keystore with keytool -list -keystore gluesync.com.jks: it must contain one entry of type PrivateKeyEntry, whose alias is the value of certificateAlias. keytool -list only checks the keystore password, not the password of the private key.

Extracting PEM files

If you are using a reverse proxy such as Traefik in front of Core Hub, you will need to extract the certificate and private key in PEM format from the same .p12 keystore:

# Extract the certificate
openssl pkcs12 -in gluesync.com.p12 -clcerts -nokeys -out gluesync-cert.pem

# Extract the private key without encryption
openssl pkcs12 -in gluesync.com.p12 -nocerts -nodes -out gluesync-key.pem

This will produce:

  • gluesync-cert.pem: X.509 certificate in PEM format

  • gluesync-key.pem: unencrypted private key in PEM format

These are the file names the reverse proxy of the Gluesync kits expects, see Configuring the Reverse Proxy Certificate.

The -nodes flag is critical when extracting the private key. Without it, OpenSSL encrypts the exported PEM private key by default and prompts for a passphrase, producing an encrypted key (-----BEGIN ENCRYPTED PRIVATE KEY-----) that our reverse proxy (Traefik) cannot read. With -nodes, the key is written as an unencrypted PEM private key (-----BEGIN PRIVATE KEY-----), which is the format expected.
If the certificate is issued by an intermediate CA, append the certificate of the intermediate CA to gluesync-cert.pem, after the server certificate, so that browsers can build the chain.

Enabling TLS in Core Hub

To enable TLS encryption, modify your Core Hub service definition in the docker-compose or in your Kubernetes configuration file:

gluesync-core-hub:
  image: molo17/gluesync-core-hub:LATEST
  environment:
    - type=corehub
    - SSL_ENABLED=true # Enable TLS
    - LOG_CONFIG_FILE=/opt/gluesync/shared/logback.xml
  volumes:
    - ./shared:/opt/gluesync/shared:rw
    # ... other volume mappings ...
The SSL_ENABLED environment variable is set to true to enable TLS encryption. The value must be exactly true, in lower case: any other value leaves TLS disabled. The lower case name ssl_enabled is still read when SSL_ENABLED is not set. The default HTTPS port is 1717.
Repeat this step for each node and agent present in your deployment.

Important Configuration Notes

  1. Set SSL_ENABLED=true in the environment variables

  2. Ensure the keystore file (gluesync.com.jks, or the .p12 file) is mounted correctly in the container

  3. The default HTTPS port is 1717

Customizing the Security Configuration File

To ensure that all nodes share the same secret for the TLS certificates, you need to customize the security configuration file. This file should include the following settings:

{
  "ssl": {
    "sslCertificatePath": "/opt/gluesync/shared/gluesync.com.jks",
    "certificateAlias": "gluesync",
    "certificatePassword": "gluesync",
    "certificateKeyPassword": "gluesync"
  }
}
Field Value

sslCertificatePath

Path of the keystore inside the container, JKS or PKCS12 (.p12). On Windows, escape the backslashes, for example "C:\\opt\\gluesync\\shared\\gluesync.com.jks".

certificateAlias

Alias of the private key in the keystore: the -name given to openssl pkcs12 -export, or the -alias given to keytool.

certificatePassword

Password of the keystore.

certificateKeyPassword

Password of the private key. In a PKCS12 keystore it is the same as the keystore password.

Keep any other section already present in the file, such as dh, unchanged.

Before version 2.2.11.9, Gluesync opens both the keystore and the private key with certificateKeyPassword, and uses neither certificatePassword nor certificateAlias. The keystore must therefore hold a single private key, protected by the same password as the keystore, and that password must be set in both fields. A configuration written this way keeps working in later versions.

Starting from version 2.2.11.9:

  • the keystore is opened with certificatePassword and the private key with certificateKeyPassword, so the two passwords can differ. Each field is also tried in place of the other, so the configurations written for earlier versions keep working;

  • the certificate served is the one of certificateAlias, and the other keys of the keystore are ignored. When the keystore holds a single private key, that key is used whatever the alias says;

  • a wrong path or password, or an alias missing among several private keys, stops Core Hub at startup, with an error that names the keystore, the alias and the field to change.

Make sure to mount this configuration file on each node. This setup not only secures the communication between the client (browser) and the Core Hub UI but also secures the communication between each node by enabling WSS (WebSocket Secure).

This file should be named security-config.json and placed in the /opt/gluesync/shared directory, just like the following example:

volumes:
  - ./security-config.json:/opt/gluesync/shared/security-config.json

Configuring the Reverse Proxy Certificate

When Traefik runs in front of Core Hub, browsers receive the certificate of Traefik, not the one of the Core Hub keystore. Traefik reads it from the certs.yml file of the proxy folder of the installation:

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /etc/traefik/gluesync-cert.pem
        keyFile: /etc/traefik/gluesync-key.pem

Replace the PEM files at the paths set in certFile and keyFile, keeping their names. The paths depend on the kit: on recent Windows kits they are C:\opt\gluesync\shared\gluesync-cert.pem and C:\opt\gluesync\shared\gluesync-key.pem, that is the shared folder of the installation. On older Windows installations, the .pem files could also be duplicated in the proxy folder: make sure to replace them in both locations.

If certs.yml does not define defaultCertificate, Traefik serves its own generated certificate (TRAEFIK DEFAULT CERT) and browsers show a security warning.

Traefik connects to Core Hub over HTTPS without checking its certificate (serversTransport.insecureSkipVerify: true in traefik.yml), so the certificate of Traefik is the one that matters for browsers. Using the same .p12 for the Core Hub keystore and for the PEM files keeps the two aligned.

Verifying the Configuration

After enabling TLS:

  1. Restart the Core Hub service, and the reverse proxy if you changed its certificate

  2. Check that the Core Hub log contains Responding at https://. Starting from version 2.2.11.9, Core Hub also logs the certificate in use: SSL certificate '<alias>' loaded from <path>: subject <subject>, expires <date>

  3. Access the web UI using https:// instead of http://

  4. If using self-signed certificates, you may need to accept the security warning in your browser

Troubleshooting

  • If you can’t connect after enabling TLS, verify that:

    • The keystore file is properly mounted

    • The SSL_ENABLED environment variable is set to true

    • The correct port is exposed in your docker-compose configuration

The following messages point to a specific cause:

Message Meaning

Core Hub log: Responding at http://

TLS is not enabled: check that SSL_ENABLED is set to true.

Core Hub log: Keystore was tampered with, or password was incorrect (JKS) or keystore password was incorrect (PKCS12)

Before version 2.2.11.9: the password in certificateKeyPassword does not open the keystore.

Core Hub log: UnrecoverableKeyException: Cannot recover key

Before version 2.2.11.9: the private key has a password different from certificateKeyPassword, or the keystore holds another private key with a different password. Align the key password with keytool -keypasswd, or use the .p12 file directly as the keystore.

Core Hub log: The Gluesync web server could not start on port 1717: CoreHub is exiting

Starting from version 2.2.11.9: the lines that follow name the keystore, the alias and the field to change.

Reverse proxy log: No default certificate, fallback to the internal generated certificate

certs.yml does not define defaultCertificate, so Traefik serves its own certificate.

Reverse proxy log: Error while creating certificate store

Traefik cannot read the PEM files set in certs.yml: check their paths and names, and that the private key is not encrypted.

Reverse proxy log: 500 Internal Server Error error="tls: first record does not look like a TLS handshake"

Core Hub is running without TLS, while Traefik connects to it over HTTPS: check SSL_ENABLED.

Browser: Bad Gateway, reverse proxy log: 502 Bad Gateway with connection refused

Core Hub is not listening on port 1717: check the Core Hub log. Before version 2.2.11.9, a keystore error can leave Core Hub running without its web server: fix the configuration and restart it.
The reverse proxy log line Serving default certificate for request is expected with the certs.yml of the kits, and does not mean that the certificate does not match the host name.