Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

4.7 KB
Raw Blame

Homarr Workshop

Workshop is the PocketBase service behind the community pages in Homarr's documentation site. It stores Custom JSX v2 widgets and Custom CSS submissions. Homarr validates community content again before installation.

The PocketBase version and multi-platform image digest are pinned in apps/workshop/Dockerfile; update and validate them together.

Run locally

From the repository root:

cp apps/workshop/.env.example apps/workshop/.env
bun install --frozen-lockfile
docker compose --env-file apps/workshop/.env -f apps/workshop/docker-compose.yml up --build workshop

Start the documentation site in another terminal:

WORKSHOP_API_URL=http://127.0.0.1:8090 bun run dev:docs

Open PocketBase administration at http://127.0.0.1:8090/_/ and Workshop at http://127.0.0.1:3003/workshop. Create the first PocketBase superuser in the administration UI or run:

docker compose -f apps/workshop/docker-compose.yml exec workshop \
  pocketbase superuser create [email protected] 'replace-with-a-strong-password' --dir=/pb_data

Useful service commands:

docker compose -f apps/workshop/docker-compose.yml logs -f workshop
docker compose -f apps/workshop/docker-compose.yml stop workshop

Connect Homarr

Use the same URL contract in the repository-root .env, then restart Homarr:

HOMARR_WEBSITE_URL=http://127.0.0.1:3003
WORKSHOP_API_URL=http://127.0.0.1:8090
WORKSHOP_WEB_URL=http://127.0.0.1:3003/workshop
WORKSHOP_PUBLIC_ORIGIN=http://127.0.0.1:3003
PB_ALLOWED_ORIGINS=*

WORKSHOP_API_URL controls API calls, WORKSHOP_WEB_URL controls links from Homarr, and HOMARR_WEBSITE_URL is the documentation-site base. All three must be absolute HTTP(S) URLs.

OAuth and moderators

For optional GitHub OAuth, set both GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. The callback is:

https://<workshop-host>/api/oauth2-redirect

After a user signs in, a PocketBase superuser can promote them by setting users.isAdmin to true. This grants Workshop moderation only; it does not grant Homarr administrator access. The user must sign in again after the change.

The public community uses PB_ALLOWED_ORIGINS=* because self-hosted Homarr instances can run on any origin. Private deployments can use an explicit comma-separated allowlist.

Submission edits

Every submission update must explicitly send expectedRevision equal to the last-read revision, including moderator and PocketBase superuser edits. In the PocketBase dashboard, replace expectedRevision with the record's current revision before saving; do not change revision itself. Workshop increments it on success. The stored expectedRevision describes the previous write, not the revision to use for the next edit.

A stale update returns HTTP 409 with data.expectedRevision.code = "revision_conflict". Reload the submission and reconcile changes before retrying. Missing or invalid expectations return HTTP 400. Homarr already fetches the current revision before submitting updates; superusers do not bypass the revision check.

Validate changes

Run the focused Workshop checks:

bun run test:workshop
bun run --filter @homarr/workshop typecheck
bun run --filter @homarr/docs typecheck

The integration suite uses a disposable Compose project. bun run test:workshop-image additionally builds and smoke-tests the combined production image. The production image smoke also runs in PR CI on native amd64 and arm64 runners, including data persistence and backup restore. The broader integration suite remains available manually. Workshop CI validates Compose configuration and publishes images only on release branches. The main Fast gate owns workspace typechecking.

To smoke-test an already built candidate without rebuilding:

WORKSHOP_IMAGE_TEST_IMAGE=homarr-workshop:candidate bun run test:workshop-image

Data safety

PocketBase data lives in /pb_data. Normal start, stop, and down operations retain the named volume. Back up the database before migrations or image promotion, and test restores in a separate empty volume.

The v2 branch consolidates the unreleased Workshop migrations. Volumes that ran an earlier v2 migration chain are unsupported and must be backed up and recreated. The following command permanently removes the local Workshop volume:

docker compose -f apps/workshop/docker-compose.yml down --volumes

Never run that reset against production.

Production

The production image serves the documentation site and PocketBase from one origin. See the Workshop operator guide for environment variables, proxying, staging, backups, and promotion. Publish by immutable digest, validate that exact digest in staging, then promote it.