Upgrading Lombok

This page covers how to move an existing self-hosted Lombok deployment to a newer release. It assumes you already have Lombok running. For first-time installation, see the deployment pages instead.

Before upgrading, make sure you know how you would restore your deployment if something goes wrong. This page intentionally focuses on the upgrade workflow itself rather than broader backup or disaster-recovery procedures.

How Lombok is released

Lombok is distributed as Docker images published to the GitHub Container Registry (GHCR). A release is cut by tagging the source repository with a version tag (vX.Y.Z), which builds and publishes the images for that version.

Two image variants are published for each release, matching the two supported deployment shapes:

Variant	Image	Postgres
Standalone	`ghcr.io/lombokapp/lombok-standalone`	Bundled inside the container
Separate database	`ghcr.io/lombokapp/lombok`	External PostgreSQL

Each variant is published for both linux/amd64 and linux/arm64, and is tagged in two ways:

:<version> — an immutable tag for a specific release
:latest — a moving tag that points at the most recent release

[!NOTE] Pinning to a specific :<version> tag makes upgrades explicit and repeatable. :latest works too, but it means the image changes the next time you pull. Choose whichever matches how you operate.

Make sure you upgrade using the same variant you originally deployed. Switching between standalone and separate-database images changes where your database lives and is not a routine version upgrade.

Before you upgrade

Record your current version. You can read the build identifier of the running server from the unauthenticated endpoint:
Terminal window
```
curl http://<your-host>/api/v1/public/build-id
```
This returns the build ID baked into the running image, which is useful for confirming both your current version before the upgrade and the new version afterwards.
Review the release notes for the version you are moving to so you know about any changes that affect your deployment.
Take a backup if the upgrade is configured to run database migrations on startup. In the reference deployment flow, RUN_MIGRATIONS=true applies pending migrations automatically on startup, and those migrations are forward only. Taking a database backup before upgrading gives you a recovery point if you need to roll back.

What persists across an upgrade

Upgrading replaces the application container with one built from a newer image. It does not, by itself, delete your data, provided your persistent storage is kept:

Object data lives in your configured S3-compatible storage and is external to the container.
Database data:
- Standalone: Postgres stores its data under /var/lib/postgresql/data inside the container. This must be backed by a persistent volume.
- Separate database: data lives in the external PostgreSQL instance you operate.

Keep the same volumes, database, environment variables, and S3 configuration when you recreate the container. Changing them is a configuration change, not a routine upgrade.

Database migrations on startup

When the server starts with RUN_MIGRATIONS=true, it runs any pending database migrations automatically before it begins serving requests. With CREATE_DATABASE=true, it will also create the target database if it does not yet exist.

Practically, this means a normal upgrade is: pull the new image, recreate the container, and let it migrate on boot. There is no separate manual migration step for a standard deployment.

[!IMPORTANT] Migrations are applied forward only. There is no automatic down-migration on startup, so downgrading to an older image after migrations have run is not a supported path. This is the main reason to take a database backup before upgrading.

Upgrade steps

Docker Compose

If you run Lombok with a Compose file:

Update the image tag in your Compose file to the version you want, or keep :latest if you intentionally track the latest release.
Pull the new image:
Terminal window
```
docker compose pull
```
Recreate the container:
Terminal window
```
docker compose up -d
```

Compose will recreate the service from the new image while leaving your declared volumes in place. On startup the server applies any pending migrations.

`docker run`

If you run the container directly:

Pull the new image:

docker pull ghcr.io/lombokapp/lombok-standalone:<version>
# or, for the separate-database variant:
docker pull ghcr.io/lombokapp/lombok:<version>

Stop and remove the existing container.
Start a new container from the new image, reusing the same environment variables, volume mounts, and ports as before.

Because your data lives in mounted volume(s) and/or your external database and S3 storage, recreating the container does not discard it as long as you reattach that same storage.

Verify the upgrade

After the container is back up:

Confirm the reported build:
Terminal window
```
curl http://<your-host>/api/v1/public/build-id
```
The returned build ID should reflect the new release.
Check the container logs to confirm startup completed, including the database and migration steps, without errors:
Terminal window
```
docker compose logs -f
# or: docker logs -f <container>
```
Sign in and confirm your data is present and the application behaves as expected.

If something goes wrong

If the new version does not start cleanly:

check the container logs first
if you took a backup beforehand and need to revert, restore the database from that backup before starting an older image, since migrations applied by the newer version may not be understood by an older one

For general operational issues unrelated to upgrading, use your normal incident and debugging workflow for the deployment environment.