refactor: trim v2 hardening scaffolding
This commit is contained in:
1 parent
ecfb9d59e0
commit
2eb0baf17e
75 files changed
+334
-2067
No files matched your search
+2
-2
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user