124 lines
3.8 KiB
Plaintext
124 lines
3.8 KiB
Plaintext
---
|
|
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 (the root `package.json` selects the supported pnpm version)
|
|
- Git
|
|
- Docker with Docker Compose
|
|
- Go 1.25+ for the developer Docker CLI
|
|
- GitHub CLI for pull-request image features
|
|
|
|
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
|
|
|
|
Start PocketBase in another terminal:
|
|
|
|
```sh
|
|
cp apps/workshop/.env.example apps/workshop/.env
|
|
docker compose --env-file apps/workshop/.env -f apps/workshop/docker-compose.yml up --build workshop
|
|
```
|
|
|
|
Then start Docusaurus in a third terminal:
|
|
|
|
```sh
|
|
WORKSHOP_API_URL=http://127.0.0.1:8090 pnpm dev:docs
|
|
```
|
|
|
|
PocketBase runs on port 8090 and Docusaurus on port 3003. Stopping the services preserves 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 testing
|
|
|
|
Docusaurus reads `HOMARR_WEBSITE_URL` and `WORKSHOP_API_URL` when it starts or builds. Homarr also reads
|
|
`WORKSHOP_WEB_URL` when its server starts, so these values do not rely on `NEXT_PUBLIC_*` build variables. Test a
|
|
separate API origin 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/workshop \
|
|
pnpm dev:docs
|
|
```
|
|
|
|
### Useful commands
|
|
|
|
- `pnpm dev` — Next.js on port 3000.
|
|
- `pnpm dev:benchmark` — run the authenticated-board development benchmark.
|
|
- `pnpm dev:cli -- dev` — browse 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:install` — install the developer CLI as a `homarr` binary.
|
|
- `pnpm dev:docs` — Docusaurus only on port 3003.
|
|
- `pnpm docker:dev:up` — start Redis in the background.
|
|
- `pnpm docker:workshop` — local PocketBase through Docker Compose.
|
|
- `pnpm cli` — Homarr operations CLI.
|
|
- `pnpm db:migration:sqlite:run` — create or update a SQLite database.
|
|
- `pnpm db:seed` — seed the default database data.
|
|
- `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.
|