Thomas
229bd4b3ed
* feat: migrate tooling and runtimes to bun * fix: serialize act installs and adapt backup checks * fix: finish bun scripts and rootless act setup * fix: support bun images in runtime benchmarks * fix: keep a single bun toolchain configuration * fix: include docs mascot sources in workshop build * docs: use bun in remaining tool commands * fix: complete bun sqlite development tooling * docs: explain sqlite development adapter * fix: align remaining commands and local ci validation * fix: use renovate regex fallback with bun * fix: finalize bun sqlite connections during cleanup * fix: preserve sqlite foreign key enforcement * fix: align docker build frontends * fix: prepare release versions with bun * Add Bun benchmarks and preserve SQLite connection defaults * Benchmark Bun installs, conflicts and production workloads * Force Bun workspace tools and HTTP/1.1 upstream streaming * Exclude benchmark evidence from Docker contexts * Expose branch benchmarks through CI * Verify hydrated widget data in production benchmarks * Measure image archives and document benchmark protocol * Audit dependency sharing across every workspace * Pin pnpm for nested baseline benchmark scripts * Preserve nested manager pinning on benchmark resume * Include application and runtime image footprints * Fail benchmark gates on candidate command errors * Report complete build overhead and sampled memory bounds * Validate migration comparisons across pinned revisions * Record configurable runtime memory budgets * Retain out-of-memory kills in runtime budget probes * Reject OOM events consistently across runtime metrics * Record complete Bun migration benchmarks * Record memory diagnosis and correct Turbo caching * Use Bun package management while preserving Node runtimes * Keep native build fallbacks and exclude development artifacts * Fix Node ESM metadata and isolate local CI configuration * Measure development performance and isolate act environment * Support isolated environment files in rootless act * Validate the full migration range with act * Preserve native SQLite binding for bundled migrations * Use documented dev defaults and report benchmark scope * Validate dev defaults and isolate restart measurements * Record package-manager and development benchmarks * Keep benchmark measurements and link full command artifacts * Clean up temporary act environment files * Validate Node runtimes in package-manager comparisons * Validate every workspace in manual CI runs * Retain patched nested brace expansion versions * Complete package-manager and Node performance report * Normalize archived benchmark logs * Record final hosted validation * Cache both Next builds with platform isolation * Prime cache with write-only mode * Split Next artifacts below Cloudflare upload limit * Assemble coherent standalone cache outputs * Preserve traced middleware entrypoints * Assemble traced directory links before files * Separate cached dependencies from assembled output * Record signed Turbo cache benchmarks * Remove archived benchmark captures Full benchmark evidence is preserved at 8f7d3bcd14109bfb13fa664d31710b88d820ad66. * Remove migration benchmark harness * fix: correct migration launch and local Act prerequisites * Consolidate Turbo caches and production artifacts * Exclude generated files from Docker cache inputs * fix: address Bun migration review findings * fix: check restored compiler bundle manifests
107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
docker compose -f apps/workshop/docker-compose.yml exec workshop \
|
|
pocketbase superuser create you@example.com 'replace-with-a-strong-password' --dir=/pb_data
|
|
```
|
|
|
|
Useful service commands:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```text
|
|
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.
|
|
|
|
## Validate changes
|
|
|
|
Run the focused Workshop checks:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](../docs/docs/advanced/development/workshop-operator.mdx) for environment variables, proxying, staging, backups,
|
|
and promotion. Publish by immutable digest, validate that exact digest in staging, then promote it.
|