Install the Workspaces Container

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.

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.

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

Pull the release image

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.

Create the data volume

docker volume create ws-data

Start the container

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

Check the process

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.

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.

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 covers OIDC, storage, raw links, updates, and Cloudflare errors. Reviewed July 22, 2026. Maintained by the Plannotator documentation team.

Start

Accounts and organizations

Sharing and access

Documents and collaboration

Agents and developer access

Plans, billing, and seats

Self-hosting and updates

Security and privacy

Troubleshooting

Prerequisites

Prepare the environment file

Start Workspaces

Expected result

Common failures

​Prerequisites

​Prepare the environment file

​Start Workspaces

​Expected result

​Common failures

Prerequisites

Prepare the environment file

Start Workspaces

Expected result

Common failures