Local Backstage developer portal for repositories hosted on Forgejo.
  • TypeScript 90.9%
  • Dockerfile 4.4%
  • HTML 2.4%
  • Nix 2.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Martin Berg Alstad 1855476dc0
All checks were successful
ci/woodpecker/push/application-checks Pipeline was successful
docs: document TechDocs pilot and verification (#61)
Explain the pilot configuration, troubleshooting, and hosted publishing
and access controls. Add controlled TechDocs fixture coverage so the
reader integration is tested without live Forgejo or Docker access.

Refs: Personal/backstage#25

Co-authored-by: OpenCode <opencode@anoma.ly>

Reviewed-on: #61
2026-11-22 11:14:34 +00:00
.woodpecker feat(catalog): add scheduled Forgejo discovery (#51) 2026-11-21 18:37:02 +00:00
docs docs: document TechDocs pilot and verification (#61) 2026-11-22 11:14:34 +00:00
examples Remove central personal-services System source (#57) 2026-11-21 22:22:23 +00:00
packages docs: document TechDocs pilot and verification (#61) 2026-11-22 11:14:34 +00:00
patches build: replace Yarn with Bun as the package manager 2026-11-21 09:12:29 +00:00
plugins build: replace Yarn with Bun as the package manager 2026-11-21 09:12:29 +00:00
.dockerignore build: replace Yarn with Bun as the package manager 2026-11-21 09:12:29 +00:00
.eslintignore Initial commit 2026-10-14 16:43:15 +00:00
.eslintrc.js Initial commit 2026-10-14 16:43:15 +00:00
.gitignore build: replace Yarn with Bun as the package manager 2026-11-21 09:12:29 +00:00
.prettierignore feat(catalog): add scheduled Forgejo discovery (#51) 2026-11-21 18:37:02 +00:00
AGENTS.md Remove central personal-services System source (#57) 2026-11-21 22:22:23 +00:00
app-config.production.yaml Initial commit 2026-10-14 16:43:15 +00:00
app-config.yaml Tailor portal to Personal developer workflow (#58) 2026-11-21 22:49:54 +00:00
backstage.json chore(deps): update dependencies for Backstage 1.56.5 (#36) 2026-11-17 20:21:24 +00:00
bun.lock fix(catalog): reject duplicate descriptor entity refs (#52) 2026-11-21 19:07:32 +00:00
catalog-info.yaml Use repository-owned catalog descriptors (#56) 2026-11-21 21:55:15 +00:00
CODEOWNERS Remove clank-not from CODEOWNERS 2026-11-17 19:54:58 +00:00
flake.lock build: replace Yarn with Bun as the package manager 2026-11-21 09:12:29 +00:00
flake.nix build: move runtime to Node 24 (#50) 2026-11-21 14:17:53 +00:00
package.json feat(catalog): add scheduled Forgejo discovery (#51) 2026-11-21 18:37:02 +00:00
playwright.config.ts feat(catalog): add scheduled Forgejo discovery (#51) 2026-11-21 18:37:02 +00:00
README.md docs: document TechDocs pilot and verification (#61) 2026-11-22 11:14:34 +00:00
renovate.json build: move runtime to Node 24 (#50) 2026-11-21 14:17:53 +00:00
TODO.md test(e2e): verify the imported catalog end to end (#35) 2026-11-17 19:58:28 +00:00
tsconfig.json Initial commit 2026-10-14 16:43:15 +00:00

Personal Developer Portal

A local Backstage developer portal for repositories hosted on Forgejo at code.martials.no.

Requirements

  • Node.js 24
  • Bun 1.4.4 (package manager and script runner)
  • Python 3 (only needed when a native dependency has to compile from source; Node 24 uses the published better-sqlite3 prebuilt binary)
  • Network access to code.martials.no

On NixOS or another system with Nix flakes enabled, enter the development environment with:

nix develop

The shell pins Bun 1.4.4 through the nixpkgs-unstable flake input while Node comes from the main nixpkgs input.

Start locally

bun install
bun run dev

Open http://localhost:3000. The frontend and backend bind to localhost. The development app uses guest sign-in and an in-memory SQLite database; do not expose it to a network or use it for production data.

The backend discovers repositories for the configured Forgejo owners at startup and refreshes every 15 minutes. Only repositories with a root catalog-info.yaml are imported; each repository descriptor is the source of truth for its catalog metadata. To discover private repositories visible to your account, create a read-only Forgejo API token and export it before starting:

export FORGEJO_TOKEN='your-read-only-token'
bun run dev

Catalog behavior

Repositories with a root catalog-info.yaml are discovered as catalog locations and processed by Backstage. Repositories without the descriptor are not added to the catalog. Entity names, ownership, systems, APIs, lifecycle, links, and other metadata belong in the repository descriptor; there is no central per-repository enrichment map.

The local starter users and groups are in examples/org.yaml; the personal-services System and repository Components/APIs are imported from Forgejo descriptors. The System is owned by the cluster GitOps repository. Forgejo integration is configured in app-config.yaml; credentials are read from FORGEJO_TOKEN and are not stored in Git. FORGEJO_URL overrides the integration base URL. Configure owner selection, polling cadence, and request timeouts under catalog.providers.forgejo.main.

Use this repository's root catalog-info.yaml as the reference for adding metadata to a Forgejo repository. See Repository catalog onboarding for the descriptor policy, field guidance, and validation steps.

Refreshes fetch every repository page and verify descriptor availability before publishing a full snapshot of descriptor-backed repositories. A failed API request or timeout leaves the last successful snapshot in place; a later successful refresh removes repositories that have disappeared or no longer have a descriptor. Backend logs report the last successful refresh timestamp and the current refresh error, if any.

The built-in Backstage Gitea discovery provider was evaluated but is not used as the repository discovery source: it only imports repositories that already have a descriptor, and its current refresh behavior can treat per-repository API errors as missing descriptors. The Forgejo provider here reuses the configured Gitea integration for authentication while retaining all-or-nothing refreshes.

See Forgejo catalog discovery for the refresh lifecycle, configuration, descriptor precedence, and troubleshooting details.

Catalog verification

Playwright verifies the imported catalog end to end:

bun run test:e2e

The checks run against the controlled fixtures in packages/app/e2e-tests/fixtures/catalog, which the E2E app-config overlay loads by setting CATALOG_DIR for the dev servers and disabling live discovery. The suite therefore needs no Forgejo token, no network access to code.martials.no, and no live repository data. Outside CI the command starts the app and backend itself; expect roughly two minutes on the first run.

  • packages/app/e2e-tests/catalog-api.test.ts signs in through the guest auth provider and reads entities from /api/catalog/entities/by-name/.... It asserts that representative Forgejo components carry the Personal/* project slug, user:default/martin ownership, personal-services membership, and their repository and service links. It also asserts that the recurring-events API embeds its OpenAPI definition, belongs to the system, and is provided by the recurring-events component.
  • packages/app/e2e-tests/catalog-browser.test.ts signs in in the browser, opens a component page to check the Forgejo and production links, and follows the API list to the rendered OpenAPI definition.

Two environment variables cover non-default setups:

E2E_CATALOG_DIR=/path/to/catalog bun run test:e2e        # verify another catalog
PLAYWRIGHT_BACKEND_URL=http://host:7007 bun run test:e2e # backend on another host

On NixOS, run the tests from nix develop. The shell provides Chromium and exports PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH, which playwright.config.ts passes to the browser launcher, so Playwright does not try to use a downloaded browser that cannot run on NixOS.

Optional live verification

To check discovery against the real Forgejo instance, start the app with a read-only token:

export FORGEJO_TOKEN='your-read-only-token'
bun run dev

Open http://localhost:3000/catalog and check the entities described by the selected repositories' catalog-info.yaml files.

Never commit the token or paste it into an issue. The automated suite does not read FORGEJO_TOKEN.

TechDocs

Documentation is repository-owned: a repository adds an MkDocs source and a backstage.io/techdocs-ref annotation to its catalog descriptor, and Backstage renders it on the Component's TechDocs tab. The pilot is Personal/recurring-events, which builds its docs with just docs and previews them with just docs-serve.

The local backend builds docs on request with the Docker-based TechDocs generator and stores them locally. See TechDocs for verification steps, troubleshooting, and the CI publishing, private storage, and access-control approach for a hosted portal.

Useful commands

bun run dev              # Start Backstage; Forgejo discovery refreshes on schedule
bun run tsc              # TypeScript check
bun run build:app        # Production frontend bundle
bun run build:backend    # Frontend bundle plus backend dist bundle

Package manager and runtime

Bun 1.4.4 is the package manager and the entry point for repository scripts. Node.js 24 runs Backstage, Jest, the TypeScript compiler, and the production backend, because native modules such as better-sqlite3 are built for the Node ABI and do not load under Bun.

  • package.json sets "packageManager": "bun@1.4.4"; bun.lock is the committed lockfile. bun install is reproducible and updates the lockfile only when a manifest changes.
  • Only better-sqlite3 is in trustedDependencies, so its install script runs. On Node 24 it downloads a prebuilt binary, so no C++ toolchain or Python is needed; node-gyp is only reached when a prebuild is missing. Bun blocks the other eight lifecycle scripts (@swc/core, core-js, protobufjs, @parcel/watcher, @tree-sitter-grammars/tree-sitter-yaml, and similar); they are optional postinstalls and the suite passes without them.
  • resolutions are kept and honored by Bun; the lockfile was migrated from Yarn 4.18 with no version drift.
  • patches/@backstage%2Fcli-module-build@0.1.9.patch replaces the two places where the Backstage packager assumes Yarn: building a bundled package runs bun run build instead of yarn run build, and the dist workspace no longer copies a yarn.lock. Re-check the patch whenever @backstage/cli changes; bun install fails loudly if it no longer applies.
  • backstage-cli versions:bump still requires Yarn, because Backstage 1.56 only ships a Yarn lockfile module. Bump dependencies with bun update, or run the command in a throwaway Yarn checkout and migrate the resulting lockfile.

Validation

The following commands are the validated baseline for this repository, run with Node.js 24 and Bun 1.4.4:

bun install --frozen-lockfile   # Reproducible install; fails if bun.lock would change
bun run tsc                     # TypeScript check
bun run lint:all                # ESLint across all packages
bun run prettier:check          # Formatting check
bun run test:ci                 # Jest, single non-interactive run
bun run test:e2e                # Playwright catalog checks against fixtures
bun run build:app               # Production frontend bundle
bun run build:backend           # Frontend bundle and backend dist bundle

bun run test starts Jest in watch mode when the CI environment variable is unset, which is why it never exits locally. bun run test:ci passes --watchAll=false for a single run; CI=true bun run test behaves the same. Append --runInBand when you need deterministic ordering or a stable CI log. bun run test:e2e needs a Playwright browser; see Catalog verification.

Continuous integration

Woodpecker runs the repository-owned application-checks workflow from .woodpecker/application-checks.yaml on pull requests and on pushes to the default branch. It uses Node 24 and installs Bun 1.4.4 into .ci/bun inside the workspace, then runs bun install --frozen-lockfile, typecheck, lint, formatting, unit tests, the frontend and backend builds, and the Playwright suite as separate steps so a failure points at the check that broke. The unit-test step reports a dedicated error when Jest exceeds 15 minutes. The install step installs curl and unzip with apt but no Python or compiler, because the better-sqlite3 prebuild matches the Node 24 ABI.

The workflow needs no FORGEJO_TOKEN and does not run the catalog sync. It runs alongside the organization's global workflows such as pr-review, so application failures remain distinguishable from automated-review results. Keep the Node image, the Bun version in the install step, and packageManager in sync.

Docker

packages/backend/Dockerfile starts from node:24-trixie-slim and copies the pinned Bun binary from oven/bun:1.4.4-slim for the production install. The image runs bun install --omit=dev (Bun refuses --production once the packager has stripped the bundled app's manifest) and then starts the backend with Node 24, which matches the ABI of the better-sqlite3 binary built during the install.

Known dependency warnings

bun install reports peer-dependency warnings that are accepted rather than fixed in this repository:

  • react, react-dom, and @types/react are on version 18, while @material-ui/core declares a ^16.8.6 || ^17.0.0 peer range. Backstage 1.56 still ships Material UI v4 through @backstage/core-components, and requires React 18 itself, so the ranges cannot both be satisfied. Do not replace @material-ui/* with @mui/* here; that migration belongs upstream.
  • Upstream @backstage/cli* packages report missing optional peers among themselves (jest, typescript, webpack, and similar). Those are dependency-internal and not actionable from this workspace.

These dependencies are also held at the newest version their Backstage release supports, rather than the newest published major:

  • react-router and react-router-dom stay on 6.x because Backstage 1.56 declares react-router-dom@^6.30.2 peers. The remaining react-router advisories are fixed only in 7.18 or later, so they cannot be resolved without an upstream Backstage upgrade. Re-check this before the hosted deployment in #30.
  • jsdom stays on 27.x because @backstage/cli declares a ^27.1.0 peer.
  • better-sqlite3 stays on 12.x because @backstage/backend-defaults requests ^12.0.0.
  • typescript stays on 5.9; the TypeScript 7 native compiler is not yet validated by the Backstage CLI.
  • CI, the backend Dockerfile, and the development shell are pinned to Node 24, the validated runtime selected in #47. Renovate is constrained to this major; test a new major before changing the allowed version.