Upgrading and backups

An upgrade replaces the application code and may also change the database
schema. You can restore the previous code by deploying the old image tag, but
deploying an old image does not reverse schema changes.

Self-hosting overview explains when each platform runs
migrations during a fresh installation. Upgrades use the same schedule, but
must also preserve the data already stored in the database.

Back up before every upgrade

Back up Postgres. Boards, feedback, votes, comments, changelog entries,
accounts, sessions and similarity embeddings are all stored there. Without a
database backup, you cannot restore this data.

pg_dump --format=custom "$DATABASE_URL" > feedlog-$(date +%F).dump

You can run this command while the application is running; no downtime is
required. Test the backup by restoring it to a temporary database before using
it as a recovery point.

Back up uploaded files separately. Their location depends on your storage
configuration:

If no S3_* variables are set, uploads use a local-filesystem driver that
writes inside the container. The bundled compose.yml mounts a named volume at
/app/.data, so these files persist when the container is removed. If you used
the one-line docker run command without adding -v, the files do not persist,
and the docker rm step in a Docker upgrade removes them.

Keep a copy of your environment variables. In particular, preserve
BETTER_AUTH_SECRET: changing it signs out all users and invalidates pending
password-reset and email-verification links.

Upgrading

Docker

docker pull ghcr.io/linkcraftstudio/feedlog:v0.2.0
docker stop feedlog && docker rm feedlog
docker run -d --name feedlog -p 3000:3000 \
  ... same env vars as before ... \
  ghcr.io/linkcraftstudio/feedlog:v0.2.0
docker logs -f feedlog        # wait for "Database migration completed"

# With the bundled compose file: edit the image: tag, then
docker compose pull app && docker compose up -d app

Vercel

git pull upstream main
git push          # Vercel rebuilds; migrations run in the build step

Cloudflare Workers

git pull upstream main
pnpm install
pnpm build:cf && pnpm deploy:cf
# then visit the site as a signed-in admin — see below

Full per-platform instructions stay in the repository, versioned with the
release you're deploying:
Docker ·
Vercel ·
Cloudflare Workers

Which image tag to deploy

You can use latest while evaluating FeedLog. In production, use a vX.Y.Z or
sha- tag. Otherwise, running docker compose up -d after an unrelated host
restart may deploy a new version and run migrations unexpectedly. The bundled
compose.yml therefore uses a version tag.

Migrations during an upgrade

Migrations use the same schedule as a fresh installation, but an upgrade must
account for existing data if a migration fails.

• Docker — the container applies pending migrations at startup. A Postgres
  advisory lock serializes them, so two containers starting at once won't apply
  the same migration twice; the second waits and then finds no pending
  migrations. The lock does not prevent an old application version from running
  against the new schema, so stop the old version before starting the new one
  instead of replacing replicas one at a time. Wait for Database migration completed in the logs before sending traffic to the new container. /health
  returns 200 when the process is running, which may happen before migrations
  finish.
• Vercel — migrations run during the build, before the Nuxt build step. A
  migration failure stops the deployment, and the previous deployment continues
  serving, so the failed schema change does not reach production. This requires
  DATABASE_URL to be set for both the Production and Preview scopes, and your
  Postgres to be reachable from Vercel's build machines.
• Cloudflare Workers — a Worker has no startup phase, so migrations run on
  request. An upgrade therefore requires one manual step, described below.

Cloudflare Workers requires an admin to confirm the upgrade

After pnpm deploy:cf, if the release contains migrations that haven't been
applied, the Worker puts the site into setup mode: every page request redirects
to /setup, and every /api/ request returns 503 with NOT_INITIALIZED. The
/setup page then attempts to run the migration. Because this is an upgrade
rather than a first installation, the endpoint requires a signed-in admin.
Anonymous callers receive "Administrator required". This restriction prevents
visitors from triggering schema changes.

In setup mode, the Worker redirects every request except /setup,
/api/auth/**, /health and static assets. This includes the pages that contain
the sign-in dialog. If you are not already signed in as an admin when the new
Worker goes live, you cannot sign in through the interface.

Sign in before you deploy

Open your instance and confirm you're signed in as an admin before running
pnpm deploy:cf. The session cookie remains valid after the deployment. When
you next load a page, the Worker redirects you to /setup, runs the migration,
and returns you to the original page. If you deploy before signing in, the site
only serves /setup, which returns "Administrator required".

If /setup does not continue, request /api/_migrate/status directly. It
reports state, the number of applied migrations and the number of expected
migrations.

Rolling back

To roll back the application code, deploy the previous image tag, redeploy the
previous Vercel deployment from the dashboard, or check out the old commit and
run pnpm deploy:cf again.

FeedLog does not support rolling back the schema. Migrations are recorded in a
tracking table and only move forward; FeedLog ships no down-migrations. Past
releases have dropped indexes and unique constraints and tightened columns to
NOT NULL, and an older build starting against that schema either misbehaves or
refuses to start.

Before rolling back, determine which case applies:

• The new version has a bug and applied no migrations. Deploy the old tag.
  No database restore is required. This covers most rollbacks.
• The new version applied migrations. Deploy the old tag and restore the
  Postgres backup you took before the upgrade. Data written between the upgrade
  and the rollback is lost, so upgrade at a quiet hour.

On Docker and Vercel, the deployment log shows which migrations ran. On
Cloudflare, check /api/_migrate/status after the deployment.

Restore the database, not just the image

Rolling the container back to a previous tag does not undo a migration. If the
new version migrated your schema, you need the database backup taken before the
upgrade.

Common errors

The container starts, immediately exits and repeatedly restarts. A migration
failed. The Database migration failed line in docker logs feedlog contains
the specific error. The schema is partly applied at this point. Fix the cause
before restarting, or restore the backup and try the upgrade again.

Pages return 500 right after a container restart, then recover. The process
starts listening while migrations are still running. Wait for
Database migration completed before sending traffic to the container. A 200
response from /health does not mean the schema is ready.

The Vercel deploy failed on the migrate step. The previous deployment
continues to serve traffic. Common causes: DATABASE_URL isn't checked for the
Production scope, or the database isn't reachable from Vercel's build IPs (a
self-hosted Postgres behind a VPN won't be).

/setup returns "Administrator required" and you cannot sign in. The Worker
was deployed before an admin session was established. Use a browser that still
has a valid admin session, then reload /setup.

Uploaded images 404 after a Docker upgrade. The instance used local
filesystem storage without a volume on /app/.data, so docker rm removed the
files. They cannot be recovered. Configure S3_* storage before the next
upgrade. See Configuring external services.

Everyone was signed out after the upgrade. BETTER_AUTH_SECRET changed,
usually because the new deployment generated a new value instead of reusing the
old one. Restore the original value to restore the existing sessions.