Getting started

Set up your development environment

Prerequisites

• Node.js 24.18 or newer: You can download it from the official website.
• Corepack: Run corepack enable so the repository selects its pinned pnpm 11 version.
• 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.

The versions in the root package.json are the supported baseline. Let Corepack select the repository version instead of installing an unrelated global pnpm:

corepack enable
corepack install
pnpm install --frozen-lockfile

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:

pnpm docker:dev

Terminal 2:

pnpm db:migration:sqlite:run
pnpm 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 pnpm docker:dev:up instead when you only need Redis in the background. Running the migration also seeds the default data; use pnpm db:seed to seed it explicitly later.

pnpm dev starts only Next.js. When your work needs scheduled tasks or live subscriptions, run the relevant service in a separate terminal alongside it:

pnpm --filter @homarr/tasks dev

pnpm --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

• pnpm dev — Next.js on port 3000.
• pnpm dev:benchmark — authenticated-board benchmark; readiness-only --smoke runs are not performance claims.
• pnpm dev:cli -- dev — browse and run local images and remote pull-request images.
• pnpm dev:cli -- build <name> — build the current checkout as homarr:<name>.
• pnpm dev:cli -- build --pr <number> — build a pull request from a temporary checkout.
• pnpm dev:cli -- rebuild <name> — rebuild an image from its recorded checkout or pull request.
• pnpm dev:cli:install — optionally install the developer CLI as a homarr binary.
• pnpm dev:docs — Fumadocs on port 3003.
• pnpm docker:dev:up — Redis development service in the background.
• pnpm cli — Homarr operations CLI.
• pnpm db:migration:sqlite:run — create or update a SQLite database.
• pnpm db:seed — seed the default database data explicitly.
• pnpm db:studio — inspect the database.
• pnpm format / pnpm format:fix — check or apply oxfmt.
• pnpm lint / pnpm lint:fix — check or apply oxlint.
• pnpm typecheck — typecheck all workspaces.
• pnpm test — unit and contract suites.
• pnpm 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 runs lint, typechecking, affected workspace builds, workspace configuration checks, OpenAPI validation, and Custom Widget architecture and bundle checks. Unit and E2E suites do not run in CI. Preview images publish after the Fast gate and both architecture builds succeed; browser tests do not block publication. The container job builds an amd64 image when no preview image was built.

Workshop CI runs only when its workflow or Docker build inputs change. It validates Compose configuration and publishes production images on its configured release branches. Its Docker integration and image tests are manual; 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 pnpm 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:

pnpm --filter @homarr/docs build
pnpm --filter @homarr/docs validate:links
pnpm --filter @homarr/docs verify:search
pnpm --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.