93 lines
2.6 KiB
Markdown
93 lines
2.6 KiB
Markdown
# Homarr development
|
|
|
|
This repository contains the Homarr application, task and WebSocket services, the Docusaurus documentation site, and
|
|
the PocketBase-backed Community Workshop.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 24.18 or newer
|
|
- Corepack with pnpm 11.11
|
|
- Docker with Docker Compose
|
|
- Git
|
|
|
|
Enable the repository's pnpm version and install dependencies:
|
|
|
|
```sh
|
|
corepack enable
|
|
corepack install
|
|
pnpm install --frozen-lockfile
|
|
```
|
|
|
|
## Run Homarr locally
|
|
|
|
Copy the environment template and choose a writable absolute SQLite path:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
Keep the development infrastructure running in the first terminal:
|
|
|
|
```sh
|
|
pnpm docker:dev
|
|
```
|
|
|
|
Then apply migrations and start Homarr in a second terminal:
|
|
|
|
```sh
|
|
pnpm db:migration:sqlite:run
|
|
pnpm dev
|
|
```
|
|
|
|
Homarr is available at `http://127.0.0.1:3000`. The foreground infrastructure command starts Redis and the optional
|
|
database services from `development/development.docker-compose.yml`; stop it with Ctrl+C after stopping Homarr.
|
|
|
|
## Run PocketBase and documentation locally
|
|
|
|
The integrated command starts persistent PocketBase on port 8090, waits for its health endpoint and Workshop
|
|
collections, then starts Docusaurus on port 3003:
|
|
|
|
```sh
|
|
pnpm dev:workshop
|
|
```
|
|
|
|
Open the PocketBase administration UI at `http://127.0.0.1:8090/_/` to create the first superuser. Open the Workshop at
|
|
`http://127.0.0.1:3003/workshop`.
|
|
|
|
To run Homarr against this local stack, set these values in `.env` and restart `pnpm dev`:
|
|
|
|
```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
|
|
```
|
|
|
|
Stopping `pnpm dev:workshop` stops the services but retains the `homarr-workshop_pb_data` volume. See
|
|
[`apps/workshop/README.md`](apps/workshop/README.md) for OAuth, moderator access, logs, backup, restore, and intentional
|
|
reset instructions.
|
|
|
|
## Common checks
|
|
|
|
```sh
|
|
pnpm format
|
|
pnpm lint
|
|
pnpm typecheck
|
|
pnpm test
|
|
pnpm test:workshop
|
|
pnpm turbo build --filter=@homarr/docs
|
|
```
|
|
|
|
Use `pnpm format:fix` and `pnpm lint:fix` to apply mechanical fixes. User-facing code changes must include the matching
|
|
documentation under `apps/docs/docs/`.
|
|
|
|
## Repository map
|
|
|
|
- `apps/nextjs` — main Homarr web application
|
|
- `apps/tasks` — scheduled task runner and API
|
|
- `apps/websocket` — WebSocket server
|
|
- `apps/docs` — Docusaurus documentation and public Workshop UI
|
|
- `apps/workshop` — PocketBase image, migrations, hooks, and integration tests
|
|
- `packages` — shared application, API, database, UI, widget, and integration packages
|
|
- `development` — local Docker infrastructure
|
|
- `e2e` — end-to-end tests
|