Getting started

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.
• Git: You can download it from the official website.
• 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.
• GitHub CLI: Required only for pull-request image features. Install it from the official website, 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.

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.

cp .env.example .env

Terminal 1:

bun run docker:dev

Terminal 2:

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:

bun run --filter @homarr/tasks dev

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.

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:

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:

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 describes supported components and source APIs; match examples to the versions installed in this repository.