How to upgrade a Docker Jitsi Meet server safely

This is the upgrade and recovery workflow for an existing Docker Jitsi server. For a fresh installation, use Docker installation. For a move from pre-rootless releases such as stable-11031, combine this workflow with the rootless migration checklist before starting the new stack.

Reviewed target: stable-11248-2, commit 74d3e6edbb275d700d25de71bddc7088a78b1af4, on 25 October 2026. Keep the target’s Compose files, optional service files and image tags together. This page does not establish that every older deployment can upgrade without an intermediate step or a rehearsal. [S1][S2]

What changed in stable-11248-2?

The 23 October patch release lists two corrections: restoring the Prosody lua-inspect dependency and keeping the custom CA trust store in Jigasi. These are specific upstream release changes, not a blanket guarantee that every login or transcription problem is resolved. [S1]

• If stable-11248-1 cannot load auth_token because inspect is missing, use the exact-error diagnosis.
• If a private-CA transcriber endpoint fails with PKIX errors despite a successful import, use the Jigasi trust-store checks.

The preceding stable-11248-1 release also introduced custom CA support and a template for custom transcription languages. The template alone does not establish environment forwarding; see the release-specific language setup. Preserve the backup and rehearsal steps below even for a patch release. [S10]

1. Record the existing deployment

Record the actual running images and identifiers using version inspection, plus the old release files, local patches, Compose project name, file order, profiles, environment files and command options. Include external proxies, authentication, custom networks and optional services. Keep old images available until recovery has been rehearsed. [S2][S3]

All examples below are Bash on the Linux Docker host. Replace paths and the uppercase project placeholder with your existing values. Keep the same shell session. Set JITSI_CONFIG_DIR to the actual resolved host CONFIG, not an assumed home-directory default. The test -d check below rejects a missing configuration directory. [S3][S8]

set -e
JITSI_PROJECT_DIR=$(pwd -P)
JITSI_CONFIG_DIR=$(realpath /absolute/path/to/CONFIG)
JITSI_BACKUP_DIR=$(realpath -m /absolute/path/to/private-backups/before-upgrade)
test -d "$JITSI_CONFIG_DIR"
test "$JITSI_PROJECT_DIR" != /
test "$JITSI_CONFIG_DIR" != /

JITSI_OLD_COMPOSE=(docker compose -p REPLACE_WITH_EXISTING_PROJECT \
  --project-directory "$JITSI_PROJECT_DIR" \
  -f "$JITSI_PROJECT_DIR/docker-compose.yml")

Start in the current release directory. Add all your existing -f, --env-file and profile options to the array, in their original order, before using it. If Docker requires sudo, put sudo before docker in both command arrays. The -p value must be the existing project name: staging in another directory must not accidentally create a second project. [S3]

Inventory data outside CONFIG, named volumes, symlink targets and external stores separately. The archive example below backs up only the named project and configuration trees; it is not proof that every deployment dependency is included. [S2][S7][S8]

2. Stage the new release separately

Download and extract the selected release into a new staging directory, outside the active project and its data. Do not overwrite the working Compose files. Use the archive download pattern in the installation guide, but skip its fresh-directory setup and password generation. [S1]

Copy your current .env privately into the staged release and compare it with the new env.example. Preserve component passwords, domains, ports and authentication settings. Reapply only reviewed local patches to the new release’s files, and update registry/tag settings together. Do not run gen-passwords.sh as an incidental upgrade step. [S2][S4]

For the reviewed target, the core images use: [S2]

JITSI_IMAGE_REPO=ghcr.io/jitsi
JITSI_IMAGE_VERSION=stable-11248-2

Resolve CONFIG to the existing absolute host path in the staged configuration. Check every other relative bind source too: moving the Compose files changes the base used for relative paths. Define a second array with the same project name and the staged file list. [S3][S5]

JITSI_TARGET_DIR=$(realpath /absolute/path/to/staged-release)
JITSI_NEW_COMPOSE=(docker compose -p REPLACE_WITH_EXISTING_PROJECT \
  --project-directory "$JITSI_TARGET_DIR" \
  -f "$JITSI_TARGET_DIR/docker-compose.yml")

"${JITSI_NEW_COMPOSE[@]}" config --quiet
"${JITSI_NEW_COMPOSE[@]}" config --images
"${JITSI_NEW_COMPOSE[@]}" pull

Add the matching target overlays and environment/profile options before running these checks. Inspect resolved mounts, networks, published ports and services locally; a fully rendered configuration can contain secrets. Validation and a successful image pull do not test startup, migration or a meeting. [S5][S6]

3. Stop and back up before migration

Finish active meetings and stop the old project’s complete service set during the maintenance window. stop retains the containers; ensure no separate process is still writing the data being archived. Arrange backups for any external stores too. [S7]

Choose a new backup directory outside both source trees. The guard rejects a backup nested inside either tree, avoiding an archive that includes its own output. Its parent must already exist. The private archives contain credentials and possibly recordings; keep them protected and off public storage. [S8]

case "$JITSI_BACKUP_DIR/" in
  "$JITSI_PROJECT_DIR/"*|"$JITSI_CONFIG_DIR/"*)
    echo 'Choose a backup directory outside the source trees.' >&2
    exit 1 ;;
esac

umask 077
mkdir "$JITSI_BACKUP_DIR"
chmod 700 "$JITSI_BACKUP_DIR"
"${JITSI_OLD_COMPOSE[@]}" stop

sudo tar -czpf "$JITSI_BACKUP_DIR/project.tgz" -C "$JITSI_PROJECT_DIR" .
sudo tar -czpf "$JITSI_BACKUP_DIR/config.tgz" -C "$JITSI_CONFIG_DIR" .
sudo chmod 600 "$JITSI_BACKUP_DIR/project.tgz" "$JITSI_BACKUP_DIR/config.tgz"
sudo tar -tzf "$JITSI_BACKUP_DIR/project.tgz" >/dev/null
sudo tar -tzf "$JITSI_BACKUP_DIR/config.tgz" >/dev/null
umask 022

If CONFIG is inside the project, these archives duplicate that subtree; allow enough space. Archive listing checks readability, not restore completeness. Rehearse restoration into an empty location and verify representative files, ownership and external data coverage before relying on the backup. Files reached only through symlinks need separate consideration. [S8]

If backup or preparation fails, keep the original configuration unchanged and decide whether to resume the old stack or extend the maintenance window. Do not continue merely because some archive files exist.

4. Apply the migration and start

Complete the rootless migration steps if applicable, including optional data and proxy changes, before starting the target. Retain the old files and backup. Then run the staged command array: [S2][S9]

"${JITSI_NEW_COMPOSE[@]}" up -d --force-recreate
"${JITSI_NEW_COMPOSE[@]}" ps
"${JITSI_NEW_COMPOSE[@]}" images
"${JITSI_NEW_COMPOSE[@]}" logs --tail 100 web prosody jicofo jvb

Recreation is disruptive. restart alone does not apply changed container environment settings. Keep subsequent operations tied to this staged file set and the original project name. Do not delete volumes or prune old images as part of this procedure. [S3][S9]

5. Verify before reopening access

• Check the running images, startup errors and expected persistent data locations. Confirm authenticated accounts and moderator/guest restrictions with separate browsers.
• Verify the publicly served HTTPS certificate using SSL checks. A local certificate file is not proof of what the endpoint serves.
• Run a three-participant meeting across different networks, reconnect and test supported screen sharing. A two-participant call can use P2P and miss a bridge problem; see media diagnostics.
• If enabled, make a short recording or transcript and verify its intended storage and access. Check branding and custom configuration after a fresh page load.

These are acceptance checks to perform on your server, not tests completed by this article. Keep monitoring renewal separately from initial HTTPS success.

6. Roll back from clean state

An old image tag cannot reverse new data formats or recover missing files. Keep the target stopped while planning recovery, preserve post-upgrade data separately, and account for any changes made since the backup. Extracting a backup over changed directories leaves files absent from the archive in place. [S8][S9]

The following only prepares clean restore copies inside the private backup directory; it does not switch the live deployment. [S8]

JITSI_RESTORE_DIR=$(mktemp -d "$JITSI_BACKUP_DIR/restore.XXXXXX")
mkdir "$JITSI_RESTORE_DIR/project" "$JITSI_RESTORE_DIR/config"
sudo tar -xzpf "$JITSI_BACKUP_DIR/project.tgz" -C "$JITSI_RESTORE_DIR/project"
sudo tar -xzpf "$JITSI_BACKUP_DIR/config.tgz" -C "$JITSI_RESTORE_DIR/config"

Before restarting the old stack:

1. Stop the target using its exact Compose array. Preserve its new state for investigation or recovery.
2. Arrange a controlled replacement of the original project and CONFIG with the verified clean copies, at the paths expected by the old configuration. If the paths overlap, coordinate that replacement as one restoration. Do not merge trees or erase the only copy of either state.
3. Restore any external data through its own recovery procedure. Ensure the old image identifiers and complete file set remain available.
4. Start with the restored old project options and verify accounts, HTTPS and a meeting again.

The replacement commands depend on your actual paths, mount layout and storage, so there is no universal live mv or extraction command here. Recovery returns the backed-up data state; later accounts, recordings or changes require separate reconciliation.

Debian and Ubuntu packages

This workflow is for Docker deployments. Native packages have different service, configuration and data management; use the Ubuntu installation guide for that route rather than running these container commands against host services.

Open questions and maintenance

The release files, Compose models and a synthetic archive/restore example were checked locally. No production upgrade, Linux permission migration, full restore cutover, public CA issuance or real meeting was performed for this revision. Rehearse on a representative server. Review the target’s release notes and migration behavior each time the pin changes.

Sources

Reviewed 25 October 2026.

• [S1] Docker Jitsi stable-11248-2 release, published 23 October 2026.
• [S2] Pinned target Compose file and environment example.
• [S3] Compose project identity and multiple-file path rules.
• [S4] Pinned password generator.
• [S5] Compose config.
• [S6] Compose pull.
• [S7] Compose stop.
• [S8] GNU tar, Bash, realpath and mktemp.
• [S9] Compose up, restart limitations and down volume behavior.
• [S10] stable-11248-1 release notes, published 22 October 2026.