refactor: trim v2 hardening scaffolding

This commit is contained in:
ajnart committed 2026-07-30 15:19:17 +02:00
1 parent ecfb9d59e0
commit 2eb0baf17e
75 files changed
+334 -2067

No files matched your search

+2 -2
View File
@@ -22,8 +22,8 @@ pnpm dev:docs
# Or from within this directory
pnpm dev
# PocketBase on 8090 plus docs on 3003
pnpm dev:workshop
# Point the docs at a local PocketBase instance
WORKSHOP_API_URL=http://127.0.0.1:8090 pnpm dev:docs
```
The standalone docs use `WORKSHOP_API_URL` for PocketBase, `HOMARR_WEBSITE_URL` for the public site origin, and
@@ -55,14 +55,20 @@ Homarr becomes the instance administrator.
### Run PocketBase and documentation
Use the integrated local Workshop command in a second terminal:
Start PocketBase in another terminal:
```sh
pnpm dev:workshop
cp apps/workshop/.env.example apps/workshop/.env
docker compose --env-file apps/workshop/.env -f apps/workshop/docker-compose.yml up --build workshop
```
It starts persistent PocketBase on port 8090, waits for health and the required collections, then starts Docusaurus on
port 3003. It also propagates shutdown without deleting the PocketBase volume.
Then start Docusaurus in a third terminal:
```sh
WORKSHOP_API_URL=http://127.0.0.1:8090 pnpm dev:docs
```
PocketBase runs on port 8090 and Docusaurus on port 3003. Stopping the services preserves the PocketBase volume.
Open `http://127.0.0.1:8090/_/` and create the first PocketBase superuser. The Workshop UI is available at
`http://127.0.0.1:3003/workshop`.
@@ -97,7 +103,7 @@ pnpm dev:docs
- `pnpm dev` — Next.js on port 3000.
- `pnpm dev:docs` — Docusaurus only on port 3003.
- `pnpm dev:workshop` — persistent PocketBase plus Docusaurus.
- `pnpm docker:workshop` — local PocketBase through Docker Compose.
- `pnpm cli` — Homarr operations CLI.
- `pnpm db:migration:sqlite:run` — create or update a SQLite database.
- `pnpm db:studio` — inspect the database.
@@ -35,8 +35,6 @@ Using the `PUID` and `PGID` will require you to set the correct permissions on t
| `HOMARR_WEBSITE_URL` | Main Homarr documentation/site base used by runtime links. Must be an absolute HTTP(S) URL. | HTTP(S) URL | `https://homarr.dev` |
| `WORKSHOP_API_URL` | PocketBase API used by Homarr and standalone documentation. | HTTP(S) URL | `HOMARR_WEBSITE_URL` |
| `WORKSHOP_WEB_URL` | Public Workshop page opened from Homarr. | HTTP(S) URL | `HOMARR_WEBSITE_URL/workshop` |
| `CUSTOM_WIDGETS_ENABLED` | Emergency switch. `false` preserves definitions and placements but blocks Custom Widget authoring and execution. | `true` or `false` | `true` |
| `WORKSHOP_ENABLED` | Emergency switch. `false` hides and blocks Workshop operations without disabling installed widgets. | `true` or `false` | `true` |
## Authentication
@@ -101,22 +101,4 @@ per-scenario limit with `OPENROUTER_GENERATOR_MODEL`, `OPENROUTER_JUDGE_MODEL`,
`CUSTOM_WIDGET_AI_MAX_LOOPS`. Generated artifacts are local and ignored by Git; promote a reviewed, validated result
into the bundled-widget source deliberately.
To exercise the connected MCP workflow with the Vercel AI SDK agent, start Homarr and create an API key for an administrator:
```sh
OPENROUTER_API_KEY=... \
HOMARR_MCP_URL=http://localhost:3000/api/mcp/mcp \
HOMARR_MCP_API_KEY=... \
pnpm --filter @homarr/custom-widgets evaluate:mcp -- --case=pokedex
```
This evaluator uses DeepSeek V4 Pro with `ToolLoopAgent` and a strict structured result. It requires successful schema
and validation results, one successful preview call for every scenario query and action, and a journal read after those
calls. It can repair and retest a widget, but it does not persist by default. Add `--persist` to create a passing widget,
or `--definition=<id> --persist` to test the edit/debug/update path. Authenticated sources use
`customWidget_configurationRequestUser`; credential-writing tools are not exposed to the model and plaintext credentials
never enter its context. A passing result is rejected until that request reports `completed` and the required preview
queries and simulated actions succeed afterward. The deterministic unit suite separately proves the repair, persistence,
and secure source-configuration loop without contacting a model or changing a Homarr instance.
The reference API check uses a real PokeAPI list/detail request and a read-only Portainer container query when `PORTAINER_BASE_URL` and `PORTAINER_API_KEY` are set. Use `pnpm --filter @homarr/custom-widgets test:reference-apis -- --pokeapi-only` for the public PokeAPI check alone. To exercise start, restart, and stop against a disposable container, also set `PORTAINER_TEST_CONTAINER_ID` and the explicit safeguard `PORTAINER_ALLOW_MUTATIONS=1`; the script restores the container's original running state.
@@ -117,10 +117,9 @@ URL also requires the same authenticated administrator; the URL is short-lived,
Custom Widget response caches and action invalidation use shared Redis state, so multiple Homarr replicas see the same
versioned cache generation. Deployments must point every replica at the same Redis service.
Set `CUSTOM_WIDGETS_ENABLED=false` to stop authoring and runtime execution while preserving definitions, secrets, board
placements, and v1 backups. Re-enable it after correcting the incident. Before upgrading, back up the database and
`SECRET_ENCRYPTION_KEY`; a v1 binary can still read preserved v1 tables during application rollback. Widgets created
only in v2 may be unavailable to the rolled-back binary, but do not replace the v1 backup.
Before upgrading, back up the database and `SECRET_ENCRYPTION_KEY`; a v1 binary can still read preserved v1 tables
during application rollback. Widgets created only in v2 may be unavailable to the rolled-back binary, but do not
replace the v1 backup.
## Bundled examples
@@ -43,14 +43,10 @@ An invalid definition disables widget preview and Save/Create. The Data, Options
The Diagnostics tab shows the current schema errors.
## Feature unavailable
## Workshop unavailable
If every Custom Widget reports that the feature is unavailable, check `CUSTOM_WIDGETS_ENABLED`. Setting it to `false`
is an emergency stop that preserves definitions, secrets, legacy backups, and board placements while blocking authoring
and execution.
If Workshop alone is unavailable, check `WORKSHOP_ENABLED` and `WORKSHOP_API_URL`. Disabling Workshop does not disable
widgets that are already installed.
If Workshop is unavailable, check `WORKSHOP_API_URL` and PocketBase health. Widgets that are already installed continue
to work.
## Correct request errors
+4 -4
View File
@@ -87,8 +87,9 @@ Custom Widget imports detect required bearer, basic, header, or query credential
Workshop is powered by [PocketBase](https://pocketbase.io). The production image compiles the current Docusaurus site and serves it together with the API from one origin. The deployment lives in `apps/workshop/` with a Dockerfile, Compose configuration, version-controlled migrations, hooks, a smoke test, and ACT-local workflow instructions.
Run `pnpm dev:workshop` for the recommended local stack: persistent PocketBase on port 8090 and Docusaurus on port 3003. The command waits for health and collections and preserves the `pb_data` volume on shutdown. `pnpm docker:docs`
builds the combined production layout. Normal start and stop commands retain data; `down --volumes` is an intentional,
Run `pnpm docker:workshop` for PocketBase on port 8090, then run
`WORKSHOP_API_URL=http://127.0.0.1:8090 pnpm dev:docs` for Docusaurus on port 3003. `pnpm docker:docs` builds the
combined production layout. Normal start and stop commands retain data; `down --volumes` is an intentional,
irreversible development reset.
GitHub needs only the central callback `https://<workshop-host>/api/oauth2-redirect`. Keep PocketBase origins unrestricted
@@ -112,8 +113,7 @@ server-renders runtime values for the browser, and the combined image writes a p
startup. Restart services after changes.
Back up application and PocketBase data before deployment. Publish the combined image by immutable digest, test the
exact digest in staging, rehearse application rollback and PocketBase restore, then promote that same digest. The
`WORKSHOP_ENABLED=false` switch disables Homarr's Workshop entry points without affecting installed widgets.
exact digest in staging, rehearse application rollback and PocketBase restore, then promote that same digest.
## Client architecture