> ## 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.

# Install the Workspaces Container

> Pull and start the self-hosted Workspaces container with durable storage and production OIDC sign-in.

Run the Workspaces container as one process with one named Docker volume. Use
an HTTPS public origin and complete a real OIDC sign-in before you treat the
instance as ready.

Install the named `0.2.0` release. Do not use `latest`; it can point to a
different release later.

Release `0.2.0` supports `linux/amd64`. An arm64 host can run it through
Docker emulation, but this release has no native arm64 image.

## Prerequisites

You need:

* Docker on a Linux x86-64 host, or an arm64 host with Docker emulation;
* an HTTPS hostname and TLS termination in front of the container;
* an OpenID Connect provider;
* one named Docker volume or writable local block-storage directory; and
* the required settings from [Configure the Workspaces
  container](/workspaces/self-hosting/container/configure).

The container listens on port `8790` and runs as user ID `1000`. Do not use a
shared network filesystem for `/data`.

## Prepare the environment file

Store the production settings in a file readable only by the service account.
Do not commit this file or attach it to a support request.

```dotenv theme={null}
WORKSPACES_ENV=production
AUTH_MODE=oidc
APP_ORIGIN=https://workspaces.example.com
OIDC_ISSUER=https://idp.example.com
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_COOKIE_SECRET=<at-least-32-bytes>
SHARE_LINK_SECRET=<random-secret>
API_KEY_PEPPER=<at-least-32-bytes>
SELF_HOST_ORG_ID=<stable-organization-id>
SELF_HOST_ORG_NAME=<organization-name>
```

Omit `OIDC_CLIENT_SECRET` only when your provider registers Workspaces as a
public client. Register `https://workspaces.example.com/auth/callback` as the
redirect URI. Generate `SHARE_LINK_SECRET` with at least 32 random bytes even
though production boot checks only that it is present.

## Start Workspaces

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

    The image digest is
    `sha256:4cc040539a31954ce888528efbdcff6254dbe3090b12378de9c942ebaa1c6b2c`.
    Plannotator verified this image on July 22, 2026. The checks covered a
    fresh-volume restore, downgrade refusal, production OIDC sign-in, and
    creating, using, listing, and revoking an API key.
  </Step>

  <Step title="Create the data volume">
    ```bash theme={null}
    docker volume create ws-data
    ```
  </Step>

  <Step title="Start the container">
    ```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="Check the process">
    ```bash theme={null}
    docker ps --filter name=rooms
    docker logs rooms
    curl -s http://127.0.0.1:8790/healthz
    ```

    The health request should return `ok: true`, `environment: production`,
    the image version, and its source commit.
  </Step>

  <Step title="Verify sign-in">
    Open the HTTPS app origin, select **Log in**, and finish the OIDC flow. A
    green health response does not prove that OIDC discovery, the callback,
    or browser cookies work.
  </Step>
</Steps>

## Expected result

The browser opens Workspaces, OIDC sign-in returns to the app, and **Settings**
shows the signed-in account. Create a small document, reload it, and confirm
that the content remains available before inviting other users.

## Common failures

| Result                                             | Check                                                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The container exits before opening port `8790`     | Read `docker logs rooms`. The log lists missing settings, secrets that are too short, an unwritable data directory, or another process holding the data lock. |
| `/healthz` is green but **Log in** fails           | Check the HTTPS issuer, callback URI, client registration, and TLS trust. OIDC discovery runs during the first login, not during boot.                        |
| The browser returns to the signed-out page         | Confirm the public origin uses HTTPS. Workspaces marks its sign-in cookies `Secure`.                                                                          |
| A bind mount fails at boot                         | Make the directory writable by user ID `1000`, or use a named Docker volume.                                                                                  |
| A second container cannot start on the same volume | Stop the first process. Workspaces permits one process per data directory.                                                                                    |

[Troubleshoot self-hosted
Workspaces](/workspaces/self-hosting/troubleshoot) covers OIDC, storage, raw
links, updates, and Cloudflare errors.

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