Configure Liquibase Secure server

Liquibase Secure server is configured through a single .env file in the deployment directory. The liquibase-platform install command generates this file with secure values, so a standard installation needs no manual configuration. Use this page when you need to change ports, set the public URL, enable email, or manage the generated secrets. The shipped .env.sample file documents every available setting.

To apply a configuration change, edit .env and restart the stack:

./liquibase-platform stop && ./liquibase-platform start

Registry settings

The install command sets both of these values for you.

Generated secrets

The install command generates these with cryptographically secure random values. If you are configuring a manual deployment, generate each value with the command shown in .env.sample.

Warning: Back up your .env file. Losing LIQUIBASE_PLATFORM_ENCRYPTION_KEY means permanent loss of access to every stored database credential. Keep a copy of .env alongside your database backups.

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: The named user is promoted only after they verify their email address. 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.

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.

Change the port variables only if 443 and 80 are already in use on the host. 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, LIQUIBASE_PLATFORM_API_URL, and NEXT_PUBLIC_API_URL to that hostname. For example, for https://liquibase.internal.example.com:

Application settings

Email

Outbound email powers password resets and invitations. It is disabled by default. To enable it, uncomment and set the SMTP variables in .env.

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.