- Task
- Version ยท 6.0.2
- Create
Install Liquibase Secure server
Last updated: November 17, 2026
Install Liquibase Secure server on a server host with the liquibase-platform CLI and Docker Compose. The CLI is a public download. It uses your license file to download the deployment files and the container images from Liquibase, so there is no registry token to request, store, or renew. The CLI checks every file's checksum and signature before it writes anything, and it never stores your license key in your Docker credentials or keychain.
By default, install pulls the server images from Liquibase with your license file, as this article describes. If your organization vets vendor images before they run, or the server host can't reach Liquibase, install Liquibase Secure server in a restricted or air-gapped network instead. That article also starts with step 1 of this article, to download the CLI.
Before you begin
The license file (
.lic) your Liquibase account team sends you, or a directory that holds your license files. It is the only credential the install needs. Copy it to the server host before you start.A machine to run the server on, called the server host in this article. It can run Linux, macOS, or Windows with WSL2. On Windows, turn on Docker Desktop's WSL integration for your distribution, run every command in this article in your WSL2 shell, and keep the archive and the deployment under your Linux home directory, not on the Windows drive. If you download the archive in a Windows browser, copy it into your Linux home directory before you extract it. You download the CLI to the server host and run every command in this article there.
Docker Engine 24 or later and Docker Compose 2.20 or later, installed and running on the server host. The CLI installs and runs the server as Docker containers, so Docker is the only way to run Liquibase Secure server. There is no installer that runs it without Docker. The server host must also meet the rest of the Liquibase Secure server requirements.
The server host can open outbound HTTPS connections to the addresses in Network requirements, such as
api.keygen.shandoci.liquibase.com. The install downloads the deployment files and the server images from them.The server host doesn't already run a Liquibase Secure server deployment. One deployment runs per Docker host.
Procedure
Download the Liquibase Secure server CLI
Go to the Liquibase Secure server download page, open the version you are installing, and download the archive for your server host:
Server host | Archive |
Mac with Apple silicon |
|
Mac with Intel |
|
Linux x86-64, or Windows with WSL2 |
|
Linux arm64 |
|
Double-click the archive to extract it, then open a terminal in the liquibase-platform-your_version folder it creates. You can keep this folder anywhere on the server host.
Install the server
From the folder you extracted, run install with your license file.
install puts the server's settings, secrets, and certificate in a deployment directory, which you choose with --dir. It is a different directory from the folder you extracted, which holds only the CLI. When you upgrade, you download a new CLI folder and the deployment directory stays where it is.
Be sure to:
Replace
your_license_filewith the path to the license file (.lic) Liquibase sent you, after you copy it to the server host. For example,~/liquibase-secure-server.licReplace
your_deployment_directorywith the deployment directory. You can use any directory, andinstallcreates it if it does not exist. For example,/opt/liquibase-secure-serverReplace
your_fully_qualified_domain_namewith the domain name people will use to reach the server. For example,liquibase.example.com
install downloads the server with your license, starts it, and prints the address of the web app when it finishes:
Access URL: https://your_fully_qualified_domain_name
TLS: Self-signed certificateNote: install records the deployment directory, so later commands such as status, stop and update find the deployment from any directory. Run them as the user who ran install, because the record belongs to that user. To work on another deployment, add --dir with its directory.
Tip: If port 80 or 443 is already in use on the server host, or you want to use your own TLS certificate, see the install flags in the command reference.
Back up the deployment secrets
The secrets/ directory and the .env file in the deployment directory hold the encryption key for stored database credentials and the deployment's passwords and settings. The secrets cannot be regenerated, so if you lose them, you cannot read the credentials stored in the server.
Run this command to save them into one compressed file, liquibase-secure-server-secrets.tar.gz, in the current folder. Be sure to replace your_deployment_directory with the deployment directory from step 2.
tar -czf liquibase-secure-server-secrets.tar.gz -C your_deployment_directory secrets .envStore liquibase-secure-server-secrets.tar.gz somewhere secure off the server host, such as your backup system or secrets manager, and delete the copy on the server host. Anyone with this file can read the stored credentials.
Check that the server is healthy
The -k option lets curl accept the self-signed certificate that install generated. Leave it out if you installed your own certificate. Be sure to replace your_fully_qualified_domain_name with the domain from step 2.
200 means the API is up and reaches both of its databases.
Create the administrator account
Open https://your_fully_qualified_domain_name in a browser. If the server uses the self-signed certificate, your browser warns you the first time, which is expected. The console opens on Step 1 of 2, Create the administrator account.
Enter your Full name, your Work email, and a Password, then enter the password again in Confirm password.
Select Create account.
This is the first account on the installation, and it is the administrator. Create it before you share the address with anyone.
Warning: If other people can reach the address before you sign in, someone else can create the administrator account first. To name the administrator up front, set LIQUIBASE_PLATFORM_INITIAL_ADMIN_EMAIL in .env and run liquibase-platform start --dir your_deployment_directory before anyone opens the address.
Import your license
The console then shows Step 2 of 2, Import your license.
Drag your license file onto Drop your license file here, or select browse and pick the file. The page accepts
.licand.jsonfiles.Select Import license.
The license is validated offline, so nothing leaves your network. When the import succeeds, the console opens and the installation is complete.
Note: Outbound email is off by default. Until you set the LIQUIBASE_PLATFORM_SMTP_* settings in .env and run liquibase-platform start, password reset emails, invitations, and email-change verification emails are not sent. Configure Liquibase Secure server covers the email settings. In the meantime, liquibase-platform reset-password creates a one-time password reset link for an account.
Troubleshooting
cannot execute binary file
You downloaded the archive for a different platform. Check your machine with uname -sm, then repeat step 1 with the archive for your server host from its table.
The install command stops with an error code
Each install error starts with a code such as LB-SEC-INS-0001, followed by a suggestion. Troubleshoot the Liquibase Secure server CLI explains each code and what to do about it.
What to do next
Configure Liquibase Secure server to turn on outbound email and change the other settings in
.env.Configure TLS certificates for Liquibase Secure server to replace the self-signed certificate with one your organization trusts.
Invite and manage users to give your team access to the console.
Connect Liquibase Secure to the server so your Liquibase runs send their operations to it.