- Concept
- Version ยท 6.0.2
- Create
Configure Liquibase Secure server
Last updated: November 17, 2026
Liquibase Secure server reads its settings from the .env file in the deployment directory, and its four generated secrets from files in the secrets/ directory beside it. The liquibase-platform install command writes both with working values, so a standard installation needs no manual configuration.
Use this page when you need to change ports, set the public URL, turn on email, or manage the generated secrets. The .env.sample file in the deployment directory documents every available setting.
To change a setting, edit .env in the deployment directory, then run start from that directory:
./liquibase-platform startstart recreates each container whose configuration changed and leaves the others running, so you do not need to stop the server first. A certificate is the exception, because the proxy reads it only when its container starts. To replace the server's certificate, run stop and then start.
Set values when you install
liquibase-platform install writes .env and starts the server in one run, and it has no option that sets arbitrary .env values. To configure anything its flags do not cover, install first, then edit .env and run start.
These install flags write their values into .env for you:
--domainsets the host name inLIQUIBASE_PLATFORM_WEB_URLandLIQUIBASE_PLATFORM_API_URL, and the self-signed certificate thatinstallgenerates covers it. The default islocalhost.--http-portand--https-portsetLIQUIBASE_PLATFORM_HTTP_PORTandLIQUIBASE_PLATFORM_HTTPS_PORT. When the HTTPS port is not 443,installadds it to both URLs.--tls-certand--tls-keycopy your certificate and private key intocerts/, instead of generating a self-signed certificate.--registryand--tagsetIMAGE_REGISTRYandIMAGE_TAG.--db-hostand the other--db-*flags point the server at an external PostgreSQL database.installreads that database's password from theLIQUIBASE_PLATFORM_DB_PASSWORDenvironment variable, never from a flag.
No secret is passed as a flag. install generates the database passwords and keys itself, and the SMTP password has no flag, so you set it in .env.
Your values survive upgrades. liquibase-platform update sets IMAGE_TAG to the new version and changes other settings only where a release has to move the deployment forward. It keeps the previous file as .env.bak. It does not add a new release's optional settings to .env, so to use one, copy its line from .env.sample, which update replaces with the new release's copy.
Note: The server does not check setting names. A misspelled or unknown name in .env is ignored without a warning, so when a change has no effect, compare the name with .env.sample.
Registry settings
The install command sets both of these values for you.
Variable | Description |
| Registry the server images are pulled from. |
| Version the server runs. |
Generated secrets
The install command generates these four values with cryptographically secure random values and writes each one to its own file in the secrets/ directory, with file mode 0600. Their lines in .env stay empty.
File | The | Purpose |
|
| Primary database password |
|
| Secrets database password |
|
| Session signing key. 32 bytes, hex-encoded. |
|
| Master encryption key for stored secrets. 32 bytes, encoded as 64 hex characters. |
If you are configuring a manual deployment:
Create the directory with
mkdir -m 700 secrets.Generate each file with the command shown in
.env.sample.Set each file to mode 0600.
A deployment installed with an earlier release keeps these four values in .env. The liquibase-platform update command moves them into secrets/ as part of the upgrade, so there is nothing to move by hand.
Warning: Back up the secrets/ directory and your .env file alongside your database backups. Losing secrets/encryption_key means permanent loss of access to every stored database credential, because the key has no other copy.
What file-based secrets protect
The bundled docker-compose.yml file declares each file as a Compose secret, and Docker mounts it under /run/secrets/ in the containers that need it. The databases read their password through POSTGRES_PASSWORD_FILE, and the API reads all four values through its LIQUIBASE_PLATFORM_*_FILE settings. So the values do not appear in any container's configuration. docker inspect, the Docker Engine dashboard, and any tool that reads container configuration through the Docker API show the /run/secrets/ paths instead of the values.
The secrets also reach only the services that need them. The web app container receives none of them, and the CLI passes database credentials to its migration containers through the environment, never on the command line.
File-based secrets do not protect the values from anyone who can do one of these things:
Run
docker execin the containers.Act as root on the host. Membership of the
dockergroup gives the same access.Read the deployment directory, which holds
secrets/and, after an upgrade from an earlier release,.env.bak.
Keep the deployment directory readable only by the account that runs the platform.
Note: Leave the four secret lines in .env empty. A value there takes precedence over the file and puts the secret back into the API container's environment.
Initial administrator
Nothing in the permission model creates the first administrator, so a new deployment needs one bootstrapped. There are two ways, and which one applies depends on whether you set LIQUIBASE_PLATFORM_INITIAL_ADMIN_EMAIL.
Name the administrator up front. Set LIQUIBASE_PLATFORM_INITIAL_ADMIN_EMAIL to an email address before anyone registers. Only that address is ever promoted, whenever that person signs up. Anyone else who registers without an invitation lands in the Pending group with no permissions until an administrator places them.
Note: When email is set up, the named user is promoted only after they verify their email address, because matching the variable proves someone typed the address, not that they control the mailbox. Until they verify, they sit in Pending with no permissions, and clicking the verification link promotes them straight away with no restart. Single sign-on accounts are not marked verified, so name an address that registers with a password rather than one that arrives through your identity provider. When email is off, no address can be verified, so the named user is promoted as soon as they register.
Or let the first registration win. Leave the variable unset and the first person to register becomes the administrator. This is deliberately not gated on email verification, because no address has been named and there would be nothing to wait for.
Warning: If the server is reachable before you register, a stranger can sign up first and take the administrator account. Set LIQUIBASE_PLATFORM_INITIAL_ADMIN_EMAIL for any deployment that is exposed before you have signed up yourself.
The setting is also applied at startup, so naming someone who has already registered and verified promotes them on the next restart. Running it repeatedly is safe.
Networking
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.
Variable | Default | Description |
|---|---|---|
|
| HTTPS port exposed on the host |
|
| HTTP port exposed on the host. Requests are redirected to HTTPS. |
|
| Application URL as your users see it |
|
| API URL |
| Value of | Comma-separated list of allowed CORS origins |
In your firewall, allow inbound HTTPS to the server from two sets of clients. Machines that run Liquibase commands must reach the server to send operation data, and your team's browsers must reach it to use the web app.
When you serve the deployment under a real hostname instead of localhost, set LIQUIBASE_PLATFORM_WEB_URL and LIQUIBASE_PLATFORM_API_URL to that hostname. For example, for https://liquibase.internal.example.com:
The web app calls the API at LIQUIBASE_PLATFORM_WEB_URL. The bundled Docker Compose file passes that value to the web app container as RUNTIME_API_URL each time the container starts, so the web app needs no API URL setting of its own. A NEXT_PUBLIC_API_URL line in .env has no effect.
Use ports other than 80 and 443
When another program on the host already holds port 80 or 443, install, start and update stop with LB-SEC-INS-0022 and name the port. Move the server to other ports in one of two ways.
If you have not installed the server yet, pass --http-port and --https-port to install. It writes both ports into .env and adds the HTTPS port to LIQUIBASE_PLATFORM_WEB_URL and LIQUIBASE_PLATFORM_API_URL.
If the server is already installed, set both ports in .env, and add the HTTPS port to both URLs yourself. For example, for HTTPS on port 8443:
Then run start. Liquibase connects to the new address too, so on the machines that run Liquibase, set LIQUIBASE_PLATFORM_API_URL to the same URL, for example https://liquibase.internal.example.com:8443/api.
Application settings
Variable | Default | Description |
|---|---|---|
|
| Runtime mode. Leave set to |
|
| Display name shown in the web app |
|
| When |
Database connections
The API connects to the primary database directly, through two connection pools. LIQUIBASE_PLATFORM_DB_POOL_MAX caps each pool, so each API instance opens at most twice the value plus 2 connections. With the default of 10, that is 22.
Variable | Default | Description |
|---|---|---|
| 10 | Maximum connections in each of the API's two database pools. Must be a positive whole number, or the API does not start. |
| 5000 | How long a request waits for a free database connection, in milliseconds. A request that gets none in that time fails with a 503 response instead of waiting until the API is restarted. |
Keep the total across all API instances, plus room for migrations and administration tools, below the database's max_connections setting. On a managed PostgreSQL service such as Amazon RDS, max_connections depends on the instance size.
Outbound email is off until you set LIQUIBASE_PLATFORM_SMTP_HOST. Until then, the server sends none of these emails:
Password reset emails.
Invitations.
Email address verification, including the verification a change of email address needs.
Password sign-in keeps working. Because no address can be verified while email is off, a user named in LIQUIBASE_PLATFORM_INITIAL_ADMIN_EMAIL is promoted without verifying their address.
Variable | Default | Description |
| Not set | SMTP server host name. Setting it turns outbound email on. |
|
| SMTP port. Set it to the port your mail server uses, commonly |
|
| Set to |
| Not set | SMTP user name. The server signs in to the mail server only when this is set. |
| Not set | SMTP password |
|
| From address for outbound email. Set it to an address your mail server accepts. |
To turn email on, uncomment the SMTP lines in .env and set them for your mail server, as in this example. Be sure to replace your_smtp_password with the password of the SMTP user.
Then run start from the deployment directory. It recreates the API container with the new settings, and the server starts sending email.
To check whether email is set up, go to Administer > Authentication in the web app. The Email delivery card on the authentication settings page reads Configured or Not configured.
Until email works, a user who forgets their password cannot get a reset email. An administrator can create a one-time reset link, valid for one hour, by running this on the Docker host:
liquibase-platform reset-password your_user_email
Replace your_user_email with the address of the account. For example, priya.shah@example.com.
AI integration
AI-assisted features are optional and disabled by default. Teams that do not want AI functionality do not need to configure anything. To enable it, set a provider and its API key.
Variable | Description |
|---|---|
| One of |
| API key for the selected provider |
| Model to use. Defaults to a sensible model per provider if unset. |
| Base URL override. Required only for the |
| Max tokens per AI response. Default: |