- TypeScript 90.9%
- Dockerfile 4.4%
- HTML 2.4%
- Nix 2.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
ci/woodpecker/push/application-checks Pipeline was successful
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 |
||
| .woodpecker | ||
| docs | ||
| examples | ||
| packages | ||
| patches | ||
| plugins | ||
| .dockerignore | ||
| .eslintignore | ||
| .eslintrc.js | ||
| .gitignore | ||
| .prettierignore | ||
| AGENTS.md | ||
| app-config.production.yaml | ||
| app-config.yaml | ||
| backstage.json | ||
| bun.lock | ||
| catalog-info.yaml | ||
| CODEOWNERS | ||
| flake.lock | ||
| flake.nix | ||
| package.json | ||
| playwright.config.ts | ||
| README.md | ||
| renovate.json | ||
| TODO.md | ||
| tsconfig.json | ||
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-sqlite3prebuilt 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.tssigns in through the guest auth provider and reads entities from/api/catalog/entities/by-name/.... It asserts that representative Forgejo components carry thePersonal/*project slug,user:default/martinownership,personal-servicesmembership, 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 therecurring-eventscomponent.packages/app/e2e-tests/catalog-browser.test.tssigns 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.jsonsets"packageManager": "bun@1.4.4";bun.lockis the committed lockfile.bun installis reproducible and updates the lockfile only when a manifest changes.- Only
better-sqlite3is intrustedDependencies, so its install script runs. On Node 24 it downloads a prebuilt binary, so no C++ toolchain or Python is needed;node-gypis 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. resolutionsare 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.patchreplaces the two places where the Backstage packager assumes Yarn: building a bundled package runsbun run buildinstead ofyarn run build, and the dist workspace no longer copies ayarn.lock. Re-check the patch whenever@backstage/clichanges;bun installfails loudly if it no longer applies.backstage-cli versions:bumpstill requires Yarn, because Backstage 1.56 only ships a Yarn lockfile module. Bump dependencies withbun 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/reactare on version 18, while@material-ui/coredeclares a^16.8.6 || ^17.0.0peer 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-routerandreact-router-domstay on 6.x because Backstage 1.56 declaresreact-router-dom@^6.30.2peers. 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.jsdomstays on 27.x because@backstage/clideclares a^27.1.0peer.better-sqlite3stays on 12.x because@backstage/backend-defaultsrequests^12.0.0.typescriptstays 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.