docs: streamline release v2 documentation (#6760)
This commit is contained in:
Thomas authored and 
GitHub committed
1 parent
ac62e5bfd6
commit
b3aa6155cc
163 files changed
+2908
-4208
No files matched your search
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Workshop development
|
||||
sidebar_position: 4
|
||||
tags:
|
||||
- Workshop
|
||||
- Developer
|
||||
- Docusaurus
|
||||
- PocketBase
|
||||
---
|
||||
|
||||
# Workshop development
|
||||
|
||||
Install the repository dependencies and make sure Docker is available before starting the Workshop services. See the
|
||||
[main development guide](../advanced/development/getting-started) for the repository prerequisites.
|
||||
|
||||
## Run PocketBase and documentation
|
||||
|
||||
Start PocketBase in one terminal:
|
||||
|
||||
```sh
|
||||
cp apps/workshop/.env.example apps/workshop/.env
|
||||
docker compose --env-file apps/workshop/.env -f apps/workshop/docker-compose.yml up --build workshop
|
||||
```
|
||||
|
||||
Then start Docusaurus in another 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`.
|
||||
|
||||
Point Homarr at the local services with:
|
||||
|
||||
```dotenv
|
||||
HOMARR_WEBSITE_URL=http://127.0.0.1:3003
|
||||
WORKSHOP_API_URL=http://127.0.0.1:8090
|
||||
```
|
||||
|
||||
Restart `pnpm dev:docs` after changing the Docusaurus URL variables. If Homarr is also running, restart its `pnpm dev`
|
||||
process after changing the Workshop URLs. GitHub OAuth is optional locally. See
|
||||
[`apps/workshop/README.md`](https://github.com/homarr-labs/homarr/blob/HEAD/apps/workshop/README.md) for OAuth,
|
||||
Workshop moderator promotion, logs, tests, backup, restore, stopping, and intentional volume reset.
|
||||
|
||||
## URL testing
|
||||
|
||||
Docusaurus reads `HOMARR_WEBSITE_URL`, `WORKSHOP_API_URL`, and `WORKSHOP_WEB_URL` when it starts or builds. Homarr uses
|
||||
`WORKSHOP_WEB_URL` for public Workshop links while API and documentation origins remain independent. These values do
|
||||
not rely on `NEXT_PUBLIC_*` build variables. Test separate origins before release:
|
||||
|
||||
```sh
|
||||
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 \
|
||||
pnpm dev:docs
|
||||
```
|
||||
|
||||
The [Workshop operator guide](./operator) covers production environment variables, staging, and service validation.
|
||||
@@ -8,46 +8,31 @@ tags:
|
||||
- Community
|
||||
---
|
||||
|
||||
import { OpenCollectiveLink } from "@site/src/components/assistant-provider/open-collective-link";
|
||||
import { HomarrProviderDiagram } from "@site/src/components/pages/core-concepts/technical-diagrams";
|
||||
|
||||
# Homarr provider
|
||||
|
||||
The Homarr provider gives Community Workshop users access to the **Homarr model** without an administrator API key.
|
||||
The Homarr team chooses the upstream model based on quality, reliability, and cost.
|
||||
The Homarr provider gives Community Workshop users access to a server-selected model without configuring an Assistant
|
||||
API key.
|
||||
|
||||
## Set it up
|
||||
Select **Homarr** under **Management → Assistant**, enable Assistant, then sign in to the Workshop when prompted.
|
||||
|
||||
1. Open **Management → Assistant**.
|
||||
2. Select **Homarr** as the provider.
|
||||
3. Save the provider connection.
|
||||
4. Select the available model, enable the assistant, and save.
|
||||
5. Open the assistant and sign in to the Workshop when asked.
|
||||
<HomarrProviderDiagram />
|
||||
|
||||
## Daily allowance
|
||||
## Allowance
|
||||
|
||||
- Each user gets **50 request units per UTC day**.
|
||||
- Each model request uses one unit. A tool loop can use several units.
|
||||
- Forwarded requests count even if the model later fails.
|
||||
- Allowances reset at 00:00 UTC. A shared daily limit also applies.
|
||||
- Each user receives 50 request units per UTC day.
|
||||
- Each model request consumes one unit; a tool loop can consume several.
|
||||
- Forwarded requests count even when the upstream model fails.
|
||||
- A shared daily service limit also applies.
|
||||
|
||||
The battery beside the model selector shows the remaining allowance and reset time. Workshop enforces all limits on
|
||||
its server; changing the browser clock cannot bypass them.
|
||||
Assistant shows the remaining allowance and reset time beside the model control.
|
||||
|
||||
## Privacy
|
||||
## Data handling
|
||||
|
||||
Workshop keeps the OpenRouter API key on its server. Homarr and the browser never receive it.
|
||||
Prompts, attachments, tools, and tool results pass through Workshop and OpenRouter. Workshop does not retain request or
|
||||
response content; it stores the user, UTC day, and counters required for limits. OpenRouter is configured for zero data
|
||||
retention with data collection disabled.
|
||||
|
||||
Prompts, attachments, tools, and tool results pass through Workshop and OpenRouter. Workshop does not retain this
|
||||
content or the responses. It stores only the user, UTC day, and counters needed to enforce allowances. Each active day
|
||||
has a separate quota record so Workshop operators can inspect per-user daily usage without seeing request content.
|
||||
OpenRouter is configured for zero data retention with data collection disabled. Homarr does not use this content to
|
||||
train models.
|
||||
|
||||
We would rather become millionaires in a more ethical manner.
|
||||
|
||||
The community pays for these requests. Donations help cover the cost.
|
||||
|
||||
<OpenCollectiveLink />
|
||||
|
||||
Workshop operators can change the upstream model, per-user allowance, global allowance, and security limits in the
|
||||
[Workshop operator guide](./operator#homarr-provider-proxy).
|
||||
Operators configure the model, limits, and upstream key; see the
|
||||
[Workshop operator guide](/docs/advanced/development/workshop-operator#homarr-provider).
|
||||
@@ -7,45 +7,40 @@ tags:
|
||||
- Custom CSS
|
||||
---
|
||||
|
||||
import { WorkshopFlowDiagram } from "@site/src/components/pages/core-concepts/technical-diagrams";
|
||||
|
||||
# Community Workshop
|
||||
|
||||
The [Community Workshop](pathname:///workshop) is where Homarr users share Custom Widgets and dashboard CSS.
|
||||
The [Community Workshop](pathname:///workshop) hosts community Custom Widgets and dashboard CSS.
|
||||
|
||||
:::warning Experimental
|
||||
|
||||
Workshop content is made by the community. Review it before installation and back up your Homarr instance.
|
||||
Workshop content is community-maintained. Review its source and permissions before installation.
|
||||
|
||||
:::
|
||||
|
||||
## Find and install content
|
||||
## Content flow
|
||||
|
||||
Browse the Workshop by type, date, popularity, or recent activity. Each submission includes its source, screenshots,
|
||||
author, revision, comments, and reports.
|
||||
<WorkshopFlowDiagram />
|
||||
|
||||
Administrators can install content without leaving Homarr:
|
||||
Workshop also exposes the [Homarr Assistant provider](./homarr-provider). Its model-routing and quota path is separate
|
||||
from Custom Widget and CSS submissions.
|
||||
|
||||
- **Custom Widgets:** open **Management → Custom Widgets**, then select **Import from Workshop**.
|
||||
- **Custom CSS:** open a board's **Settings → Custom CSS**, then select **Import from Workshop**.
|
||||
## Install content
|
||||
|
||||
Homarr shows the complete source and required permissions before installation. Widget credentials are entered in your
|
||||
Homarr instance and are never included in a Workshop submission.
|
||||
- Install a Custom Widget from **Management → Custom Widgets → Import from Workshop**.
|
||||
- Import dashboard CSS from **Board settings → Custom CSS → Import from Workshop**.
|
||||
|
||||
## Share your work
|
||||
Custom Widget credentials are configured in your Homarr instance and are not part of the Workshop submission.
|
||||
|
||||
For a saved Custom Widget, open **Management → Custom Widgets**, use its action menu, and select **Publish to
|
||||
Workshop**. Review the public listing details and source URLs, then publish the credential-free export. Custom CSS and
|
||||
manual submissions can be shared directly from the Workshop website with **Share yours**.
|
||||
## Publish content
|
||||
|
||||
Publishing creates the listing immediately. To update or delete it, review reports, or mark it outdated, open the
|
||||
Workshop website, sign in, and select **Yours**. Editing a submission does not change its Workshop URL.
|
||||
Publish a saved Custom Widget from its action menu under **Management → Custom Widgets**. Custom CSS and manual
|
||||
submissions can be published from the Workshop website.
|
||||
|
||||
## Voting, comments, and reports
|
||||
Sign in to the Workshop and open **Yours** to update or delete submissions and review reports. Signed-in users can vote,
|
||||
comment, and report content; Workshop moderators can remove content. Workshop moderation is separate from administration
|
||||
of a Homarr instance.
|
||||
|
||||
Signed-in users can vote, comment, and report submissions. Authors can edit their own comments and submissions.
|
||||
Workshop moderators can review reports, remove comments, and delete unsafe content. Reports do not remove a submission
|
||||
automatically.
|
||||
|
||||
A Workshop moderator manages the public community. This is separate from the administrator role on a Homarr instance.
|
||||
|
||||
Deployment and server configuration are in the [Workshop operator guide](./operator). Local setup is in
|
||||
[Workshop development](./development).
|
||||
See the [Workshop operator guide](/docs/advanced/development/workshop-operator) to host Workshop or
|
||||
[Workshop development](/docs/advanced/development/workshop) to run it from the repository.
|
||||
@@ -1,160 +0,0 @@
|
||||
---
|
||||
title: Workshop operator guide
|
||||
sidebar_label: Operator guide
|
||||
sidebar_position: 3
|
||||
tags:
|
||||
- Workshop
|
||||
- Deployment
|
||||
- Environment variables
|
||||
- PocketBase
|
||||
---
|
||||
|
||||
# Workshop operator guide
|
||||
|
||||
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.
|
||||
|
||||
Submission links include Open Graph and X/Twitter metadata for the submission title, description, and type. The first
|
||||
uploaded screenshot is used as the social preview image; submissions without screenshots use the Homarr logo.
|
||||
|
||||
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. See [Workshop development](./development) for the complete local setup.
|
||||
|
||||
## Authentication and notifications
|
||||
|
||||
GitHub needs only the central callback `https://<workshop-host>/api/oauth2-redirect`. Keep PocketBase origins
|
||||
unrestricted unless every self-hosted Homarr caller is explicitly listed. Configure both `GITHUB_CLIENT_ID` and
|
||||
`GITHUB_CLIENT_SECRET`; supplying only one is a startup error. Set `WORKSHOP_PUBLIC_ORIGIN` in production so generated
|
||||
links and email use the public host. Workshop stores only the OAuth provider username in `users.name`, and users cannot
|
||||
rename it. Map **OAuth2 username** to `name`; leave OAuth2 id, full name, and avatar mappings empty. Profile and avatar
|
||||
URLs are derived from `https://github.com/<username>` and `https://github.com/<username>.png`, so PocketBase does not
|
||||
store duplicate profile metadata or avatar files. Configure SMTP for comment, report, and removal notices.
|
||||
|
||||
## Environment variables
|
||||
|
||||
The public URL contract and Workshop-only server configuration are:
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
| -------------------------------------- | --------------------------------------------- | ------------------------------ |
|
||||
| `HOMARR_WEBSITE_URL` | Documentation/site base used by Homarr links | `https://homarr.dev` |
|
||||
| `WORKSHOP_API_URL` | PocketBase API used by Homarr and docs | `HOMARR_WEBSITE_URL` |
|
||||
| `WORKSHOP_WEB_URL` | Public Workshop links in Homarr | `HOMARR_WEBSITE_URL/workshop` |
|
||||
| `WORKSHOP_PUBLIC_ORIGIN` | PocketBase-generated links and email | Required in production |
|
||||
| `PB_ALLOWED_ORIGINS` | PocketBase browser origins | `*` for the central community |
|
||||
| `OPENROUTER_API_KEY` | Server-only key for the Homarr provider proxy | Provider disabled when empty |
|
||||
| `HOMARR_AI_DAILY_REQUEST_LIMIT` | Per-user daily provider allowance | `50` |
|
||||
| `HOMARR_AI_GLOBAL_DAILY_REQUEST_LIMIT` | Shared daily ceiling across all users | `10000` |
|
||||
| `HOMARR_AI_OPENROUTER_BASE_URL` | OpenRouter-compatible proxy upstream | `https://openrouter.ai/api/v1` |
|
||||
| `HOMARR_AI_OPENROUTER_MODEL` | Server-selected upstream model | Selected by the Homarr team |
|
||||
|
||||
All public URL variables reject non-HTTP protocols, embedded credentials, query strings, and fragments, and normalize
|
||||
trailing slashes when Homarr or Docusaurus starts. The deprecated docs-only `WORKSHOP_URL` alias remains for one
|
||||
release; `WORKSHOP_API_URL` takes precedence for API calls and `WORKSHOP_WEB_URL` takes precedence for public Workshop
|
||||
links. The combined Workshop image writes the public URLs into its browser
|
||||
runtime configuration whenever the container starts; the Docker build arguments remain fallbacks. Restart the
|
||||
container after changing these values, without rebuilding it.
|
||||
|
||||
### Homarr provider proxy
|
||||
|
||||
The [Homarr provider](./homarr-provider) proxy is part of the Workshop image. `OPENROUTER_API_KEY` enables the proxy,
|
||||
`HOMARR_AI_OPENROUTER_BASE_URL` selects its OpenRouter-compatible upstream, `HOMARR_AI_OPENROUTER_MODEL` selects the
|
||||
private upstream model behind the stable `homarr/model` alias, and the two allowance variables provide per-user and
|
||||
shared request ceilings. Lowering either allowance takes effect for existing users. The upstream URL cannot contain
|
||||
embedded credentials, a query, or a fragment and must use HTTPS. Tests can explicitly opt into an insecure local mock
|
||||
with `HOMARR_AI_ALLOW_INSECURE_UPSTREAM=true`; do not use that setting with a real API key.
|
||||
|
||||
The proxy overwrites client routing and generation limits. It requires OpenRouter zero-data-retention routing, denies
|
||||
data-collecting providers, limits responses to 32,768 completion tokens, and does not retain prompts, responses, or
|
||||
per-request telemetry. It accepts only uploaded image data, conservatively bounds text to the advertised context, and
|
||||
allows at most two concurrent requests per user and 100 across the service. Keep an OpenRouter account-level credit
|
||||
limit as the final monetary backstop because request quotas are not dollar accounting.
|
||||
|
||||
PocketBase stores one `assistant_quotas` record per user and active UTC day. Workshop superusers can use this private
|
||||
collection for a daily usage breakdown; regular users cannot list or view its records.
|
||||
|
||||
Run `pnpm test:workshop` to test authentication, streaming, UTC reset, atomic per-user and global quota enforcement,
|
||||
failed-request accounting, identity attribution, server-selected model routing, function tools, input and output
|
||||
controls, privacy routing, spoofing resistance, absence of request logs, and migration rollback.
|
||||
|
||||
An operator can explicitly smoke-test a deployed Workshop against its real configured upstream with a dedicated,
|
||||
low-quota test user:
|
||||
|
||||
```sh
|
||||
HOMARR_AI_LIVE_SMOKE=1 \
|
||||
WORKSHOP_LIVE_TEST_URL=https://workshop.example.com \
|
||||
WORKSHOP_LIVE_TEST_TOKEN=<temporary-pocketbase-user-token> \
|
||||
pnpm test:workshop-live-provider
|
||||
```
|
||||
|
||||
This optional check consumes one provider request. The test client needs neither the OpenRouter key nor the private
|
||||
upstream model ID. Do not run it in CI or with a normal user's Workshop token.
|
||||
|
||||
## Staging and demo deployment
|
||||
|
||||
Use `apps/workshop/docker-compose.staging.yml` with the published `ghcr.io/homarr-labs/workshop:v2` image for a v2
|
||||
preview. Copy `apps/workshop/.env.staging.example` to `.env.staging`; its default public contract is:
|
||||
|
||||
```dotenv
|
||||
HOMARR_WEBSITE_URL=https://v2.preview.homarr.dev
|
||||
WORKSHOP_API_URL=https://v2.preview.homarr.dev
|
||||
WORKSHOP_PUBLIC_ORIGIN=https://v2.preview.homarr.dev
|
||||
PB_ALLOWED_ORIGINS=*
|
||||
```
|
||||
|
||||
Start or update it from the repository root:
|
||||
|
||||
```sh
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml pull
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml up --detach
|
||||
curl --fail http://127.0.0.1:8090/api/health
|
||||
```
|
||||
|
||||
The service binds to `127.0.0.1:8090`. Terminate TLS at a reverse proxy and forward the **entire hostname**, including
|
||||
`/api`, `/_/`, and `/workshop-runtime-config.js`; forwarding only `/workshop` breaks PocketBase and runtime URL loading.
|
||||
This combined image serves both the documentation site and PocketBase, so use a dedicated Workshop hostname if the
|
||||
chosen hostname already serves Homarr itself. In that case, replace the hostname in all three URL values. Homarr
|
||||
derives the public Workshop page by appending `/workshop` to `HOMARR_WEBSITE_URL`.
|
||||
|
||||
The Compose volume preserves PocketBase data across pulls and container recreation. The mutable `v2` tag is suitable
|
||||
for previews; use the `sha-<commit>` tag for promotion. For the public central Workshop, `PB_ALLOWED_ORIGINS=*` allows
|
||||
self-hosted Homarr origins to use the API and OAuth. A private demo may use a comma-separated origin allowlist instead.
|
||||
GitHub OAuth requires both credentials and the callback `https://v2.preview.homarr.dev/api/oauth2-redirect`. Restart
|
||||
after changing environment values, then verify the health endpoint, `/workshop`, a public listing request, GitHub
|
||||
sign-in, and an installation from the Homarr preview.
|
||||
|
||||
## Backup and restore
|
||||
|
||||
PocketBase data lives in `/pb_data`. Stop writes and copy it to a new, empty backup directory:
|
||||
|
||||
```sh
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml stop workshop
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml cp workshop:/pb_data/. ./workshop-backup
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml start workshop
|
||||
```
|
||||
|
||||
Restore only after preserving the current volume and confirming the backup contains `data.db`:
|
||||
|
||||
```sh
|
||||
test -f ./workshop-backup/data.db
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml stop workshop
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml run --rm --no-deps --entrypoint sh workshop \
|
||||
-c 'find /pb_data -mindepth 1 -maxdepth 1 -exec rm -rf {} +'
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml cp ./workshop-backup/. workshop:/pb_data
|
||||
docker compose --env-file apps/workshop/.env.staging \
|
||||
-f apps/workshop/docker-compose.staging.yml start workshop
|
||||
curl --fail http://127.0.0.1:8090/api/health
|
||||
```
|
||||
|
||||
The restore empties the selected volume. Rehearse it in staging, then verify sign-in and one installation. Publish by
|
||||
immutable digest, validate that exact digest in staging, and promote the same digest.
|
||||
Reference in new issue
Block a user