Why a Jitsi Docker upgrade to stable-11146 needs its own plan
The rootless release of the Jitsi Docker setup changes file ownership, directory layout and write access, so the upgrade is a storage migration as much as an image update. Since stable-11146, every service runs as an unprivileged user with uid and gid 1000, holds no effective Linux capabilities and runs on a read-only container filesystem. Only /run and /tmp are writable tmpfs mounts, and every directory the containers write to must be writable by uid 1000. A team that pulls the new images and restarts may find services failing at startup or unable to persist data. This section and the rest of the page cover the Docker setup only. Debian and Ubuntu package installations follow a different path and are not covered here.
Plan the move as a direct upgrade from an older Docker release onto stable-11146 or later. Before you schedule it, confirm with the Jitsi handbook whether your starting release needs any intermediate step, since the handbook's upgrade guidance governs your environment. The jitsi-meet repository lists stable/jitsi-meet_11248, published September 14, 2026, as the latest stable build we can confirm, but check the current tag when you plan because newer builds may exist. Pin the exact image tags for every service you run, including web, prosody, jicofo, jvb and any optional containers, so that a rollback target is known before the change window opens.
The data split is the part most likely to cause trouble. From stable-11146, the CONFIG directory separates per-service configuration, which is read at startup, from ${CONFIG}/storage for persistent state and ${CONFIG}/tmp for regenerable runtime files. On first start, Prosody data and web TLS material move into ${CONFIG}/storage automatically. Jibri recordings, logs and transcripts do not, so you must move them yourself if you need them afterward. Inventory those directories on the current host before the upgrade, record their sizes and owners, and decide which Jibri output must survive. That decision determines whether the migration is a routine restart or a planned data copy.
Keep the old directories in place until the new setup is verified. The Jitsi Docker guide states they are left untouched after the upgrade and can be removed once the new setup works, which gives you a fallback copy while you test. Verification should cover ownership of the storage and tmp directories for uid 1000, a conference with audio and video between two clients, and a working HTTPS certificate. The Jitsi handbook says a proper domain certificate is necessary for working audio and video and warns that self-signed certificates cause problems, especially with mobile clients. Assign one owner for the storage migration and get the file list signed off before the change window.
What changes in the rootless release and what you must do
This table compares each change in the rootless release with its impact on an existing Docker-based Jitsi and the action you need to take. Read it before the first start on the new release, because permissions and directory moves determine whether services come up with their data intact. The main takeaway is that Prosody data and TLS material move automatically, while Jibri files and permission checks remain your responsibility.
| Change | Impact | Action needed |
|---|---|---|
| Service user | Every service runs as uid and gid 1000 with no effective Linux capabilities, so processes lose privileged operations. | Confirm that host paths and volumes allow uid 1000 access before starting the containers. |
| Read-only filesystem | The container filesystem is read-only, with /run and /tmp as writable tmpfs mounts. | Remove custom volumes or overrides that write to other paths inside the container filesystem. |
| CONFIG directory split | Per-service configuration is read at startup, ${CONFIG}/storage holds persistent state and ${CONFIG}/tmp holds regenerable runtime files. | Back up ${CONFIG}/storage and treat ${CONFIG}/tmp as disposable. |
| Write access for uid 1000 | Every directory the containers write to must be writable by uid 1000. | Check ownership of each ${CONFIG} subdirectory and set it to uid 1000 before starting services. |
| Automatic and manual data moves | Prosody data and web TLS material move to ${CONFIG}/storage on first start. Jibri recordings, logs and transcripts do not move automatically. | Move Jibri recordings, logs and transcripts yourself to keep them, and confirm the target paths in the Docker guide. |
| Old directories left in place | The old directories are left untouched after the upgrade. | Keep them until the new setup works, then remove them. |
Which data moves automatically and which you must move yourself
The split between automatic and manual data moves decides where your upgrade work goes. According to the Jitsi Docker guide, Prosody data and web TLS material move to ${CONFIG}/storage automatically on the first start after the upgrade. Jibri recordings, logs and transcripts do not move on their own, so you must copy them into the new layout yourself if you want to keep them. Do not treat the automatic move as finished until you have checked it. Before you let users back in, confirm that the Prosody data and certificate files exist under ${CONFIG}/storage and that a test meeting signs in and presents the expected certificate.
On first start, the containers run the new release against your existing CONFIG directory and perform the move once. You cannot assume that a second run will repeat it, and new state written after users return can complicate a later correction, so schedule the checks in a maintenance window. Ownership matters as much as location. Every directory the containers write to must be writable by uid 1000, so a copy that keeps old root ownership can leave a service failing to start or failing to write. Check ownership after every copy you make by hand, not only after the automatic move.
Jibri data is the main exposure because nothing fails loudly when it is missed. A stack can start cleanly while earlier recordings, logs or transcripts are simply absent from the new setup. Recordings are often the most sensitive output of a meeting platform, and a missed copy may leave the old directories as the only remaining source. For that reason, keep the old directories until the new setup is verified. The Jitsi Docker guide states that they are left untouched after the upgrade and can be removed once the new setup works. Remove them only after you have confirmed sign-in, a test recording, and access to the logs you need, and apply your recording retention policy to the copies as well.
The manual step may not apply to your deployment. Jibri and Jigasi are optional containers, so open the .env file and confirm which optional services are enabled before you plan the move. If Jibri is disabled, there are no recordings to transfer, although you still need to decide which logs must be kept. If Jigasi is disabled, there are no SIP dial-in transcripts to carry over. Confirm the exact directory names and steps against the Docker guide for the release you are installing, rather than relying on paths from an older version.
Preparing a Docker Jitsi host before you touch the containers
The rootless containers change which directories each service can write to, so most upgrade problems trace back to file ownership and paths. The four areas below cover what to save, what to record, which optional containers need attention and what to rehearse. Work through them in order, because the backup is your rollback point and the test host relies on the same inventory.
Full backup before any change
Take a complete copy of the CONFIG directory and every Docker volume before you change ownership or pull new images. Preserve numeric owner, group and permission bits, because the upgrade requires uid 1000 and gid 1000 to write to the directories the containers use, and you need the original values to roll back. Store the copy off the host and confirm you can restore it into an empty directory. The old directories remain after the upgrade, but they are not a substitute for a tested backup.
Inventory of .env and mounted config
Record the .env file and every custom web, Prosody or Jicofo file that a container mounts from the host. Note which authentication settings are in use, such as internal accounts, JWT, LDAP or Matrix, so you can confirm them after the upgrade. Each mounted file must remain readable by uid 1000, and any custom file a container writes to needs a writable path in the new layout. Check the compose file for every bind mount, including ones added months ago and forgotten.
Enabled optional containers
List which of jibri, jigasi, Etherpad and Excalidraw are enabled on this host, and record where each one keeps its data. Jibri recordings, logs and transcripts must be moved by hand to keep them, so identify those paths before the window opens. Jigasi transcription and SIP settings sit in the .env file and need the same check as the core services. The Jibri project states that a single Jibri supports one recording at a time and should run on its own machine or VM, so confirm where your recording host runs.
Test host from the same release
Build a test host on the target stable release with a copy of your .env file, then restore the backup into it. Run the upgrade there first to see which data moves automatically, such as Prosody data and web TLS material on first start, and which files you must copy yourself. Confirm that sign-in works, that a room with two participants connects and that each enabled optional container starts. Use the results to set the production change order and the rollback point.
The upgrade sequence, with checks and rollback points
This sequence moves a Docker-based Jitsi onto the rootless, read-only containers with a way back at each stage. Each step ends with a check that tells the operator whether to continue, and the old directories and previous image tag stay in place until the new stack passes verification.
Freeze changes and announce the window
The deployment owner announces a maintenance window to users and the operations team, and pauses configuration changes, certificate renewals and image updates on the host until the window closes. Nothing else should touch the stack during the window. Check: the change owner confirms in writing that the window is open, names an escalation contact, and confirms that no other change is scheduled on the same host. Rollback point: no system change has happened yet, so the window can be cancelled with the running service left as it is.
Back up and record the current release
Copy the entire existing CONFIG directory to separate storage, save the .env file alongside it, and record the image tag each running container uses along with your compose file. If your tooling cannot copy Prosody data consistently while the stack is running, stop the stack first. Check: list the backup, confirm file sizes match the source, and run a test restore into a scratch directory to confirm the files are readable. Rollback point: this backup is the restore source for every later step, so do not continue until the test restore succeeds.
Stage the new configuration and directories
Begin with the configuration templates in the Docker guide, then carry your values across using the exact variable names that guide lists. Confirm that ${CONFIG}/storage and ${CONFIG}/tmp exist, and create them if they do not. Leave the old directories in place. Check: a directory listing shows both new directories, and a diff between the new .env and the saved copy shows only the values you intended to change. Rollback point: the old directories and the saved .env are untouched, so reverting means pointing the stack back to them.
Set ownership for uid 1000
Set ownership so that uid 1000 can write to every directory the containers use, including ${CONFIG}/storage, ${CONFIG}/tmp and any other directory a service writes to at startup. Each service runs as uid and gid 1000 with no effective Linux capabilities and a read-only root filesystem, so a directory owned by another user will stop a container from starting. Check: run a write test as uid 1000 in each directory, or start one service and read its log for permission errors. Rollback point: ownership can be restored from the backup in the second step, and the old directories still hold the previous ownership.
Move Jibri recordings, logs and transcripts
Skip this step if you do not run Jibri, Jigasi transcription or any other component that writes recordings, logs or transcripts you need to keep. Otherwise, copy those files from the old directories into the locations the Docker guide specifies for the new layout. The guide says these files must be moved manually, while Prosody data and web TLS material move on first start. If Jibri runs on its own host, perform the copy there. Check: file counts and total sizes match between old and new locations, and a sample recording plays. Rollback point: the originals remain in the old directories until the final step.
Pull the new images and start the stack
Pull the images for the target release, record their tags, and start the stack with the new configuration and directories. Watch each container until it reports running. Prosody data and web TLS material move to ${CONFIG}/storage automatically on first start, so a rollback after this point depends on the backup from the second step, not only on the old directories. Check: every container runs without restart loops, and logs show no permission denied or read-only filesystem errors. Rollback point: if the check fails, stop the stack, restore the previous image tag and the saved .env, and point CONFIG back to the old layout.
Verify web, conference, logs and TLS
Test the stack end to end before users return. Load the web app in a browser, join a test conference with audio and video from two devices, and confirm that media flows in both directions. Read the Prosody and Jicofo logs from the start of that session and look for errors. Confirm TLS: the certificate should be issued for your domain by a trusted authority, and the browser should show no warnings. Check: all four areas pass, and the results are recorded with the time and the tester's name. Rollback point: any failure keeps the previous image tag and old directories in place until the fault is fixed or the change is reverted.
Retain old directories until sign-off
Keep the old directories, the saved .env, the backup and the previous image tag until the new setup has handled normal use and the owner has signed off. The Docker guide says the old directories can be removed once the new setup works, so removal belongs at this point, after the new setup is proven. Check: the sign-off record names the release, the date of the test and the person who approved removal. Then remove the old directories and keep the backup according to your retention policy.
How to test the upgrade and roll back if a container fails
The test plan should prove that the upgraded stack works end to end before any user joins a production conference. The most useful step is a rehearsal on a copy of production data. Copy the existing CONFIG directory, including Prosody data, web TLS material, Jibri output and any transcripts, and run the upgrade against that copy on a host that matches production in network layout, published ports (80/TCP, 443/TCP and 10000/UDP) and container settings. Record which files moved into ${CONFIG}/storage on first start and which you moved by hand. Compare that list with what you expected before you touch production. Confirm the exact file list and sequence with your own change records, because your environment may include extensions that this guide does not cover.
Run test conferences with two or more participants, using each browser your users rely on. A single participant proves little, because media only flows through the videobridge once a second participant joins. Check audio, video and screen sharing in both directions, and confirm that the bridge still reaches participants through UDP 10000 and, where you rely on it, TCP fallback on 5349. If you run Jibri, start a recording and a stream, then confirm that the output lands where you expect and that Jibri logs show no permission errors. Jibri recordings and transcripts are not moved for you, so this check should also confirm that your manually moved copies are readable by the new containers. Repeat the conference test after any restart of the stack, not only once.
Test authentication for the method your deployment actually uses: internal XMPP accounts, JWT tokens, LDAP, Matrix user verification or the hybrid Matrix plus JWT mode. Sign in with a known account, create a room with a moderator and join it as a guest, and confirm that the expected rules apply to each. Because every service now runs as uid and gid 1000 on a read-only filesystem, a credential file or directory the container cannot read may fail only at login, so test every method rather than assuming the startup logs are enough. For TLS, open the public URL in each browser under test and confirm that the existing certificate chain and expiry date are served. The web container should use the TLS material now stored under ${CONFIG}/storage, so confirm that the served certificate matches the one you expect.
Plan the rollback before the change window opens. The rollback path is to restore the previous image tag and bring back the preserved old directories, which the Docker guide says are left untouched after the upgrade. Rollback is clean only while no one has created new data in the new layout. Once users have held conferences, created persistent state or produced recordings under the new paths, returning to the old release may leave that data unread or stranded, and you would need to move it back by hand. Set a clear go or no-go point after the test conferences and authentication checks, and decide who approves a rollback. The facts available here do not describe a built-in downgrade, so every rollback step is manual. Confirm the steps, approvals and evidence requirements with your own change process before the upgrade is scheduled.
What makes a Jitsi Docker upgrade longer or harder
This table lists the factors that lengthen or complicate an upgrade from a Docker Jitsi release older than stable-11146 to the rootless containers. Read each row as a question to answer about your current deployment before you schedule the change window. The more of these factors that apply to your setup, the more testing, data moves and rollback checks you should plan for.
| Driver | Why it matters | What to check |
|---|---|---|
| Optional containers enabled | Each enabled container (jibri, jigasi, Etherpad, Excalidraw) has its own configuration and must be checked against the new per-service layout. | List which optional services run today and confirm each one starts cleanly with its configuration read from the new directory layout. |
| Jibri recordings, logs and transcripts | Recordings, logs and transcripts are not moved automatically, so files left in the old directories are lost once those directories are removed. | Measure the total size and retention period of existing recordings and confirm the new storage location has room for them before the change. |
| Custom mounts and overrides | Compose overrides, bind mounts and custom files that assume root access or old paths will fail under read-only filesystems and uid 1000. | Review every override and bind mount for root-owned paths, hard-coded old directories and any write access the containers now lack. |
| Authentication method in the .env file | Moving off the deprecated secure domain method or switching to JWT, LDAP or Matrix changes variables the containers read at startup. | Identify the authentication mode currently set in the .env file and confirm the target method, user changes and guest domain before the change window. |
| Number of videobridges and scale-out | Each additional videobridge is another container to update, verify and roll back, and each one needs its own writable directories. | Count the videobridge instances, confirm how they connect to the central services and decide whether they can be updated one at a time. |
| Availability requirement for the change window | Active meetings drop during container restarts, and a single-server deployment has no spare capacity to keep meetings running during the change. | Agree with business owners when meetings can be interrupted and confirm whether a staging copy exists for rehearsing the upgrade. |
Questions teams ask before upgrading Jitsi Docker
Does the upgrade delete the old Jitsi directories automatically?
No. The Jitsi Docker guide says the old directories are left untouched after the upgrade, so nothing is removed for you. Keep them in place while you verify the new setup: join a test call, run a recording if you use Jibri, confirm that logins work and check container logs for write errors. The new layout also separates persistent state under the storage directory from regenerable runtime files under the tmp directory, so do not expect the old tree to map one to one onto the new one. Once everything works, you can delete the old directories yourself. Until then, they and a verified backup form your rollback path.
Do Jibri recordings move to the new layout on their own?
No. Prosody data and web TLS material move to the storage directory automatically on first start, but Jibri recordings, logs and transcripts must be moved manually if you want to keep them. Copy them into the new storage location before you retire the old directories, and confirm that the files are writable by uid 1000 so the containers can read and write them. This step is easy to miss, so write it into the maintenance plan. Jibri also runs on its own machine or VM, and a single Jibri supports only one recording at a time, so check each recording host separately.
Can our own team upgrade Jitsi Docker to stable-11146 in-house?
Yes, if your team already runs Docker and can follow the official Jitsi Docker guide. Build a test host from a copy of your current configuration, rehearse the upgrade there, and take a verified backup of the configuration and any recordings before you change production. Your engineers then review the .env file, set directory ownership for uid 1000, apply the new per-service configuration and test calls, recordings and authentication. Keep the work in-house when the deployment is standard and one person can own it after the change. If the setup is heavily customized, a partner can take on the planning and testing.
What drives the cost and effort of this Jitsi upgrade?
Cost depends mainly on scope. The same version change can be a short task on a bare setup or a multi-stage project on a complex one. The main drivers are which containers run (web, Prosody, Jicofo, JVB, Jigasi and Jibri), which authentication mode the .env file configures, whether you have custom changes to compose files or web assets, how many videobridges you operate, and how much recording data must be moved and checked. Ask for a quote that itemizes these items, the test environment, the backup, the recording migration and the handover. Quotes for DeployOpen work follow from a written scope, and the company does not publish a price list.
What does our team need to provide for the upgrade?
Three things are essential: access to the host, an agreed maintenance window, and a named owner for the .env file and TLS certificates. Access must include the Jibri machine if you record, because it runs separately. The maintenance window should come with a rollback plan that uses the backup and the retained old directories. The .env owner decides authentication settings and optional extensions. The certificate owner must confirm the domain has a valid certificate, since self-signed certificates cause problems for audio and video, especially on mobile clients. Finally, ask the network team to confirm that inbound access for the web and media ports stays in place after the change.
When should we hire a partner for the Jitsi Docker upgrade?
Hire a partner when the change carries risk your team cannot absorb. Typical triggers are custom changes to containers or configuration, recordings with Jibri that must be preserved and verified, scaled bridges across several videobridges, and authentication that connects SSO or JWT tokens to your applications. DeployOpen plans, implements, customizes, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and ongoing support is available as a retainer. Ask for a written scope so you can compare it with your internal plan.
Which file permissions and user settings break after the rootless change?
The main risk is write access. From stable-11146, every service runs as uid and gid 1000 with no effective Linux capabilities and a read-only container filesystem. Only /run and /tmp are writable tmpfs mounts, so every host directory a container writes to must be writable by uid 1000. Check the ownership of the storage and tmp directories after you move files. A wrong owner usually shows up later as a failed write in a container log, during a call or a recording, so test those paths before you declare the upgrade complete. Back up the storage directory first, since it holds persistent state, while the tmp directory holds files that can be regenerated.
How DeployOpen works on this
DeployOpen scopes this upgrade as a written, fixed-scope engagement covering your Docker-based Jitsi from a release older than stable-11146 to the rootless, read-only containers. We inventory which data moves automatically on first start and which data, such as Jibri recordings, logs and transcripts, you must move yourself. Ongoing support and upgrades are available as a retainer.
How we scope
- Inventory of the current Jitsi Docker release, host directories and the .env settings in use.
- Written scope listing which Prosody, web TLS, Jibri and other data paths are included.
- Fixed-scope agreement, with deliverables and timelines agreed in writing before work starts.
How we build
- Set ownership of ${CONFIG}/storage and ${CONFIG}/tmp to uid and gid 1000 before first start.
- Move Jibri recordings, logs and transcripts into the new layout, then verify file access as uid 1000.
- Test read-only container behavior, with /run and /tmp as writable tmpfs mounts, before cutover.
How we hand over
- Runbook mapping each old directory to its new location, with the automatic and manual moves marked.
- Verification checklist covering call setup, recording, authentication and TLS certificate loading.
- Removal guidance for the old directories, which the Docker guide says are left untouched after upgrade.
How we support
- Retainer options for ongoing support and later Jitsi upgrades once the rootless setup is live.
- Review of each subsequent Jitsi release against the storage and tmp layout before you update.
- Support questions about which files moved and where they now live, answered from the runbook.
