Pandore/homarr
Public Access
1
0 Fork 0
Code Actions Activity

refactor(dev): make setup explicit and portable

Browse Source
This commit is contained in:
Thomas Camlong committed 2026-07-31 23:52:14 +02:00
1 parent b733ed6a79
commit 5b04ed1ab5
7 files changed
+51 -119
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/ci.yml
-10
View File
@@ -78,16 +78,6 @@ jobs:
- name: Setup
uses: ./tooling/github/setup
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version-file: tools/homarr-dev/go.mod
cache-dependency-path: tools/homarr-dev/go.sum
- name: Validate developer CLI
working-directory: tools/homarr-dev
run: go test -race ./... && go vet ./...
- name: Copy environment defaults
run: cp .env.example .env
AGENTS.md
+6 -5
View File
@@ -70,7 +70,9 @@ When modifying user-facing code, you MUST also update the corresponding document
## Monorepo Commands
- `pnpm dev` — Next.js app only
- `pnpm dev:setup` — install dependencies, prepare Redis and SQLite, and install the `homarr` developer CLI
- `pnpm dev:cli -- dev` — run the developer CLI without installing a global binary
- `pnpm db:seed` — seed default database data explicitly
- `pnpm docker:dev:up` — start the Redis development service in the background
- `pnpm dev:docs` — Docusaurus docs site only
- `pnpm turbo build` — build all packages
- `pnpm turbo build --filter=@homarr/docs` — build docs only
@@ -84,8 +86,7 @@ When modifying user-facing code, you MUST also update the corresponding document
- UI: Mantine (not Tailwind) — Tailwind is only used in docs app
- Icons: @tabler/icons-react
- Docs app can import from `@homarr/definitions` for shared types
- Run `homarr dev` to browse local `homarr:*` images and remote PR images.
- Run `homarr build <name>` from a Homarr checkout to build `homarr:<name>` with rebuild provenance.
- Run `homarr build --pr <number>` to build a PR locally from a temporary checkout.
- Run `pnpm dev:cli -- dev` to browse local `homarr:*` images and remote PR images.
- Run `pnpm dev:cli -- build <name>` from a Homarr checkout to build `homarr:<name>` with rebuild provenance.
- Run `pnpm dev:cli -- build --pr <number>` to build a PR locally from a temporary checkout.
- Run Go checks from `tools/homarr-dev` with `go test ./...` and `go vet ./...`.
- Changes to `tools/homarr-dev` are validated by the fast-gate job in `.github/workflows/ci.yml`.
apps/docs/docs/advanced/command-line/development/index.mdx
+7 -5
View File
@@ -1,11 +1,13 @@
# Developer Docker CLI
The host-side developer CLI builds and runs local Homarr images and pull-request previews. It is installed from a Homarr checkout with `pnpm dev:setup` and is separate from the recovery CLI included in production images.
The host-side developer CLI builds and runs local Homarr images and pull-request previews. Run it directly from a checkout with `pnpm dev:cli -- ...`; no shell-specific setup script is required. It is separate from the recovery CLI included in production images.
To install an optional `homarr` binary, run `pnpm dev:cli:install` and make your Go bin directory available on `PATH`.
## Browse development images
```bash
homarr dev
pnpm dev:cli -- dev
```
The interactive browser combines local `homarr:*` images with open pull requests and their GHCR preview status. Select an image to start or stop it, use `R` to rebuild a local image, or use `p` to pull a remote preview.
@@ -13,8 +15,8 @@ The interactive browser combines local `homarr:*` images with open pull requests
## Build images
```bash
homarr build <name>
homarr build --pr <number> [name]
pnpm dev:cli -- build <name>
pnpm dev:cli -- build --pr <number> [name]
```
The first command builds the current checkout as `homarr:<name>`. The pull-request form clones the requested branch into a temporary directory and defaults to `homarr:pr-<number>` when `name` is omitted.
@@ -22,7 +24,7 @@ The first command builds the current checkout as `homarr:<name>`. The pull-reque
## Rebuild images
```bash
homarr rebuild <name>
pnpm dev:cli -- rebuild <name>
```
Images built by this CLI record their source checkout, revision, and optional pull-request number. Rebuild uses that provenance to select the original checkout or create a fresh temporary pull-request checkout.
apps/docs/docs/advanced/development/getting-started.mdx
+20 -13
View File
@@ -16,11 +16,10 @@ This guide will help you set up your development environment to start contributi
- **Node.js (lts)**: You can download it from the [official website](https://nodejs.org/).
- **pnpm (latest)**: You can install it by running `npm install -g pnpm`.
- **Go 1.25+**: You can download it from the [official website](https://go.dev/).
- **Git**: You can download it from the [official website](https://git-scm.com/).
- **GitHub CLI**: Install it from the [official website](https://cli.github.com/), then authenticate with `gh auth login`.
- **Docker or Docker Desktop**: You can download it from the [official website](https://www.docker.com/).
- **A GitHub account**: You can create one on the [official website](https://github.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`.
### Setting up the project
@@ -34,24 +33,32 @@ This guide will help you set up your development environment to start contributi
3. Change directory to the project folder with `cd homarr`.
4. Set up the project with `pnpm dev:setup`. This installs dependencies, starts Redis, creates and migrates a local SQLite database, and installs the `homarr` developer CLI.
4. Install the dependencies with `pnpm install`.
5. Start the development server with `pnpm dev` and wait for a message that says `✓ Ready in 10.7s`
5. Create `.env` from `.env.example`. In a POSIX shell, run `cp .env.example .env`; in PowerShell, run `Copy-Item .env.example .env`. Set `DB_URL` to an absolute path for your SQLite file.
6. Open your browser and navigate to [http://localhost:3000](http://localhost:3000). (Loading the page might take up to 2 minutes the first time)
6. Start Redis in the background with `pnpm docker:dev:up` if your development workflow needs it.
7. Create or update the database with `pnpm db:migration:sqlite:run`. This also seeds the default data. To run the seed explicitly later, use `pnpm db:seed`.
8. Start the development server with `pnpm dev` and wait for a message that says `✓ Ready in 10.7s`
9. Open your browser and navigate to [http://localhost:3000](http://localhost:3000). (Loading the page might take up to 2 minutes the first time)
### Useful npm scripts
#### During development
- `pnpm dev`: Start the development server.
- `pnpm dev:setup`: Set up dependencies, services, database, and developer CLI.
- `homarr dev`: Browse and run local images and remote pull-request images.
- `homarr build <name>`: Build the current checkout as `homarr:<name>`.
- `homarr build --pr <number>`: Build a pull request locally from a temporary checkout.
- `homarr rebuild <name>`: Rebuild a local image from its recorded checkout or pull request.
- `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 locally from a temporary checkout.
- `pnpm dev:cli -- rebuild <name>`: Rebuild a local image from its recorded checkout or pull request.
- `pnpm dev:cli:install`: Optionally install the developer CLI as a `homarr` binary.
- `pnpm cli`: Run cli commands.
- `pnpm db:migration:sqlite:run`: Run the migrations to create or update the sqlite db file.
- `pnpm db:seed`: Explicitly seed the default database data.
- `pnpm docker:dev:up`: Start the Redis development service in the background.
- `pnpm db:migration:sqlite:generate`: Generate a new migration file for the sqlite db. Also works with `mysql`.
- `pnpm db:studio`: Open a visual studio for the database.
- `pnpm package:new`: Create a new package in the monorepo.
@@ -66,5 +73,5 @@ This guide will help you set up your development environment to start contributi
#### Building the project
- `pnpm build`: Build the project for production.
- `homarr build <name>`: Build a `homarr:<name>` image and record its checkout for later rebuilds.
- `pnpm dev:cli -- build <name>`: Build a `homarr:<name>` image and record its checkout for later rebuilds.
- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:<name>`: Run the created docker image.
package.json
+4 -1
View File
@@ -17,12 +17,15 @@
"db:migration:postgresql:run": "pnpm -F db migration:postgresql:run",
"db:migration:sqlite:generate": "pnpm -F db migration:sqlite:generate",
"db:migration:sqlite:run": "pnpm -F db migration:sqlite:run",
"db:seed": "pnpm -F db seed",
"db:push": "pnpm -F db push:sqlite",
"db:studio": "pnpm -F db studio",
"dev": "pnpm -F nextjs dev",
"dev:cli": "go -C tools/homarr-dev run .",
"dev:cli:install": "go -C tools/homarr-dev install .",
"dev:docs": "pnpm -F @homarr/docs dev",
"dev:setup": "bash scripts/setup-dev.sh",
"docker:dev": "docker compose -f ./development/development.docker-compose.yml up",
"docker:dev:up": "docker compose -f ./development/development.docker-compose.yml up -d redis",
"format": "turbo format --continue -- --check",
"format:fix": "turbo format --continue",
"lint": "turbo lint --continue",
scripts/setup-dev.sh
-75
View File
@@ -1,75 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
repository_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
for command in corepack go docker gh; do
if ! command -v "$command" >/dev/null 2>&1; then
printf 'Required command not found: %s\n' "$command" >&2
exit 1
fi
done
if ! docker compose version >/dev/null 2>&1; then
printf 'Required command not found: docker compose\n' >&2
exit 1
fi
if ! docker info >/dev/null 2>&1; then
printf 'Docker daemon is not available.\n' >&2
exit 1
fi
if ! gh auth status >/dev/null 2>&1; then
printf 'GitHub CLI is not authenticated. Run `gh auth login`.\n' >&2
exit 1
fi
if [ ! -f "$repository_root/.env" ]; then
database_directory="$HOME/.local/share/homarr"
database_path="$database_directory/dev.sqlite"
mkdir -p "$database_directory"
while IFS= read -r line || [ -n "$line" ]; do
printf '%s\n' "${line/FULL_PATH_TO_YOUR_SQLITE_DB_FILE/$database_path}"
done < "$repository_root/.env.example" > "$repository_root/.env"
fi
corepack enable pnpm
pnpm --dir "$repository_root" install
compose_file="$repository_root/development/development.docker-compose.yml"
redis_id="$(docker compose -f "$compose_file" ps -q redis)"
if [ -n "$redis_id" ] && [ "$(docker inspect --format '{{.State.Running}}' "$redis_id")" = "true" ] && [ "$(docker compose -f "$compose_file" exec -T redis redis-cli ping)" = "PONG" ]; then
printf 'Redis is already available on port 6379.\n'
else
docker compose -f "$compose_file" up -d --no-recreate redis
for _ in {1..30}; do
if [ "$(docker compose -f "$compose_file" exec -T redis redis-cli ping 2>/dev/null)" = "PONG" ]; then
break
fi
sleep 1
done
if [ "$(docker compose -f "$compose_file" exec -T redis redis-cli ping 2>/dev/null)" != "PONG" ]; then
printf 'Redis did not become ready.\n' >&2
exit 1
fi
fi
pnpm --dir "$repository_root" db:migration:sqlite:run
mkdir -p "$HOME/.local/bin"
(
cd "$repository_root/tools/homarr-dev"
go build -trimpath -o "$HOME/.local/bin/homarr" .
)
if [ "$(uname -s)" = "Darwin" ]; then
codesign --sign - --force "$HOME/.local/bin/homarr"
fi
if [ -d "$HOME/.config/fish/completions" ]; then
"$HOME/.local/bin/homarr" completion fish > "$HOME/.config/fish/completions/homarr.fish"
fi
cli_command="$HOME/.local/bin/homarr"
case ":$PATH:" in
*":$HOME/.local/bin:"*) cli_command="homarr" ;;
*) printf 'Add %s to PATH to run `homarr` directly.\n' "$HOME/.local/bin" ;;
esac
printf 'Development environment ready. Run `%s dev` or `pnpm dev`.\n' "$cli_command"
tools/homarr-dev/README.md
+14 -10
View File
@@ -11,17 +11,19 @@ Build and launch local Homarr images and GHCR pull-request builds, then manage t
## Setup
```sh
pnpm dev:setup
pnpm install
pnpm db:migration:sqlite:run
```
This installs monorepo dependencies, creates and migrates the local SQLite database, starts or reuses Redis, installs `homarr` to `~/.local/bin`, and generates Fish completions when Fish is configured. Add `~/.local/bin` to `PATH` to invoke `homarr` directly; setup prints the absolute command when it is not available on `PATH`.
The migration command also seeds a new database. Use `pnpm db:seed` explicitly when you need to reseed an existing database. Start Redis separately with `pnpm docker:dev:up` when it is needed.
The examples below use `pnpm dev:cli -- ...`, which works from POSIX shells and PowerShell. If you prefer a global command, install it with `pnpm dev:cli:install` and add your Go bin directory to `PATH`.
## Build
```sh
homarr build feature
homarr build --pr 6441
homarr rebuild feature
pnpm dev:cli -- build feature
pnpm dev:cli -- build --pr 6441
pnpm dev:cli -- rebuild feature
```
Checkout builds are tagged as `homarr:<name>`. The source checkout and revision are recorded on the image so `homarr rebuild` and the development dashboard can rebuild it later. PR builds use a temporary checkout and default to `homarr:pr-<number>`.
@@ -29,16 +31,18 @@ Checkout builds are tagged as `homarr:<name>`. The source checkout and revision
## Launch
```sh
homarr run dev
homarr run --detach dev
homarr run --pr 6441
homarr run --pr 6441 --demo
homarr run --env FOO=bar --env FEATURE=true dev
pnpm dev:cli -- run dev
pnpm dev:cli -- run --detach dev
pnpm dev:cli -- run --pr 6441
pnpm dev:cli -- run --pr 6441 --demo
pnpm dev:cli -- run --env FOO=bar --env FEATURE=true dev
```
PR launches always pull the latest GHCR tag before starting. Local tags remain local.
The first launch generates a per-user encryption key in the OS config directory and reuses it for later launches. Set `HOMARR_DEV_SECRET_ENCRYPTION_KEY` to a 64-character hexadecimal key to override it.
The command reference below assumes the optional `homarr` installation. Without it, prefix each command with `pnpm dev:cli --` (for example, `pnpm dev:cli -- dev`).
## Commands
```text