--- 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 ` — build the current checkout as `homarr:`. - `bun run dev:cli -- build --pr ` — build a pull request from a temporary checkout. - `bun run dev:cli -- rebuild ` — 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 ` | 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 ` | Docker-backed service and database compatibility tests | Docker | | `bun run test:e2e ` | 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 `` 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.