Take control over your live stream video by running it yourself. Streaming + chat out of the box.
HTML activitypubbroadcastingchatdecentralizedfederationfediversegolanghacktoberfesthlslivelivestreamowncastrtmpself-hostedstreaming-videovideo
chore(docs): update docs
Gabe Kangasa22db7b5e975
diff --git a/.github/PULL_REQUEST_TEMPLATE.MD b/.github/PULL_REQUEST_TEMPLATE.MDindex 28dad58f8c..a7e53396af 100644--- a/.github/PULL_REQUEST_TEMPLATE.MD+++ b/.github/PULL_REQUEST_TEMPLATE.MD@@ -50,6 +50,6 @@ Some things you might want to mention:2. Explain how it works and decisions you made.3. If you're fixing something, what was wrong? How should we stop from having this issue happen again?4. If this is a new feature or addition to functionality, why should it be added? What are the use cases? Who was asking for this functionality?-5. If this is a frontend change, does the text support [translation](https://owncast.notion.site/web-translations)?+5. If this is a frontend change, does the text support [translation](https://docs.owncast.dev/web-translations)?Thank you so much for contributing to Owncast! 🎉diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex fbe3fc3272..3970e4fba8 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -1,73 +1,5 @@-This is a repository consisting of a Go backend and a React frontend. It supports both an internal web application that is public facing, an internal admin web application, internal-only APIs for powering these web interfaces, and a set of APIs for third parties to take advantage of.+# Owncast-## Code Standards+Agent instructions for this repository live in `AGENTS.md` at the repo root. There are no Copilot-specific rules.-- UI component standards can be found in https://docs.owncast.dev/develop-frontend-components--### Required Before Each Commit--- Ensure all code is formatted using `golangci-lint` for Go, `stylelint` for CSS, and `prettier` for JavaScript/React.-- Fix any formatting or linting errors.--### Development Flow--- Build: Ensure the code builds successfully using `go build` for Go and `npm run build` for React in the `web` directory.-- Tests: Write unit tests for Go code and Javascript logic. Use `go test` and `npm run test`.-- UI components: Components should be standalone and reusable and show up in Storybook to enable testing, prototyping, and iteration.-- API: All APIs should be documented using OpenAPI specifications. Use `build/gen-api.sh` to generate the stubs, and then fill them in with your actual API implementation.-- If you made new UI components or made changes ensure that Storybook still builds by running `npm run build-storybook`.--## Repository Structure--- `web`: The web source code for the React frontend.-- Root of the repo: Go source code for the backend.-- `static/web`: Generated static files for the web application. Do not edit or commit files in this directory directly; they are generated from the `web` directory. Ignore this.-- `test/automated/api`: A series of automated integration tests for API endpoints written in Javascript.-- `test/automated/browser`: A series of automated browser UI tests for actual real-world browser interaction.-- `build/web`: Script to build and bundle the web application.--## Testing web frontend--Testing the web frontend requires running the frontend development server and the backend service together. The frontend development server must be started using `npm run dev` in the `web` directory, which will serve the web application at `http://localhost:3000`. The backend service can be started using `go run main.go` in the root of the repository.--Do not access the web application via http://localhost:8080 or build the web project to copy files to the `static/web` directory for local development.--## Code Reviews--- When performing a code review for a UI component take a screenshot and attach it to your comments to make the review more detailed.-- When performing a code review for an API provide the payload for the API and attach it to the code review comment.-- When performing a code review check for all linters and formatters for in code and put in the code review comment a suggestion on how to fix each line.--## Key Guidelines--1. All APIs are to be documented using OpenAPI specifications and code is to be generated using `build/gen-api.sh`. Additional details can be found at https://docs.owncast.dev/api-web-routing.-2. Write API tests for all new endpoints in the `test/automated/api` directory.-3. Use the `test/automated/browser` directory for browser-based tests for new functionality that simulate user interactions.-4. All user-facing frontend UI strings need to support localization. Use the `Translation` component to show most displayable strings. To create dynamic translated strings use the `next-export-i18n` library and the `t()` function. But use the `Translation` component unless there is a reason not to as it allows you to set default text. Read https://docs.owncast.dev/web-translations for more details. Test localization by adding "?lang=XX" with XX being a country code, such as "de" for German. Strings that have not yet been translated will not show as changed, but it's good to test anyway to make sure that previously translated strings have not been broken or regressed in any way. Screenshots with some additional languages can be helpful in showing this.-5. For UI component changes, a before and after screenshot of the component should always be added to the pull request to help with review. Additionally a link to the PR's Storybook on Chromatic via the PR's Chromatic job should be included to help with review.-6. For API changes a before and after example of the API response should be added to the pull request to help with review.-7. For backend changes, a before and after example of logs to demonstrate the change should be added to the pull request to help with review.-8. Do not build the web project or copy the files to the `static/web` directory for local development.-9. When running the frontend development server, the local backend service must also be running. You can run the backend service using `go run main.go` in the root of the repository.-10. The credentials for the backend development backend are username: admin and password: abc123 and uses HTTP Basic Auth. This is used for the admin web application and the admin APIs.-11. The admin is found at `/admin`.-12. If a live stream video is needed to run, you can run `./test/ocTestStream.sh` to start an actual stream that will begin streaming from the local development server.-13. You should never commit the `static/web` directory to the repository. It is generated from the `web` directory and should be ignored in your commits.-14. Don't use emoji in code comments or commit messages. That's lame.--## Screenshots--Take a screenshot after every UI change without being asked. Screenshots should be automatically taken after every code change that affects UI.-After every UI change we should be able to see in the PR comments, visually, exactly what the change is. This helps with code review and ensures that the UI changes are clear and understandable. This should happen every time, automatically, without being asked, and never fail or be skipped.--These screenshots should be displayed inline in the PR comments, and not as attachments. This allows reviewers to see the changes without having to download or open files separately.--- If it is a standalone UI component, take a screenshot of the component in Storybook if it is available.-- When taking a screenshot of a component in Storybook, make sure to hide all the controls that are not relevant to the component itself. This means hiding the knobs, actions, and any other controls that are not part of the component's visual representation and would get in the way of the screenshot.-- If it is something that doesn't exist in Storybook, take a screenshot of the component in the live web application using the local development server.-- Most things in the admin do not exist in Storybook, so screenshots should be taken of the admin web application.-- When taking a screenshot of the web frontend or the admin web application, an instance of the Owncast backend service needs to be running locally by running `go run main.go` in the root of the repository as well.-- When taking screenshots for PR documentation, create temporary files in /tmp directory or use patterns like _screenshot_.js and _screenshot_.png that are excluded by .gitignore.-- Screnshots should be taken using the web dev server at `http://localhost:3000` and not the production build at `http://localhost:8080`.-- Never commit temporary screenshot scripts or image files to the repository - they should only be used locally and uploaded directly to GitHub for PR comments.-- Double check that the screenshots are attached to the PR comments. Copilot often forgets to do this or says it did it but doesn't actually do it. If it doesn't do it, it should continue to try until it succeeds.+Read `AGENTS.md` before making changes and follow it, including the commit, linting, code generation, localization, and pull request expectations described there.diff --git a/AGENTS.md b/AGENTS.mdindex 8a38dd2234..207568e9c1 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,8 @@# Owncast AI Agent Instructions-This is a repository consisting of a Go backend and a React frontend. It supports both an internal web application that is public facing, an internal admin web application, internal-only APIs for powering these web interfaces, and a set of APIs for third parties to take advantage of.+This is the single source of truth for agent instructions in this repository. `CLAUDE.md` and `.github/copilot-instructions.md` point here.++Owncast is a self-hosted live streaming server: a Go backend plus a React/Next.js frontend. One frontend project builds two apps, the public viewer page and the admin at `/admin`, and the Go binary serves both. The backend exposes internal APIs for those apps plus a documented public API that third-party clients depend on.## Quick Reference@@ -15,6 +17,7 @@ This is a repository consisting of a Go backend and a React frontend. It support| Format Go | `make fmt` || Lint JS/CSS | `cd web && npm run lint` || Format JS/CSS | `cd web && npm run format` |+| Typecheck frontend | `cd web && npm run typecheck` || Full web CI check | `cd web && npm run check` || Build Storybook | `cd web && npm run build-storybook` || Generate API code | `make api-generate` |@@ -23,49 +26,54 @@ This is a repository consisting of a Go backend and a React frontend. It support| Install git hooks | `make install-hooks` || Start test stream | `./test/ocTestStream.sh` |-## Code Standards+## Working Agreements++- Commit messages follow Conventional Commits (`type(scope): summary`). The `commit-msg` hook rejects anything else. Allowed types: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`.+- No emoji in code, comments, or commit messages.+- Run `make install-hooks` once and lefthook covers the pre-commit gate: gofumpt, golangci-lint, eslint, prettier, stylelint, knip, and the Go and JS tests. Without hooks, run `make fmt`, `make lint`, and `cd web && npm run lint && npm run format` by hand before committing.+- `develop` is the development branch and moves fast (automated bundle and translation commits land often); rebase before pushing. `master` is the release branch.++## Development Flow-- UI component standards can be found in https://docs.owncast.dev/develop-frontend-components+- **Backend**: `go build -o owncast .`, `go test ./...`, `make lint`.+- **Frontend**: `cd web && npm run typecheck` for fast feedback. `npm run check` is the full CI-equivalent gate (lint, format, typecheck, knip, tests, build).+- **Never** copy frontend build output into `static/web/` and never commit that directory. It is generated during release builds; local development uses the dev server.+- **UI work**: components stay standalone and reusable with a story beside them, and `npm run build-storybook` must keep passing. Pattern guide: `web/components/_COMPONENT_HOW_TO.md`.+- **APIs**: edit `openapi.yaml` first, then run `make api-generate` (wraps `build/gen-api.sh`, which needs `npm install -g @redocly/cli`). It regenerates `webserver/handlers/generated/`; never hand-edit generated files, implement the stubs in `webserver/handlers/`.+- **Database**: schema changes are new numbered goose migrations in `persistence/migrations/`, and a migration that has shipped is never edited. Queries live in `db/query.sql`; run `make sqlc` after changing either, and don't hand-write SQL in Go. Adding a migration also means updating the pinned assertions in `persistence/migrations/migrations_test.go`. Walkthrough: `db/README.md`.+- **Tests**: Go tests beside the code, JS unit tests via `npm test`, API integration tests in `test/automated/api/`, browser flows in `test/automated/browser/`. Other suites live under `test/automated/` (`activitypub/`, `auth/`, `hls/`, `plugins/`, `upgrades/`).-### Required Before Each Commit+## Testing the Web Frontend-- Ensure all code is formatted using `golangci-lint` for Go, `stylelint` for CSS, and `prettier` for JavaScript/React.-- Fix any formatting or linting errors.+Run the backend and the frontend dev server together: `go run main.go` in the repo root, `cd web && npm run dev`, then use `http://localhost:3000`.-### Development Flow+Do not test against `http://localhost:8080`. That serves the web bundle embedded in the binary at compile time, not your working tree, so changes appear to have no effect.-- Build: Ensure the code builds successfully using `go build` for Go and `npm run build` for React in the `web` directory.-- Tests: Write unit tests for Go code and Javascript logic. Use `go test` and `npm run test`.-- UI components: Components should be standalone and reusable and show up in Storybook to enable testing, prototyping, and iteration.-- API: All APIs should be documented using OpenAPI specifications. Use `build/gen-api.sh` to generate the stubs, and then fill them in with your actual API implementation.-- If you made new UI components or made changes ensure that Storybook still builds by running `npm run build-storybook`.+`./test/ocTestStream.sh` starts a real stream against the local server when live-stream state is needed. Admin dev credentials are `admin` / `abc123` over HTTP Basic Auth; the admin UI is at `/admin`.## Repository Structure-- `web/`: The web source code for the React frontend.-- Root of the repo: Go source code for the backend.-- `static/web/`: Generated static files for the web application. Do not edit or commit files in this directory directly; they are generated from the `web` directory. Ignore this.-- `test/automated/api/`: A series of automated integration tests for API endpoints written in Javascript.-- `test/automated/browser/`: A series of automated browser UI tests for actual real-world browser interaction.-- `build/`: Build and code generation scripts.+- Root of the repo: Go source for the backend.+- `web/`: the React frontend (viewer page, admin, embeds).+- `static/web/`: generated web bundle. Never edit or commit it.+- `test/automated/`: integration, browser, and protocol test suites.+- `build/`: build and code generation scripts.+- `docs/`: internal design and reference docs (`backend.md`, `plugins.md`, `product-definition.md`, `Release.md`).### Backend Structure-- `main.go`: Entry point and composition root. Initializes logging, database, config, core services, metrics, then constructs every migrated service from `services/` and injects them into the HTTP router and other consumers. See "Service migration pattern" below for the policy.-- `webserver/router/`: Chi (v5) HTTP router with HTTP/2 support. Routes organized under `/api/`, `/api/admin/`, federation endpoints, `/hls/`, and `/ws`.-- `webserver/handlers/`: Request handlers for web, admin, static files, HLS streaming.-- `webserver/handlers/generated/`: Auto-generated API types and Chi server stubs from OpenAPI spec. Do not hand-edit.-- `webserver/router/middleware/`: Authentication (`RequireAdminAuth()` for admin endpoints via HTTP Basic Auth) and ActivityPub content negotiation middleware.-- `persistence/`: Repository pattern implementations (ConfigRepository, UserRepository, ChatMessageRepository, WebhookRepository, AuthRepository). All database access goes through these.-- `db/`: sqlc-generated type-safe database code. Schema in `db/schema.sql`, queries in `db/query.sql`. Run `make sqlc` after modifying.-- `core/`: Core streaming logic including transcoder, chat, webhooks, storage providers, playlist management.-- `core/storageproviders/`: Video storage backends (local filesystem and S3).-- `core/transcoder/`: FFmpeg-based video transcoding.-- `activitypub/`: Federation support (controllers, inbox/outbox, HTTP signatures, WebFinger, NodeInfo, worker pool).-- `models/`: Shared data models.-- `config/`: Configuration package with defaults and constants.-- `tools/`: Separate `go.mod` for development tool dependencies installed to `./bin/`.-- `services/`: Migrated services (constructor-injected, no package-level state). See "Service migration pattern" below for the rules.+- `main.go`: entry point and composition root. Initializes logging, database, config, core services, and metrics, then constructs every migrated service from `services/` and injects them into the HTTP router and other consumers. See "Service migration pattern" below.+- `webserver/router/`: Chi (v5) HTTP router with HTTP/2 support. Routes under `/api/`, `/api/admin/`, federation endpoints, `/hls/`, and `/ws`.+- `webserver/handlers/`: request handlers for web, admin, static files, HLS, moderation, auth.+- `webserver/handlers/generated/`: auto-generated API types and Chi server stubs from the OpenAPI spec. Do not hand-edit.+- `webserver/router/middleware/`: authentication (`RequireAdminAuth()` for admin endpoints via HTTP Basic Auth) and ActivityPub content negotiation.+- `persistence/`: repository implementations (config, user, chat message, webhook, auth, federated servers, notifications) plus goose migrations. All database access goes through these.+- `db/`: sqlc-generated type-safe database code. Queries in `db/query.sql`; the schema comes from the migrations, there is no `schema.sql`. Run `make sqlc` after changes.+- `services/`: constructor-injected services (stream, chat, transcoder, storage, rtmp, activitypub, plugins, webhooks, notifications, geoip, cache, datastore, dispatcher).+- `services/activitypub/`: federation (controllers, inbox/outbox, HTTP signatures, WebFinger, NodeInfo, delivery queue).+- `pluginhost/`: plugin host surface (auth gates, chat bots, plugin events) on top of `services/plugins/`.+- `models/`: shared data models. `config/`: defaults and constants. `auth/`: IndieAuth and Fediverse chat auth. `yp/`: directory registration. `utils/`, `logging/`, `metrics/`, `notifications/`: supporting packages.+- `tools/`: separate `go.mod` for dev tool pins, installed to `./bin/`.### Service migration pattern@@ -77,66 +85,59 @@ Owncast is being moved off package-level singletons toward constructor-injected3. **Existing `<pkg>.Get()` accessors (in `persistence/`) are deprecated** and exist only until their callers migrate. New code never calls `Get()`. PRs may reduce `Get()` callers; PRs must not add them.-When a service publishes events to multiple listeners, model the listeners as injected interfaces (`type StreamLifecycleListener interface { ... }`) and iterate them in the publisher. Don't introduce a generic event bus — explicit calls make stack traces, grep, and tests work the way the rest of the codebase expects.+When a service publishes events to multiple listeners, model the listeners as injected interfaces (`type StreamLifecycleListener interface { ... }`) and iterate them in the publisher. Don't introduce a generic event bus; explicit calls make stack traces, grep, and tests work the way the rest of the codebase expects.-The cache (`services/cache/`) is the first migrated service and is the reference shape; the `*Handlers` struct in `webserver/handlers/handlers.go` is the reference pattern for consumers of injected services.+`services/cache/` is the reference shape for a service, and the `*Handlers` struct in `webserver/handlers/handlers.go` is the reference pattern for consumers of injected services.### Frontend Structure-- `web/pages/`: Next.js 14 pages with static export.-- `web/components/`: React components organized by domain (`admin/`, `chat/`, `common/`, `layouts/`, `modals/`, `ui/`, `video/`, `action-buttons/`).-- `web/components/stores/`: Recoil state management stores.+- `web/pages/`: Next.js pages router with static export (viewer, `admin/`, `embed/`).+- `web/components/`: React components by domain (`admin/`, `chat/`, `common/`, `layouts/`, `modals/`, `ui/`, `video/`, `action-buttons/`, `theme/`).+- `web/components/stores/`: jotai state and the client config/status stores.+- `web/components/theme/`: Ant Design token theming (`AntdProvider.tsx`).- `web/interfaces/`: TypeScript interfaces.-- `web/i18n/`: Localization files (next-export-i18n).-- `web/style-definitions/`: Design token definitions.+- `web/i18n/`: localization files (next-export-i18n).+- `web/style-definitions/`: design token definitions.### Key Technical Details-- **Go version**: 1.24+ (see `go.mod`)-- **Database**: SQLite (single file, no external DB server needed)-- **Frontend framework**: Next.js 14, React 18, TypeScript, static export-- **UI library**: Ant Design v6 (design tokens themed via `web/components/theme/AntdProvider.tsx`, component CSS pre-extracted to `web/styles/antd.css` via `npm run antd:extract`)-- **State management**: Recoil-- **Styling**: SCSS with component-scoped files-- **API spec**: OpenAPI 3.1 at `openapi.yaml`-- **Commit style**: Conventional Commits (`type(scope): description`)-- **Branches**: `develop` is the development branch; `master` is the production/release branch-- **CI**: GitHub Actions for Go tests, JS linting/testing, browser tests, Storybook builds, Chromatic visual regression, CodeQL security scanning+- **Go version**: see `go.mod` (currently 1.26).+- **Database**: SQLite, single file, no external DB server.+- **Frontend**: Next.js 16 (pages router, static export), React 18, TypeScript.+- **UI library**: Ant Design v6. Tokens are themed in `web/components/theme/AntdProvider.tsx` and component CSS is pre-extracted to `web/styles/antd.css` via `npm run antd:extract`.+- **State management**: jotai.+- **Styling**: SCSS with component-scoped files.+- **API spec**: OpenAPI 3.1 in `openapi.yaml`.- **Go linting**: golangci-lint with cyclop (max complexity 15), dupl (threshold 200), gosec, gocritic, forbidigo (no `fmt.Print*`, `print`, `println`, or `panic`), and others. Full config in `.golangci.yml`.-- **JS linting**: ESLint with airbnb config, Prettier, Stylelint, knip for unused code detection-- **Makefile**: For common tasks like building, testing, linting, code generation, and installing dev tools/hooks. Run `make help` for a list of functions.--## Testing Web Frontend--Testing the web frontend requires running the frontend development server and the backend service together. The frontend development server must be started using `npm run dev` in the `web` directory, which will serve the web application at `http://localhost:3000`. The backend service can be started using `go run main.go` in the root of the repository.--Do not access the web application via `http://localhost:8080` or build the web project to copy files to the `static/web` directory for local development.--## Key Guidelines--1. All APIs are to be documented using OpenAPI specifications and code is to be generated using `build/gen-api.sh`. Additional details can be found at https://docs.owncast.dev/api-web-routing.-2. Write API tests for all new endpoints in the `test/automated/api` directory.-3. Use the `test/automated/browser` directory for browser-based tests for new functionality that simulate user interactions.-4. All user-facing frontend UI strings need to support localization. Use the `Translation` component to show most displayable strings. To create dynamic translated strings use the `next-export-i18n` library and the `t()` function. But use the `Translation` component unless there is a reason not to as it allows you to set default text. Read https://docs.owncast.dev/web-translations for more details. Test localization by adding "?lang=XX" with XX being a country code, such as "de" for German. Strings that have not yet been translated will not show as changed, but it's good to test anyway to make sure that previously translated strings have not been broken or regressed in any way.-5. A link to the PR's Storybook on Chromatic via the PR's Chromatic job should be included to help with review.-6. For API changes a before and after example of the API response should be added to the pull request to help with review.-7. For backend changes, a before and after example of logs to demonstrate the change should be added to the pull request to help with review.-8. Do not build the web project or copy the files to the `static/web` directory for local development.-9. When running the frontend development server, the local backend service must also be running. You can run the backend service using `go run main.go` in the root of the repository.-10. The credentials for the backend development backend are username: admin and password: abc123 and uses HTTP Basic Auth. This is used for the admin web application and the admin APIs.-11. The admin is found at `/admin`.-12. If a live stream video is needed to run, you can run `./test/ocTestStream.sh` to start an actual stream that will begin streaming from the local development server.-13. You should never commit the `static/web` directory to the repository. It is generated from the `web` directory and should be ignored in your commits.-14. Don't use emoji in code comments or commit messages. That's lame.-15. User interface components should use Ant Design v6 components. When using a new antd component, add it to the extraction manifest in `web/build-scripts/extract-antd-styles.js` and run `npm run antd:extract`.-16. Database access should be through the repository patterns.-17. Any substantial new features or changes around Federation or ActivityPub should be documented in FEDERATION.md.--## External Documentation--- Project documentation: https://docs.owncast.dev-- Frontend component guide: https://docs.owncast.dev/develop-frontend-components-- API and routing: https://docs.owncast.dev/api-web-routing-- Localization: https://docs.owncast.dev/web-translations-- Contributing guide: https://docs.owncast.dev/contributor-guide+- **JS linting**: ESLint with airbnb config, Prettier, Stylelint, and knip for unused code detection.+- **CI**: GitHub Actions for Go tests, JS lint/test, browser tests, Storybook builds, Chromatic visual regression, CodeQL.+- **Makefile**: common tasks for building, testing, linting, code generation, and installing dev tools and hooks. `make help` lists them.++## Guidelines++1. All user-facing UI strings must be localizable. Prefer the `Translation` component because it carries default text; use `next-export-i18n`'s `t()` only for strings built at runtime. Test with `?lang=de` (untranslated strings won't visibly change, but previously translated ones must not regress). Reference: https://docs.owncast.dev/web-translations+2. `web/i18n/*/translation.json` files are tab-indented and outside prettier's config. Add keys with a tab-preserving edit; running prettier on them rewrites the entire file.+3. UI components use Ant Design v6. When you use an antd component that isn't already in the build, add it to the manifest in `web/build-scripts/extract-antd-styles.js` and run `npm run antd:extract`.+4. All database access goes through the `persistence/` repositories.+5. Substantial Federation or ActivityPub changes must be reflected in `FEDERATION.md`, which documents only the peer-visible protocol contract, not internal implementation.+6. Public API changes (config, status, HLS, directory, auth, payload shapes) affect downstream native clients (`owncast/owncasts-ios`, `owncast/roku`). Call that out in the PR.++## Pull Requests++- UI changes: include before and after screenshots, plus the Chromatic Storybook link from the PR's Chromatic job.+- API changes: include before and after example responses.+- Backend changes: include before and after log output demonstrating the change.+- Take screenshots from Storybook for standalone components (hide unrelated controls), or from the dev server at `http://localhost:3000` for anything that isn't in Storybook, which is most of the admin. Embed them inline in the PR, not as attachments.+- Keep screenshot scripts and images in `/tmp`. Never commit them.++## References++- Operator documentation: https://owncast.online/docs/+- Component library and design docs (Storybook): https://owncast.online/components+- Development guide: https://docs.owncast.dev/development+- Frontend component guide: `web/components/_COMPONENT_HOW_TO.md` and https://docs.owncast.dev/develop-frontend-components+- API and web routing: https://docs.owncast.dev/api-web-routing+- Contributor guide: https://docs.owncast.dev/contributor-guide+- Public API reference: https://owncast.online/docs/api/ (the spec of record is `openapi.yaml`)- Federation protocol: `FEDERATION.md`+- Database workflow: `db/README.md`diff --git a/CLAUDE.md b/CLAUDE.mdindex fa1d36410c..22c37e48f1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,52 +1,5 @@-This is a repository consisting of a Go backend and a React frontend. It supports both an internal web application that is public facing, an internal admin web application, internal-only APIs for powering these web interfaces, and a set of APIs for third parties to take advantage of.+# Owncast-## Code Standards+Agent instructions for this repository live in `AGENTS.md`. There are no Claude-specific rules; read that file and follow it.-- UI component standards can be found in https://docs.owncast.dev/develop-frontend-components--### Required Before Each Commit--- Ensure all code is formatted using `golangci-lint` for Go, `stylelint` for CSS, and `prettier` for JavaScript/React.-- Fix any formatting or linting errors.--### Development Flow--- Build: Ensure the code builds successfully using `go build` for Go and `npm run build` for React in the `web` directory.-- Tests: Write unit tests for Go code and Javascript logic. Use `go test` and `npm run test`.-- UI components: Components should be standalone and reusable and show up in Storybook to enable testing, prototyping, and iteration.-- API: All APIs should be documented using OpenAPI specifications. Use `build/gen-api.sh` to generate the stubs, and then fill them in with your actual API implementation.-- If you made new UI components or made changes ensure that Storybook still builds by running `npm run build-storybook`.--## Repository Structure--- `web`: The web source code for the React frontend.-- Root of the repo: Go source code for the backend.-- `static/web`: Generated static files for the web application. Do not edit or commit files in this directory directly; they are generated from the `web` directory. Ignore this.-- `test/automated/api`: A series of automated integration tests for API endpoints written in Javascript.-- `test/automated/browser`: A series of automated browser UI tests for actual real-world browser interaction.-- `build/web`: Script to build and bundle the web application.--## Testing web frontend--Testing the web frontend requires running the frontend development server and the backend service together. The frontend development server must be started using `npm run dev` in the `web` directory, which will serve the web application at `http://localhost:3000`. The backend service can be started using `go run main.go` in the root of the repository.--Do not access the web application via http://localhost:8080 or build the web project to copy files to the `static/web` directory for local development.--## Key Guidelines--1. All APIs are to be documented using OpenAPI specifications and code is to be generated using `build/gen-api.sh`. Additional details can be found at https://docs.owncast.dev/api-web-routing.-2. Write API tests for all new endpoints in the `test/automated/api` directory.-3. Use the `test/automated/browser` directory for browser-based tests for new functionality that simulate user interactions.-4. All user-facing frontend UI strings need to support localization. Use the `Translation` component to show most displayable strings. To create dynamic translated strings use the `next-export-i18n` library and the `t()` function. But use the `Translation` component unless there is a reason not to as it allows you to set default text. Read https://docs.owncast.dev/web-translations for more details. Test localization by adding "?lang=XX" with XX being a country code, such as "de" for German. Strings that have not yet been translated will not show as changed, but it's good to test anyway to make sure that previously translated strings have not been broken or regressed in any way.-5. A link to the PR's Storybook on Chromatic via the PR's Chromatic job should be included to help with review.-6. For API changes a before and after example of the API response should be added to the pull request to help with review.-7. For backend changes, a before and after example of logs to demonstrate the change should be added to the pull request to help with review.-8. Do not build the web project or copy the files to the `static/web` directory for local development.-9. When running the frontend development server, the local backend service must also be running. You can run the backend service using `go run main.go` in the root of the repository.-10. The credentials for the backend development backend are username: admin and password: abc123 and uses HTTP Basic Auth. This is used for the admin web application and the admin APIs.-11. The admin is found at `/admin`.-12. If a live stream video is needed to run, you can run `./test/ocTestStream.sh` to start an actual stream that will begin streaming from the local development server.-13. You should never commit the `static/web` directory to the repository. It is generated from the `web` directory and should be ignored in your commits.-14. Don't use emoji in code comments or commit messages. That's lame.-15. User interface components should use Ant Design v4 components, not Ant Design v5.-16. Database schema changes (new tables, columns, indexes) are made by adding a new numbered goose migration in `persistence/migrations/`. Never edit a shipped migration. Queries live in `db/query.sql`; after changing schema or queries run `make sqlc` to regenerate the type-safe Go. Don't hand-write raw SQL in Go. See `db/README.md` for the full walkthrough.