Pandore/homarr
Public Access
1
0 Fork 0
Code Actions Activity
Files
145dc17d8dec22b56facaf9ecd5d4231d40524fc
homarr/apps/docs/docs/advanced/development/getting-started.mdx
T
Thomas 229bd4b3ed chore: use Bun package management and Turbo remote caching (#6978) 
* feat: migrate tooling and runtimes to bun

* fix: serialize act installs and adapt backup checks

* fix: finish bun scripts and rootless act setup

* fix: support bun images in runtime benchmarks

* fix: keep a single bun toolchain configuration

* fix: include docs mascot sources in workshop build

* docs: use bun in remaining tool commands

* fix: complete bun sqlite development tooling

* docs: explain sqlite development adapter

* fix: align remaining commands and local ci validation

* fix: use renovate regex fallback with bun

* fix: finalize bun sqlite connections during cleanup

* fix: preserve sqlite foreign key enforcement

* fix: align docker build frontends

* fix: prepare release versions with bun

* Add Bun benchmarks and preserve SQLite connection defaults

* Benchmark Bun installs, conflicts and production workloads

* Force Bun workspace tools and HTTP/1.1 upstream streaming

* Exclude benchmark evidence from Docker contexts

* Expose branch benchmarks through CI

* Verify hydrated widget data in production benchmarks

* Measure image archives and document benchmark protocol

* Audit dependency sharing across every workspace

* Pin pnpm for nested baseline benchmark scripts

* Preserve nested manager pinning on benchmark resume

* Include application and runtime image footprints

* Fail benchmark gates on candidate command errors

* Report complete build overhead and sampled memory bounds

* Validate migration comparisons across pinned revisions

* Record configurable runtime memory budgets

* Retain out-of-memory kills in runtime budget probes

* Reject OOM events consistently across runtime metrics

* Record complete Bun migration benchmarks

* Record memory diagnosis and correct Turbo caching

* Use Bun package management while preserving Node runtimes

* Keep native build fallbacks and exclude development artifacts

* Fix Node ESM metadata and isolate local CI configuration

* Measure development performance and isolate act environment

* Support isolated environment files in rootless act

* Validate the full migration range with act

* Preserve native SQLite binding for bundled migrations

* Use documented dev defaults and report benchmark scope

* Validate dev defaults and isolate restart measurements

* Record package-manager and development benchmarks

* Keep benchmark measurements and link full command artifacts

* Clean up temporary act environment files

* Validate Node runtimes in package-manager comparisons

* Validate every workspace in manual CI runs

* Retain patched nested brace expansion versions

* Complete package-manager and Node performance report

* Normalize archived benchmark logs

* Record final hosted validation

* Cache both Next builds with platform isolation

* Prime cache with write-only mode

* Split Next artifacts below Cloudflare upload limit

* Assemble coherent standalone cache outputs

* Preserve traced middleware entrypoints

* Assemble traced directory links before files

* Separate cached dependencies from assembled output

* Record signed Turbo cache benchmarks

* Remove archived benchmark captures

Full benchmark evidence is preserved at 8f7d3bcd14109bfb13fa664d31710b88d820ad66.

* Remove migration benchmark harness

* fix: correct migration launch and local Act prerequisites

* Consolidate Turbo caches and production artifacts

* Exclude generated files from Docker cache inputs

* fix: address Bun migration review findings

* fix: check restored compiler bundle manifests
2026-10-07 16:38:14 +02:00

144 lines
8.1 KiB
Plaintext
Raw Blame History

---
title: Getting started
tags:
- Developer
- Technical documentation
- Code
- Programming
sidebar_position: 1
---
## Set up your development environment
### Prerequisites
- **Node.js 24.18.0**: application and tooling runtime, pinned in `mise.toml`.
- **Bun 1.4.2**: Install the version pinned in `mise.toml` from the [official website](https://bun.sh/docs/installation).
- **Git**: You can download it from the [official website](https://git-scm.com/).
- **Docker or Docker Desktop**: Required for the Redis service and the developer Docker CLI.
- **Go 1.25+**: Required only for the developer Docker CLI. You can download it from the [official website](https://go.dev/).
- **GitHub CLI**: Required only for pull-request image features. Install it from the [official website](https://cli.github.com/), then authenticate with `gh auth login`.
Install dependencies once at the repository root. Bun uses a hoisted workspace installation, so compatible dependencies
are shared across packages. Catalog versions, patches and overrides live in the root `package.json`.
```sh
bun install --frozen-lockfile
```
Next.js, operational commands and SQLite run on Node.js. Bun installs dependencies and dispatches package scripts.
### Run the Homarr application
1. Copy `.env.example` to `.env`.
2. Run `openssl rand -hex 32` twice. Set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
values in `.env`; the example leaves both empty. Keep this file private and preserve `SECRET_ENCRYPTION_KEY`
when reusing a database.
3. Set `DB_URL` to an absolute writable SQLite file path. Migration and application commands run from different
workspace directories, so a relative path can point them at different databases.
4. Keep Redis and the optional local databases running in one terminal.
5. Apply migrations and start Next.js in another terminal.
```sh
cp .env.example .env
```
Terminal 1:
```sh
bun run docker:dev
```
Terminal 2:
```sh
bun run db:migration:sqlite:run
bun run dev
```
The infrastructure command remains in the foreground. Open `http://127.0.0.1:3000`; the first user created through
Homarr becomes the instance administrator.
Use `bun run docker:dev:up` instead when you only need Redis in the background. Running the migration also seeds the
default data; use `bun run db:seed` to seed it explicitly later.
`bun run dev` starts only Next.js. When your work needs scheduled tasks or live subscriptions, run the relevant service
in a separate terminal alongside it:
```sh
bun run --filter @homarr/tasks dev
```
```sh
bun run --filter @homarr/websocket dev
```
The WebSocket service listens on port 3001. Production startup embeds both services, so these extra commands are
only needed for development.
Workshop contributors can set up PocketBase and Fumadocs with the dedicated
[Workshop development guide](/docs/advanced/development/workshop).
### Useful commands
- `bun run dev` — Next.js on port 3000.
- `bun run dev:benchmark` — authenticated-board benchmark; readiness-only `--smoke` runs are not performance claims.
- `bun run dev:cli -- dev` — browse and run local images and remote pull-request images.
- `bun run dev:cli -- build <name>` — build the current checkout as `homarr:<name>`.
- `bun run dev:cli -- build --pr <number>` — build a pull request from a temporary checkout.
- `bun run dev:cli -- rebuild <name>` — rebuild an image from its recorded checkout or pull request.
- `bun run dev:cli:install` — optionally install the developer CLI as a `homarr` binary.
- `bun run dev:docs` — Fumadocs on port 3003.
- `bun run docker:dev:up` — Redis development service in the background.
- `bun run cli` — Homarr operations CLI.
- `bun run db:migration:sqlite:run` — create or update a SQLite database.
- `bun run db:seed` — seed the default database data explicitly.
- `bun run db:studio` — inspect the database.
- `bun run format` / `bun run format:fix` — check or apply oxfmt.
- `bun run lint` / `bun run lint:fix` — check or apply oxlint.
- `bun run typecheck` — typecheck all workspaces.
- `bun run test` — unit and contract suites.
- `bun run build` — production monorepo build.
- `docker build -t homarr:local .` — build a production Docker image.
- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:local` — run it.
## CI and focused validation
The main CI workflow validates SQLite and PostgreSQL migrations before lint, typechecking, affected workspace builds, workspace configuration, OpenAPI, and Custom Widget architecture and bundle checks. Manual container validation builds an amd64 image and exercises MySQL conversion, authentication, and restart persistence. Preview publication requires the Fast gate and both architecture builds.
Workshop CI runs when its workflow or Docker build inputs change. Pull requests exercise production images on amd64 and arm64; release branches publish them after Compose validation. Workspace typechecks run in the main Fast gate.
Choose the smallest relevant suite when changing behavior:
| Command | Scope | Requirements |
| ------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `bun run test <file>` | Focused unit or contract tests | Workspace dependencies |
| `bun run test` | All unit and contract tests, without Docker integration suites | Workspace dependencies |
| `bun run test:coverage` | Unit and contract tests with coverage | Workspace dependencies |
| `bun run test:integration <file>` | Docker-backed service and database compatibility tests | Docker |
| `bun run test:e2e <file>` | Browser and container scenarios | Docker; Playwright Chromium and system dependencies for browser tests |
| `bun run test:docs-screenshots` | Regenerate Assistant documentation screenshots | Same browser prerequisites |
| `bun run test:workshop` / `bun run test:workshop-image` | Workshop integration / production-image validation | Docker |
Omit `<file>` to run all tests in that command's scope. E2E and screenshot commands use a local image tagged `homarr-e2e`, or an image selected with `HOMARR_E2E_IMAGE`. The default commands run once without automatic retries; coverage is opt-in. The screenshot generator is excluded from both unit and E2E commands.
Keep behavioral coverage for authorization, migrations, persistence, and widget execution. Avoid tests that only search source code for particular component names, JSX, CSS, or documentation wording.
## Documentation development
Run `bun run dev:docs` to open the Next.js and Fumadocs site at `http://127.0.0.1:3003`. Content lives in
`apps/docs/docs/`; the nearest `meta.json` controls navigation. Keep integration and widget setup metadata in their
typed `index.ts` files alongside the page.
After changing content, navigation, or shared MDX components, run:
```sh
bun run --filter @homarr/docs build
bun run --filter @homarr/docs validate:links
bun run --filter @homarr/docs verify:search
bun run --filter @homarr/docs verify:seo
```
The build writes a static site to `apps/docs/out/`. Check heading links, search results, and the page's Markdown export
when changing shared components. The [Fumadocs documentation](https://fumadocs.dev/docs) describes supported components
and source APIs; match examples to the versions installed in this repository.
View Git Blame Copy Permalink