Upgrade the NuFi app

Moving a running deployment to a new app release without losing anyone's conversations.

The NuFi app ships as ghcr.io/dudaji-vn/nufichat:vX.Y.Z; a new release is a new tag. Upgrading is pinning the deployment at that tag, with a backup taken first so the step back exists.

Before

Read the release notes for the tag. Three things force a maintenance window:

a database schema change (rare; the app runs its migrations on first start of the new image, and the old image cannot always read the result)
a renamed or removed key in librechat.yaml
a new required environment variable

Then take the backup, whatever the notes say:

cd deploy/platform
docker compose exec -T mongodb sh -c \
  'mongodump --archive --gzip -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin' \
  > "/backups/mongo_pre_v0.1.12.gz"

Backup and restore has the Postgres side too; the app's data is in MongoDB.

Move the pin

On the compose stack, the librechat service in deploy/platform/docker-compose.yml:

librechat:
  image: ghcr.io/dudaji-vn/nufichat:v0.1.12   # was v0.1.11

docker compose pull librechat
docker compose up -d librechat
docker compose logs -f librechat

On Railway, the nufi-chat service builds a wrapper image whose base is the BASE variable: set it to ghcr.io/dudaji-vn/nufichat:v0.1.12 and redeploy. On the standalone wrapper stack in deploy/railway, set IMAGE_TAG=v0.1.12 in .env and docker compose pull && docker compose up -d.

Watch the first start

Migrations, when there are any, run once and log at INFO. Wait for the health check to go green (docker compose ps librechat), then:

Sign in. Pick a model. Send a message and get a reply.
Open a conversation from before the upgrade.
Open the console; the usage page still shows history.
Open Langfuse; the message you just sent has a trace.

Step back

Put the previous tag back and pull. If the new version ran a migration the old one cannot read, restore the MongoDB dump from before the upgrade first:

docker compose exec -T mongodb sh -c \
  'mongorestore --archive --gzip --drop -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin' \
  < /backups/mongo_pre_v0.1.12.gz

This is why the backup before every upgrade is not optional.

What this page does not cover

The gateway, the console, Studio and Works each have their own image and their own pin; the same pull-and-recreate applies to the console (NUFI_CONSOLE_TAG), and the gateway is rebuilt from source, not pulled: see Run the stack locally. Which tag exists for what is in GHCR images.