- Task
- Version · 6.0.2
- Create
Configure TLS certificates for Liquibase Secure server
Last updated: November 17, 2026
By default, liquibase-platform install generates a self-signed TLS certificate. Browsers show a security warning when your team opens the web app, and Liquibase can't send operations to the server until the Java that runs it trusts the certificate. Use this guide to serve the deployment with a certificate issued by your organization's certificate authority, either when you install or by adding it to a server that is already running, and to let Liquibase trust the certificate the server uses.
Procedure
Obtain a PEM-encoded certificate and private key
Request a certificate for the hostname your team will use to reach the server. Common sources are:
Active Directory Certificate Services (Windows PKI)
HashiCorp Vault PKI secrets engine
An internal OpenSSL certificate authority
Certbot with Let's Encrypt, which requires public DNS and internet access
Both files must be PEM-encoded. If your certificate authority provides a certificate chain, concatenate the leaf and intermediate certificates into a single file.
Let Liquibase trust the certificate
Liquibase sends operations to the server only when the Java that runs Liquibase trusts the server's certificate. A browser lets you accept a certificate it doesn't trust. Java has no such prompt, so a certificate your browser loads after a warning still fails in Liquibase. A certificate from a public certificate authority is usually trusted already. The self-signed certificate that install generates is not.
Until Java trusts the certificate, each Liquibase command still runs and succeeds, but its operation is written to the extension's recovery file instead of the server, and Liquibase prints PKIX path building failed.
Do this on every machine that runs Liquibase with Change Intelligence:
Copy
certs/server.crtfrom the deployment directory to that machine. It holds the certificate only, not the private key.Find the Java that runs Liquibase. The
liquibaselauncher usesJAVA_HOMEif it is set, then thejredirectory inside the Liquibase installation, then thejavaon yourPATH. For the last case, this command prints its home asjava.home:loadingCopy that Java's trust store, and add the certificate to the copy:
loadingThe copy keeps every public certificate authority, so Liquibase still reaches other HTTPS services.
changeitis the default password of Java's trust store.Point Liquibase at the copy in the same shell before you run it:
loadingOn Windows, set
JAVA_OPTSto the same value withsetbefore you runliquibase.bat. Keep the trust store at a path without spaces, because the launcher passesJAVA_OPTSto Java unquoted.
Be sure to:
Replace
your_java_homewith the Java home from step 2. For example,/usr/lib/jvm/java-21
Import the certificate into Java's own trust store
If you can write to the trust store of the Java that runs Liquibase, you can import the certificate into it instead of steps 3 and 4:
keytool -importcert -cacerts -storepass changeit -noprompt -alias liquibase-platform -file server.crtRun it with that Java's keytool, because -cacerts is the trust store of the Java that keytool belongs to. The change applies to every program that uses that Java, and you repeat it when that Java is replaced.
When the server's certificate changes
After you replace the server's certificate, Liquibase reports PKIX path building failed until you import the new certificate. keytool refuses an alias that already exists, so delete the old entry first:
Use an address the certificate covers
The certificate install generates covers the --domain value, localhost and 127.0.0.1. Set LIQUIBASE_PLATFORM_API_URL to one of those addresses, for example https://localhost/api. Any other address fails with Hostname … not verified, even when Java trusts the certificate.
Keep https in the URL. The server answers http with a redirect to https, so switching to http doesn't get around the certificate check.
Troubleshooting
The server still presents the old certificate
start leaves a running proxy as it is, and the proxy loads the certificate only when its container starts. After you copy a new certificate into certs/, run ./liquibase-platform stop, then ./liquibase-platform start.
TLS certificate generation fails during install
install generates the self-signed certificate with openssl. When openssl is not installed or not on the PATH, install warns openssl is not installed or not in PATH. Install openssl and run install again, or pass your own certificate with --tls-cert and --tls-key, as in step 3. If install finished anyway, add your certificate to the running server instead, as in step 3.