> ## Documentation Index
> Fetch the complete documentation index at: https://help.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update or Roll Back the Workspaces Container

> Update a self-hosted Workspaces container and roll back by restoring its pre-update backup.

Update Workspaces by replacing the container image while keeping the same data
volume. Back up first. If you must roll back, restore that backup into a fresh
volume and start the old image. Do not run old code against migrated data.

Version `0.2.0` includes migrations `0027` through `0033`. Once that release
updates a data volume, an older image whose migration set ends before `0033`
will refuse to start on it.

## Before you update

1. Read the release notes and migration impact for the new version.
2. Record the current image version and source commit from `/healthz`.
3. Create and verify a [cold
   backup](/workspaces/self-hosting/container/backup-and-restore).
4. Keep the old image tag and the protected environment file available.

You can skip release versions. Workspaces applies each pending
migration in filename order during boot.

## Update the container

<Steps>
  <Step title="Pull the new image">
    ```bash theme={null}
    docker pull ghcr.io/plannotator/workspaces/workspaces-rooms:0.2.0
    ```
  </Step>

  <Step title="Stop and remove the old container">
    ```bash theme={null}
    docker stop -t 15 rooms
    docker rm rooms
    ```
  </Step>

  <Step title="Start the new image on the same volume">
    ```bash theme={null}
    docker run -d --name rooms \
      --env-file /secure/path/workspaces.env \
      -v ws-data:/data \
      -p 8790:8790 \
      ghcr.io/plannotator/workspaces/workspaces-rooms:0.2.0
    ```
  </Step>

  <Step title="Verify the result">
    ```bash theme={null}
    docker logs rooms
    curl -s http://127.0.0.1:8790/healthz
    ```

    Confirm the new version and source commit. Sign in, open a known document
    and its version history, then make a new edit.
  </Step>
</Steps>

A migration failure stops the process before it serves requests. Read the log
for the migration filename, keep the failed volume unchanged, and restore the
pre-update backup if you cannot correct the cause.

## Roll back

Rolling back restores data from before the update. The restored volume will not
contain writes made after that backup.

<Steps>
  <Step title="Stop the new container">
    ```bash theme={null}
    docker stop -t 15 rooms
    docker rm rooms
    ```
  </Step>

  <Step title="Restore into a fresh volume">
    Follow [Restore a cold
    backup](/workspaces/self-hosting/container/backup-and-restore#restore-a-cold-backup).
    Do not unpack the archive over the migrated volume.
  </Step>

  <Step title="Start the old image">
    Mount the `$RESTORE_VOLUME` created by the restore steps and use the exact
    release tag tied to the backup. This example rolls back to 0.2.0. Keep the
    command in the same shell.

    ```bash theme={null}
    docker run -d --name rooms \
      --env-file /secure/path/workspaces.env \
      -v "$RESTORE_VOLUME":/data \
      -p 8790:8790 \
      ghcr.io/plannotator/workspaces/workspaces-rooms:0.2.0
    ```
  </Step>

  <Step title="Verify the rollback">
    Check `/healthz`, sign in, open known documents and versions, and make a
    new edit. Keep the migrated volume until you have confirmed the restore.
  </Step>
</Steps>

An old image does not start when the volume contains migrations it does not
recognize. This prevents old code from using a newer schema.

*Reviewed July 22, 2026. Maintained by the Plannotator documentation team.*