feat(dev): add Docker development CLI (#6495)

This commit is contained in:
Thomas authored and GitHub committed 2026-08-03 14:38:56 +02:00
1 parent d58a47b776
commit 018f84f80d
27 files changed
+4048 -7

No files matched your search

+105
View File
@@ -0,0 +1,105 @@
package run
import (
"context"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/docker"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/gh"
)
func BuildCurrentImage(tag, directory string) error {
return buildCurrentImage(context.Background(), tag, directory, os.Stdout, os.Stderr)
}
func buildCurrentImage(ctx context.Context, tag, directory string, stdout, stderr io.Writer) error {
root, revision, err := checkoutDetails(ctx, directory)
if err != nil {
return err
}
return docker.BuildContext(ctx, docker.BuildOptions{Context: root, Tag: tag, Source: root, Revision: revision}, stdout, stderr)
}
func BuildPRImage(number int, tag string) error {
return buildPRImage(context.Background(), number, tag, os.Stdout, os.Stderr)
}
func buildPRImage(ctx context.Context, number int, tag string, stdout, stderr io.Writer) error {
if number <= 0 {
return fmt.Errorf("PR number must be positive")
}
temporaryRoot, err := os.MkdirTemp("", "homarr-pr-*")
if err != nil {
return fmt.Errorf("create temporary checkout: %w", err)
}
defer os.RemoveAll(temporaryRoot)
checkout := filepath.Join(temporaryRoot, "homarr")
clone := exec.CommandContext(ctx, "gh", prCloneArgs(checkout)...)
clone.Stdout = stdout
clone.Stderr = stderr
if err := clone.Run(); err != nil {
return fmt.Errorf("clone %s: %w", gh.Repo, err)
}
command := exec.CommandContext(ctx, "gh", "pr", "checkout", strconv.Itoa(number), "--detach")
command.Dir = checkout
command.Stdout = stdout
command.Stderr = stderr
if err := command.Run(); err != nil {
return fmt.Errorf("checkout PR #%d: %w", number, err)
}
_, revision, err := checkoutDetails(ctx, checkout)
if err != nil {
return err
}
return docker.BuildContext(ctx, docker.BuildOptions{
Context: checkout,
Tag: tag,
Source: fmt.Sprintf("https://github.com/%s/pull/%d", gh.Repo, number),
Revision: revision,
PRNumber: number,
}, stdout, stderr)
}
func prCloneArgs(checkout string) []string {
return []string{"repo", "clone", gh.Repo, checkout, "--", "--depth=1", "--filter=blob:none"}
}
func RebuildImage(image docker.Image) error {
return RebuildImageContext(context.Background(), image, os.Stdout, os.Stderr)
}
func RebuildImageContext(ctx context.Context, image docker.Image, stdout, stderr io.Writer) error {
if image.PRNumber > 0 {
return buildPRImage(ctx, image.PRNumber, image.Tag, stdout, stderr)
}
if image.Source == "" {
return fmt.Errorf("homarr:%s has no build source metadata", image.Tag)
}
if info, err := os.Stat(image.Source); err != nil || !info.IsDir() {
return fmt.Errorf("build source %s is no longer available", image.Source)
}
return buildCurrentImage(ctx, image.Tag, image.Source, stdout, stderr)
}
func checkoutDetails(ctx context.Context, directory string) (root string, revision string, err error) {
rootOutput, err := exec.CommandContext(ctx, "git", "-C", directory, "rev-parse", "--show-toplevel").CombinedOutput()
if err != nil {
return "", "", fmt.Errorf("find Homarr checkout: %w: %s", err, strings.TrimSpace(string(rootOutput)))
}
root = strings.TrimSpace(string(rootOutput))
if _, err := os.Stat(filepath.Join(root, "Dockerfile")); err != nil {
return "", "", fmt.Errorf("%s is not a Homarr checkout", root)
}
revisionOutput, err := exec.CommandContext(ctx, "git", "-C", root, "rev-parse", "HEAD").CombinedOutput()
if err != nil {
return "", "", fmt.Errorf("read checkout revision: %w: %s", err, strings.TrimSpace(string(revisionOutput)))
}
return root, strings.TrimSpace(string(revisionOutput)), nil
}
+119
View File
@@ -0,0 +1,119 @@
package run
import (
"context"
"fmt"
"os"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/docker"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/gh"
)
type Options struct {
Context context.Context
PR int
Tag string
Demo bool
Env []string
FetchTitle bool
FindPort func(int) int
}
type Plan struct {
Image string
Name string
Volume string
Label string
HostPort int
Env []string
Platform string
Pull bool
PRNumber int
}
func BuildPlan(opts Options) (*Plan, error) {
p := &Plan{}
ctx := opts.Context
if ctx == nil {
ctx = context.Background()
}
findPort := opts.FindPort
if findPort == nil {
findPort = docker.FindFreePort
}
if opts.PR > 0 {
p.PRNumber = opts.PR
p.Image = fmt.Sprintf("ghcr.io/homarr-labs/homarr-test:pr-%d", opts.PR)
p.Name = fmt.Sprintf("homarr_pr_%d", opts.PR)
p.Volume = fmt.Sprintf("homarr_pr_%d_data", opts.PR)
p.Label = fmt.Sprintf("PR #%d", opts.PR)
p.Pull = true
p.Platform = "linux/amd64"
if opts.FetchTitle {
if pr, err := gh.GetPR(ctx, opts.PR); err == nil && pr.Title != "" {
p.Label = fmt.Sprintf("PR #%d — %s", opts.PR, pr.Title)
}
}
} else if opts.Tag != "" {
p.Image = "homarr:" + opts.Tag
p.Name = "homarr_" + opts.Tag
p.Volume = "homarr_" + opts.Tag + "_data"
p.Label = "tag: " + opts.Tag
} else {
return nil, fmt.Errorf("need a tag or --pr")
}
p.HostPort = findPort(7575)
if p.HostPort == 0 {
return nil, fmt.Errorf("no free host port is available")
}
p.Env = append(p.Env, opts.Env...)
if opts.Demo {
p.Env = append(p.Env, "DEMO_MODE=true", "UNSAFE_ENABLE_MOCK_INTEGRATION=true")
p.Label += " (demo)"
}
return p, nil
}
func StartDetached(p *Plan) error {
return start(p, true)
}
func StartForeground(p *Plan) error {
return start(p, false)
}
func start(p *Plan, daemon bool) error {
const attempts = 5
for attempt := 0; attempt < attempts; attempt++ {
err := docker.Start(docker.StartOptions{
Name: p.Name,
Image: p.Image,
Volume: p.Volume,
HostPort: p.HostPort,
Env: p.Env,
Platform: p.Platform,
PullAlways: p.Pull && attempt == 0,
Daemon: daemon,
})
if err == nil {
return nil
}
if !docker.IsPortConflict(err) || attempt == attempts-1 {
if docker.IsPortConflict(err) {
return fmt.Errorf("unable to bind a host port after %d attempts; restart Docker or OrbStack: %w", attempts, err)
}
return err
}
previousPort := p.HostPort
p.HostPort = docker.FindFreePort(p.HostPort + 1)
if p.HostPort == 0 {
return fmt.Errorf("no free host port is available: %w", err)
}
if !daemon {
fmt.Fprintf(os.Stderr, "Port %d unavailable; retrying on %d.\n", previousPort, p.HostPort)
}
}
return nil
}
+59
View File
@@ -0,0 +1,59 @@
package run
import (
"os"
"slices"
"strconv"
"testing"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/docker"
)
func TestPRPlanUsesAMD64(t *testing.T) {
plan, err := BuildPlan(Options{PR: 1, FindPort: func(int) int { return 7575 }})
if err != nil {
t.Fatal(err)
}
if plan.Platform != "linux/amd64" {
t.Fatalf("platform = %q, want linux/amd64", plan.Platform)
}
}
func TestPRCloneIsShallow(t *testing.T) {
args := prCloneArgs("/tmp/checkout")
if !slices.Contains(args, "--depth=1") || !slices.Contains(args, "--filter=blob:none") {
t.Fatalf("clone args = %v", args)
}
}
func TestBuildPlanFailsWhenNoPortIsAvailable(t *testing.T) {
_, err := BuildPlan(Options{Tag: "dev", FindPort: func(int) int { return 0 }})
if err == nil {
t.Fatal("expected no-free-port error")
}
}
func TestStartPRIntegration(t *testing.T) {
if os.Getenv("HOMARR_DOCKER_INTEGRATION_TEST") != "1" {
t.Skip("set HOMARR_DOCKER_INTEGRATION_TEST=1 and HOMARR_TEST_PR=<number>")
}
pr, err := strconv.Atoi(os.Getenv("HOMARR_TEST_PR"))
if err != nil || pr <= 0 {
t.Fatal("HOMARR_TEST_PR must be a positive PR number")
}
plan, err := BuildPlan(Options{PR: pr})
if err != nil {
t.Fatal(err)
}
plan.Name += "_integration"
plan.Volume += "_integration"
defer docker.Remove(plan.Name)
if err := StartDetached(plan); err != nil {
t.Fatal(err)
}
if !docker.IsRunning(plan.Name) {
t.Fatalf("container %s did not remain running", plan.Name)
}
}