---
title: Getting started
tags:
  - Developer
  - Technical documentation
  - Code
  - Programming
sidebar_position: 1
---

## Set up your development environment

### Prerequisites

- Node.js 24.18 or newer
- Corepack and pnpm 11.11
- Git
- Docker with Docker Compose

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

```sh
corepack enable
corepack install
pnpm install --frozen-lockfile
```

### Run the Homarr application

1. Copy `.env.example` to `.env`.
2. Set `DB_URL` to an absolute writable SQLite file path.
3. Keep Redis and the optional local databases running in one terminal.
4. Apply migrations and start Next.js in another terminal.

```sh
cp .env.example .env
```

Terminal 1:

```sh
pnpm docker:dev
```

Terminal 2:

```sh
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.

### Run PocketBase and documentation

Use the integrated local Workshop command in a second terminal:

```sh
pnpm dev:workshop
```

It starts persistent PocketBase on port 8090, waits for health and the required collections, then starts Docusaurus on
port 3003. It also propagates shutdown without deleting the PocketBase volume.

Open `http://127.0.0.1:8090/_/` and create the first PocketBase superuser. The Workshop UI is available at
`http://127.0.0.1:3003/workshop`.

Point Homarr at the local services with:

```dotenv
HOMARR_WEBSITE_URL=http://127.0.0.1:3003
WORKSHOP_API_URL=http://127.0.0.1:8090
WORKSHOP_WEB_URL=http://127.0.0.1:3003/workshop
```

Restart `pnpm dev` after changing `.env`. GitHub OAuth is optional locally. See
[`apps/workshop/README.md`](https://github.com/homarr-labs/homarr/blob/HEAD/apps/workshop/README.md) for OAuth,
Workshop moderator promotion, logs, tests, backup, restore, stopping, and intentional volume reset.

### URL and base-path testing

Docusaurus reads `HOMARR_WEBSITE_URL`, `WORKSHOP_API_URL`, `WORKSHOP_WEB_URL`, and `DOCS_BASE_URL` at startup/build.
Homarr renders its public URL values into the page at server startup, so Docker overrides do not rely on
`NEXT_PUBLIC_*` build variables. Test a separate API origin and non-root documentation path before release:

```sh
HOMARR_WEBSITE_URL=http://127.0.0.1:3003 \
WORKSHOP_API_URL=http://127.0.0.1:8090 \
WORKSHOP_WEB_URL=http://127.0.0.1:3003/docs-site/workshop \
DOCS_BASE_URL=/docs-site/ \
pnpm dev:docs
```

### Useful commands

- `pnpm dev` — Next.js on port 3000.
- `pnpm dev:docs` — Docusaurus only on port 3003.
- `pnpm dev:workshop` — persistent PocketBase plus Docusaurus.
- `pnpm cli` — Homarr operations CLI.
- `pnpm db:migration:sqlite:run` — create or update a SQLite database.
- `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 test:workshop` — disposable Workshop integration suite.
- `pnpm build` — production monorepo build.