- Concept
- Version ยท 6.0.2
- Create
Review Liquibase Secure server requirements
Last updated: November 17, 2026
Check your hardware, software, host platform, and network against these requirements before you install Liquibase Secure server.
Before you install Liquibase Secure server, ensure your environment meets the following requirements.
Liquibase Secure server
Liquibase Secure server is the central service that receives, stores, and displays the operation data your team's Liquibase extensions send it. The requirements below cover what it takes to run it.
System requirements
Requirement | Minimum | Recommended |
|---|---|---|
CPU | 2 cores | 4+ cores |
RAM | 4 GB | 8+ GB |
Disk | 10 GB | 50+ GB (depends on operation volume) |
Upgrading from a release on PostgreSQL 14 copies the bundled databases to PostgreSQL 17, so while update runs, the host also needs free disk of at least 1.2 times the size of the databases it copies.
Scaling and availability
Liquibase Secure server runs as a single Docker Compose deployment on one host. It does not cluster across nodes, fail over automatically, or replicate its databases, so size the host for your expected volume rather than planning to add nodes later.
The primary database is the component that limits throughput, and it scales vertically. Give the host more CPU, memory, or disk as your operation volume grows.
Software requirements
Liquibase Secure server is a containerized application. Docker and Docker Compose are required regardless of installation method. The liquibase-platform CLI runs Docker Compose under the covers.
Software | Minimum version |
Docker Engine | 24.0+ |
Docker Compose | 2.20+ |
Every liquibase-platform command checks the Docker Compose version before it runs Docker Compose, and stops with a message to upgrade when the version is older than 2.20.
Docker access on Linux
The installer runs Docker as the user who starts it. On a Linux host, that user must be root or a member of the docker group. Choose one:
Use
sudo: Run eachliquibase-platformcommand withsudo.Add the user to the
dockergroup: Runsudo usermod -aG docker $USER, then log out and back in, or runnewgrp docker.
To confirm that the user can reach Docker, run docker ps. It lists containers when the user has access and prints permission denied when the user does not.
Note: Membership in the docker group gives a user root-level access to the host, so your security team may prefer sudo.
Docker Desktop on macOS and on Windows with WSL2 gives your user access to Docker without this step.
Database requirements
Liquibase Secure server stores its data in standard PostgreSQL 17, with no extensions required. PostgreSQL 17 is the only supported major version, whether the database is bundled or your own. By default, the bundled docker-compose.yml file runs the primary database and the secrets database for you on the postgres:17.11-alpine image, so there is nothing to install separately. You can also keep the primary database on a PostgreSQL 17 server of your own instead.
Database settings
The bundled primary database ships with memory settings sized for the 4 GB minimum host, where PostgreSQL shares memory with the server's other services. The variables take effect only with the docker-compose.yml file from this release, and they do not apply to an external database.
To raise them on a larger host:
If
updatekept your edited file and wrote the release's copy beside it asdocker-compose.yml.new, merge thedbservice from the new file into yourdocker-compose.yml.Add the variables from the table below to your
.envfile.Run
./liquibase-platform startso the database container is recreated with the new values.
Variable | 4 GB host (default) | 8 GB host | 16 GB host | What it controls |
|
|
|
| Memory PostgreSQL uses to cache data |
|
|
|
| How much memory the query planner can assume is available for caching |
|
|
|
| Memory for index builds and maintenance, such as during upgrades |
|
|
|
| Memory for each sort or join operation |
|
|
|
| Maximum number of concurrent connections |
|
|
|
| Planner cost of a random disk read. Keep |
As a rule of thumb, set LIQUIBASE_PLATFORM_DB_SHARED_BUFFERS to about 25% of the host's memory and LIQUIBASE_PLATFORM_DB_EFFECTIVE_CACHE_SIZE to about 75%.
Note: A deployment that ran on the TimescaleDB image kept memory settings that image tuned for its host. After update, the database uses the defaults in this table instead, so set the variables for your host size before you run update.
Using an external PostgreSQL database
By default, the primary database runs in the deployment's bundled db service. To keep that data on a PostgreSQL server of your own instead, point the deployment at it. The secrets database and Redis stay bundled either way, and the bundled db service does not start.
Your database must meet these requirements:
Version: PostgreSQL 17, with no extensions.
installandupdateread the server's version before they change anything, and stop when it is older than PostgreSQL 17, so upgrade it first.Privileges: The server and its migrations connect as one user. That user must own the database, or hold
CREATEandUSAGEon thepublicschema. The migrations create tables, indexes, functions and triggers there. In PostgreSQL 15 and later, a user that does not own the database has noCREATEonpublicuntil it is granted. Without it,installstops withLB-SEC-INS-0041andpermission denied for schema publicbefore it changes anything.Network: The database must be reachable from Docker on the host. Its hostname must resolve inside containers, and the host must allow outbound connections to its port.
If the user does not own the database, connect as the database owner and grant it, replacing your_user with the user's name:
To install against it, pass the connection to install with --db-host, --db-port, --db-name and --db-user. --db-port, --db-name and --db-user default to 5432, postgres and postgres. Set the password in the LIQUIBASE_PLATFORM_DB_PASSWORD environment variable rather than on the command line, where other users of the host could see it. When --db-host is set and LIQUIBASE_PLATFORM_DB_PASSWORD is not, install stops before it changes anything. install writes the password to secrets/db_password and the connection to .env, then applies the migrations to your database. From then on, update and migrate read the connection from .env.
Before they change your deployment, install, update and migrate open one connection to your database with the connection settings the migrations use: the --db-* options for install, and the LIQUIBASE_PLATFORM_DB_* settings in .env after that. When it works, the command prints a line saying the database accepts connections. When it does not, the command stops with LB-SEC-INS-0041, names the host and port, and gives the database's reason. The reasons are authentication failed, database does not exist, connection refused, unreachable, TLS failure, and a changelog lock held by another run. Fix the setting it names and run the command again. Because the command wrote no files, install --force is not needed.
The check takes the database's changelog lock, so it is the one thing the check can write. On a new database, it creates the DATABASECHANGELOGLOCK table that the migrations would create next. When another install, update or migrate holds the lock, the check waits about a minute before it stops.
TLS
With --db-tls, the server and the migrations connect over TLS and always verify the database's certificate, by default against the system's trusted CAs. If the certificate comes from a private CA, add --db-tls-ca-file with the CA's PEM file. install copies the file into the db-tls/ directory beside .env, which is mounted read-only into the containers at /etc/liquibase-platform/db-tls/, and sets LIQUIBASE_PLATFORM_DB_TLS_CA_FILE to its path there. A CA path outside that directory stops the command with a message that the database settings are not usable. TLS is either on or off. When it is on, you cannot turn off the certificate or hostname check.
Configure it by hand
To point an existing deployment at your database without install, set these lines in .env. Put the password in secrets/db_password, and leave the LIQUIBASE_PLATFORM_DB_PASSWORD line in .env empty:
Setting | Value |
| Empty, so the bundled database does not start. A bundled install has |
| Your database's hostname |
| Its port, |
| The database name |
| The user the server and its migrations connect as |
|
|
| The private CA's path inside the containers, under |
A LIQUIBASE_PLATFORM_DB_* line that is present but empty means the default. For LIQUIBASE_PLATFORM_DB_HOST and LIQUIBASE_PLATFORM_DB_PORT, an empty line means the bundled database.
For a private CA, copy its PEM file into the db-tls/ directory beside .env, and set LIQUIBASE_PLATFORM_DB_TLS_CA_FILE to /etc/liquibase-platform/db-tls/ followed by the file name. A deployment installed before this release has no db-tls/ directory until you run update, so create it yourself if you configure the database first.
Then run ./liquibase-platform migrate to create the schema in your database, and ./liquibase-platform start.
Supported host platforms
The liquibase-platform CLI comes as a separate archive for each host platform, with its own runtime embedded. Download the archive that matches the machine you run the CLI on, and verify it, before you install. If you are unsure of your machine's operating system and architecture, run uname -sm.
Host platform | CLI archive |
|---|---|
macOS, Apple Silicon (M-series) |
|
macOS, Intel |
|
Linux, x86-64 (Intel or AMD) |
|
Linux, arm64 (AArch64) |
|
Windows, through WSL2 |
|
Note: There is no native Windows archive. On Windows, run the CLI inside your WSL2 (Ubuntu) shell, which is where Docker Desktop and the CLI run, and use the linux-x64 archive.
Network requirements
The bundled reverse proxy is the only component that exposes ports on the host. All other services, including the databases, communicate over isolated internal Docker networks and are not reachable from outside the deployment.
Port | Purpose | Configurable |
|---|---|---|
443 | HTTPS entry point for the API and the web app |
|
80 | HTTP redirect to HTTPS |
|
The server must be reachable by two sets of clients:
Liquibase CLI machines: Must be able to reach the server over HTTPS to send operation data
Web app users: Must be able to reach the server over HTTPS to use the dashboard
The host that runs install, update and pull also needs outbound HTTPS to these hosts:
api.keygen.sh, for the license check and the list of deployment filesoci.liquibase.com, for the Liquibase imageskeygen-dist.c3c9112df8df715f42d1162cdce5dba1.r2.cloudflarestorage.com, the storage host that the deployment files and image layers download fromDocker Hub, for the nginx, PostgreSQL, and Redis images. You do not need it if you copy them to your own registry with
pull --to --include-third-partyand install with--include-third-party, or if your Docker hosts pull Docker Hub images through a registry mirror.repo.liquibase.com, to download the CLI. Only the machine you download it on needs this host.
If the host reaches the internet through a proxy, set HTTPS_PROXY before you run the CLI. The CLI also honors NO_PROXY. Docker pulls the images itself, so configure the proxy for the Docker daemon too.
A host with no internet access can still install. Install Liquibase Secure server in a restricted or air-gapped network covers saving the deployment files with pull --files on a connected host and installing from your registry.
Monitoring
The server does not export Prometheus or OpenTelemetry metrics. Monitor it with the health endpoints, its structured JSON logs, and your container runtime's own statistics.
Liquibase extension
The Liquibase extension is a plugin that runs on each machine executing Liquibase commands. It automatically collects operation metadata and reports it to Liquibase Secure server after each command completes. No changes to your changelogs or workflow are required.
To send operation data to the server, you need:
Java 17+. The
liquibaselauncher refuses an older Java.Liquibase Secure 6.0+ installed
Network connectivity from the CLI machine to the server API
A Java that trusts the server's TLS certificate. A certificate from a public or corporate certificate authority usually is trusted already. The self-signed certificate that
installgenerates is not, so add it to the Java that runs Liquibase before you send operations to the server.