From 5b04ed1ab5121003203be887bdd342a81b4d360d Mon Sep 17 00:00:00 2001 From: Thomas Camlong Date: Fri, 31 Jul 2026 23:52:14 +0200 Subject: [PATCH] refactor(dev): make setup explicit and portable --- .github/workflows/ci.yml | 10 --- AGENTS.md | 11 +-- .../command-line/development/index.mdx | 12 +-- .../advanced/development/getting-started.mdx | 33 ++++---- package.json | 5 +- scripts/setup-dev.sh | 75 ------------------- tools/homarr-dev/README.md | 24 +++--- 7 files changed, 51 insertions(+), 119 deletions(-) delete mode 100755 scripts/setup-dev.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index afde5781d..dcbb352c3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 2dd902685..6c3d36da4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 ` from a Homarr checkout to build `homarr:` with rebuild provenance. -- Run `homarr build --pr ` 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 ` from a Homarr checkout to build `homarr:` with rebuild provenance. +- Run `pnpm dev:cli -- build --pr ` 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`. diff --git a/apps/docs/docs/advanced/command-line/development/index.mdx b/apps/docs/docs/advanced/command-line/development/index.mdx index f4b25b67e..aa1d3c644 100644 --- a/apps/docs/docs/advanced/command-line/development/index.mdx +++ b/apps/docs/docs/advanced/command-line/development/index.mdx @@ -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 -homarr build --pr [name] +pnpm dev:cli -- build +pnpm dev:cli -- build --pr [name] ``` The first command builds the current checkout as `homarr:`. The pull-request form clones the requested branch into a temporary directory and defaults to `homarr:pr-` when `name` is omitted. @@ -22,7 +24,7 @@ The first command builds the current checkout as `homarr:`. The pull-reque ## Rebuild images ```bash -homarr rebuild +pnpm dev:cli -- rebuild ``` 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. diff --git a/apps/docs/docs/advanced/development/getting-started.mdx b/apps/docs/docs/advanced/development/getting-started.mdx index 9a1f8546b..e8f68ea6d 100644 --- a/apps/docs/docs/advanced/development/getting-started.mdx +++ b/apps/docs/docs/advanced/development/getting-started.mdx @@ -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 `: Build the current checkout as `homarr:`. -- `homarr build --pr `: Build a pull request locally from a temporary checkout. -- `homarr rebuild `: 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 `: Build the current checkout as `homarr:`. +- `pnpm dev:cli -- build --pr `: Build a pull request locally from a temporary checkout. +- `pnpm dev:cli -- rebuild `: 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 `: Build a `homarr:` image and record its checkout for later rebuilds. +- `pnpm dev:cli -- build `: Build a `homarr:` image and record its checkout for later rebuilds. - `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:`: Run the created docker image. diff --git a/package.json b/package.json index 76e61b0cb..e49e3d8cb 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/scripts/setup-dev.sh b/scripts/setup-dev.sh deleted file mode 100755 index c89243f70..000000000 --- a/scripts/setup-dev.sh +++ /dev/null @@ -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" diff --git a/tools/homarr-dev/README.md b/tools/homarr-dev/README.md index b9e74a2d3..5c120f535 100644 --- a/tools/homarr-dev/README.md +++ b/tools/homarr-dev/README.md @@ -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:`. 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-`. @@ -29,16 +31,18 @@ Checkout builds are tagged as `homarr:`. 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