Upgrading

This guide covers upgrading your lnkify instance to a new version. The process involves pulling the latest code, rebuilding images, applying database changes, and restarting services.

Standard Upgrade Workflow

# 1. Pull the latest code
git pull origin main

# 2. Rebuild all images
docker compose build --no-cache

# 3. Apply any database changes
docker compose run --rm server pnpm run db-init

# 4. Restart services with new images
docker compose up -d

After restart, check that everything is healthy:

docker compose ps
docker compose logs -f server

Step-by-Step Breakdown

1. Pull Latest Code

git pull origin main

If you have local changes to the .env file or other config files, stash them first:

git stash
git pull origin main
git stash pop

2. Rebuild Images

docker compose build --no-cache

The --no-cache flag ensures a clean build. This prevents stale layers from causing issues. If you're confident the build cache is fine (e.g., dependency changes are minimal), you can omit --no-cache for a faster build.

3. Apply Database Changes

docker compose run --rm server pnpm run db-init

This runs prisma migrate deploy, applying any committed migrations that shipped with the new version, in order. It is idempotent — already-applied migrations are skipped — and forward-only.

This step is also run automatically when the server container starts (docker-start.sh), so on a normal docker compose up -d the migrations apply on their own. Running it explicitly first is a safe way to surface migration errors before swapping the running container.

Always back up your database before upgrading. Migrations are forward-only; reverting a schema change requires restoring a backup. See Database for backup instructions.

4. Restart Services

docker compose up -d

Docker Compose detects changed images and recreates only the affected containers. The -d flag runs services in the background.

Zero-downtime upgrades are not supported in single-replica mode. There will be a brief interruption (a few seconds) while containers restart. Caddy will buffer or retry requests during this window.

Checking for New Environment Variables

Between versions, new environment variables may be added. Check .env.example for any variables not present in your .env file:

diff .env.example .env

Add any missing variables to your .env before restarting. Missing required variables will cause the server to fail at startup.

Rollback

If the upgrade causes issues, roll back to the previous version:

# 1. Checkout the previous tag or commit
git checkout v1.2.3   # or the previous commit hash

# 2. Rebuild images from the older code
docker compose build --no-cache

# 3. Restart with older images
docker compose up -d

If you have a database backup from before the upgrade, restore it:

docker compose exec -T db psql -U postgres lnkify < backup-pre-upgrade.sql

Note: Prisma migrations are forward-only — a schema change is not automatically reversed by checking out older code. Restoring a pre-upgrade database backup is the reliable rollback for schema changes. This is why backups are critical before upgrading.

Checking Logs During Upgrade

Monitor server logs to catch issues early:

# Follow server logs
docker compose logs -f server

# Follow all service logs
docker compose logs -f

Common post-upgrade issues:

• Missing new environment variables → check .env.example
• Database connection errors → verify DATABASE_URL and db health
• Prisma errors → the schema may need manual migration steps

Image Tags

The default docker-compose.yml uses local builds (build: context), so the standard workflow clones the repository and builds images locally.

CI also publishes pre-built images to GitHub Container Registry (ghcr.io/lnkify/lnkify-app/lnkify-server, -app, and -docs) on pushes to main and on tags. To upgrade by pulling instead of building, point the compose services at the published image: tags and run docker compose pull && docker compose up -d in place of the build step.

Breaking Changes

Breaking changes between versions will be documented in the GitHub releases. Look for:

• Environment variable renames — old names may stop working.
• Database schema changes — may require manual migration steps.
• API deprecations — endpoints or GraphQL fields may be removed.
• Configuration format changes — the Caddyfile or docker-compose.yml structure may change.

Always read the release notes before upgrading.

Next: Troubleshooting