From f65cfcb2e7bbe11daba4f1818fd253c98cecdb45 Mon Sep 17 00:00:00 2001 From: Teg79 Date: Mon, 16 Nov 2026 19:38:33 +0100 Subject: [PATCH 1/3] feat(cli): urbex version urbex version (and --output json), urbex --version, and the version at the top of urbex doctor. A release sets it with -ldflags -X; a build from source says dev and the commit Go embedded. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0182yxsfwRowwnxCfgrQwjnA --- docs/layout.md | 1 + internal/cli/doctor.go | 8 ++- internal/cli/root.go | 6 ++ internal/cli/version.go | 32 +++++++++++ internal/cli/version_test.go | 41 ++++++++++++++ internal/doctor/doctor.go | 7 ++- internal/version/version.go | 94 ++++++++++++++++++++++++++++++++ internal/version/version_test.go | 55 +++++++++++++++++++ 8 files changed, 240 insertions(+), 4 deletions(-) create mode 100644 internal/cli/version.go create mode 100644 internal/cli/version_test.go create mode 100644 internal/version/version.go create mode 100644 internal/version/version_test.go diff --git a/docs/layout.md b/docs/layout.md index f8a9bca..eca754c 100644 --- a/docs/layout.md +++ b/docs/layout.md @@ -34,6 +34,7 @@ internal/keycloak/ minimal Keycloak admin API client (realms, clients, internal/technitium/ minimal Technitium API client (the internal zone and its A records) internal/links/ linked applications: what each `provides`/`uses` yields, `${app.key}` references internal/progress/ the record `bootstrap` and `apply` write and `urbex status --progress` reads +internal/version/ the binary's version, commit and build date (`urbex version`, set with -ldflags -X) platform/terraform/ embedded Terraform modules (modules/lxc, base/, project/) platform/ansible/ embedded Ansible playbooks/roles (base services + Periphery for project LXCs) platform/dockerfiles/ embedded Dockerfiles for the go/java/python runtimes and web frontends diff --git a/internal/cli/doctor.go b/internal/cli/doctor.go index 26b499e..2582353 100644 --- a/internal/cli/doctor.go +++ b/internal/cli/doctor.go @@ -13,6 +13,7 @@ import ( "github.com/urbforge/urbex-cli/internal/doctor" "github.com/urbforge/urbex-cli/internal/platform" "github.com/urbforge/urbex-cli/internal/proxmoxapi" + "github.com/urbforge/urbex-cli/internal/version" ) // errDoctorFailed makes urbex doctor exit non-zero when a check failed; @@ -33,7 +34,7 @@ Proxmox token, the node (the API answers, the node, pool, storage, LXC template and bridge exist, the token has the privileges urbex needs); and, with Cloudflare in the config, the token and the zone. -Each check is ok, warn, fail or skip, with what to do when it isn't ok. It +It starts with urbex's own version. Each check is ok, warn, fail or skip, with what to do when it isn't ok. It exits non-zero when a check failed. It changes nothing, and prints no secret. --output json prints the report as one JSON document. See docs/reference/cli.md in urbforge/urbex.`, @@ -41,7 +42,7 @@ docs/reference/cli.md in urbforge/urbex.`, RunE: func(cmd *cobra.Command, args []string) error { ctx := cmd.Context() sys := doctor.LocalSystem() - r := &doctor.Report{} + r := &doctor.Report{Version: version.Get().String()} doctor.Tools(ctx, sys, r) ws := doctor.Workspace{} @@ -101,6 +102,9 @@ docs/reference/cli.md in urbforge/urbex.`, // printDoctor prints the report, a group at a time, with the fix under // each check that isn't ok. func printDoctor(out io.Writer, r *doctor.Report) { + if r.Version != "" { + fmt.Fprintf(out, "%s\n\n", r.Version) + } group := "" for _, c := range r.Checks { if c.Group != group { diff --git a/internal/cli/root.go b/internal/cli/root.go index 23ca970..5e6a6e0 100644 --- a/internal/cli/root.go +++ b/internal/cli/root.go @@ -3,6 +3,8 @@ package cli import ( "github.com/spf13/cobra" + + "github.com/urbforge/urbex-cli/internal/version" ) // Execute runs the urbex root command. @@ -20,7 +22,10 @@ personal apps to staging and production on your own Proxmox server. See https://github.com/urbforge/urbex for architecture and design decisions.`, SilenceUsage: true, SilenceErrors: true, + // --version: the same line as urbex version. + Version: version.Get().String(), } + root.SetVersionTemplate("{{.Version}}\n") root.AddCommand(newInitCmd()) root.AddCommand(newBootstrapCmd()) @@ -36,6 +41,7 @@ See https://github.com/urbforge/urbex for architecture and design decisions.`, root.AddCommand(newUsersCmd()) root.AddCommand(newDoctorCmd()) root.AddCommand(newDiscoverCmd()) + root.AddCommand(newVersionCmd()) return root } diff --git a/internal/cli/version.go b/internal/cli/version.go new file mode 100644 index 0000000..9bebf7d --- /dev/null +++ b/internal/cli/version.go @@ -0,0 +1,32 @@ +package cli + +import ( + "fmt" + + "github.com/spf13/cobra" + + "github.com/urbforge/urbex-cli/internal/version" +) + +func newVersionCmd() *cobra.Command { + var output outputFlag + cmd := &cobra.Command{ + Use: "version", + Short: "Print urbex's version, commit and build date", + Long: `Prints the version of this urbex binary, the commit it was built from and +when, and the platform: say it in a bug report. A release says its +version (0.1.0); a build from source says "dev" and its commit. --output +json prints it as one JSON document. urbex --version prints the same line.`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + i := version.Get() + if output.JSON() { + return writeJSON(cmd.OutOrStdout(), i) + } + fmt.Fprintln(cmd.OutOrStdout(), i.String()) + return nil + }, + } + output.Register(cmd) + return cmd +} diff --git a/internal/cli/version_test.go b/internal/cli/version_test.go new file mode 100644 index 0000000..d5befb3 --- /dev/null +++ b/internal/cli/version_test.go @@ -0,0 +1,41 @@ +package cli + +import ( + "bytes" + "encoding/json" + "strings" + "testing" + + "github.com/urbforge/urbex-cli/internal/version" +) + +func runRoot(t *testing.T, args ...string) string { + t.Helper() + root := newRootCmd() + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatalf("urbex %s: %v", strings.Join(args, " "), err) + } + return out.String() +} + +// urbex version and urbex --version print the same line; -o json the fields. +func TestVersionCmd(t *testing.T) { + want := version.Get().String() + "\n" + if got := runRoot(t, "version"); got != want { + t.Errorf("urbex version = %q, want %q", got, want) + } + if got := runRoot(t, "--version"); got != want { + t.Errorf("urbex --version = %q, want %q", got, want) + } + var i version.Info + if err := json.Unmarshal([]byte(runRoot(t, "version", "-o", "json")), &i); err != nil { + t.Fatal(err) + } + if i.Version != version.Get().Version || i.Go == "" || i.Platform == "" { + t.Errorf("json = %+v", i) + } +} diff --git a/internal/doctor/doctor.go b/internal/doctor/doctor.go index 7591174..f8b4d96 100644 --- a/internal/doctor/doctor.go +++ b/internal/doctor/doctor.go @@ -34,8 +34,11 @@ type Check struct { // Report is every check, in order. type Report struct { - Checks []Check `json:"checks"` - OK bool `json:"ok"` // no check failed + // Version is the urbex binary's, as `urbex version` prints it: a bug + // report with the doctor's output says which build it came from. + Version string `json:"version,omitempty"` + Checks []Check `json:"checks"` + OK bool `json:"ok"` // no check failed } func (r *Report) add(c Check) { diff --git a/internal/version/version.go b/internal/version/version.go new file mode 100644 index 0000000..5f2942e --- /dev/null +++ b/internal/version/version.go @@ -0,0 +1,94 @@ +// Package version is the urbex binary's version, so that a bug report can +// say which build it came from. +// +// A release build sets Version, Commit and Date with -ldflags -X, e.g. +// +// go build -ldflags "-X github.com/urbforge/urbex-cli/internal/version.Version=0.1.0 \ +// -X github.com/urbforge/urbex-cli/internal/version.Commit=$(git rev-parse HEAD) \ +// -X github.com/urbforge/urbex-cli/internal/version.Date=$(date -u +%FT%TZ)" ./cmd/urbex +// +// A plain `go build` leaves Version "dev" and takes the commit, its date +// and whether the tree had changes from what Go embeds in the binary (debug.ReadBuildInfo). +package version + +import ( + "fmt" + "runtime" + "runtime/debug" + "strings" +) + +// Set at build time with -ldflags -X. +var ( + Version = "dev" + Commit = "" + Date = "" +) + +// Info is what `urbex version` prints. +type Info struct { + Version string `json:"version"` + Commit string `json:"commit,omitempty"` + Date string `json:"date,omitempty"` // build date, set by a release build + CommitDate string `json:"commit_date,omitempty"` // a build from source: the commit's date + Modified bool `json:"modified,omitempty"` // built from a tree with uncommitted changes + Go string `json:"go"` + Platform string `json:"platform"` +} + +// Get returns this binary's Info. +func Get() Info { + bi, _ := debug.ReadBuildInfo() + return get(bi) +} + +func get(bi *debug.BuildInfo) Info { + i := Info{ + Version: strings.TrimPrefix(Version, "v"), + Commit: Commit, + Date: Date, + Go: runtime.Version(), + Platform: runtime.GOOS + "/" + runtime.GOARCH, + } + if i.Commit != "" || bi == nil { + return i + } + for _, s := range bi.Settings { + switch s.Key { + case "vcs.revision": + i.Commit = s.Value + case "vcs.time": + i.CommitDate = s.Value + case "vcs.modified": + i.Modified = s.Value == "true" + } + } + return i +} + +// ShortCommit is the commit's first 7 characters. +func (i Info) ShortCommit() string { + if len(i.Commit) > 7 { + return i.Commit[:7] + } + return i.Commit +} + +// String is one line: "urbex 0.1.0 (commit 1a2b3c4, built 2026-11-16T10:00:00Z, linux/amd64)", +// or from source "urbex dev (commit 1a2b3c4-dirty, committed 2026-11-15T09:00:00Z, linux/amd64)". +func (i Info) String() string { + var parts []string + if c := i.ShortCommit(); c != "" { + if i.Modified { + c += "-dirty" + } + parts = append(parts, "commit "+c) + } + if i.Date != "" { + parts = append(parts, "built "+i.Date) + } else if i.CommitDate != "" { + parts = append(parts, "committed "+i.CommitDate) + } + parts = append(parts, i.Platform) + return fmt.Sprintf("urbex %s (%s)", i.Version, strings.Join(parts, ", ")) +} diff --git a/internal/version/version_test.go b/internal/version/version_test.go new file mode 100644 index 0000000..7f25f49 --- /dev/null +++ b/internal/version/version_test.go @@ -0,0 +1,55 @@ +package version + +import ( + "runtime/debug" + "strings" + "testing" +) + +func withVars(t *testing.T, v, c, d string) { + t.Helper() + ov, oc, od := Version, Commit, Date + Version, Commit, Date = v, c, d + t.Cleanup(func() { Version, Commit, Date = ov, oc, od }) +} + +func TestGet_ReleaseBuild(t *testing.T) { + withVars(t, "v0.1.0", "1a2b3c4d5e6f7a8b9c0d", "2026-11-16T10:00:00Z") + // What ldflags set wins over what Go embedded. + bi := &debug.BuildInfo{Settings: []debug.BuildSetting{{Key: "vcs.revision", Value: "ffffffff"}}} + i := get(bi) + if i.Version != "0.1.0" || i.Commit != "1a2b3c4d5e6f7a8b9c0d" || i.Date != "2026-11-16T10:00:00Z" { + t.Fatalf("got %+v", i) + } + s := i.String() + if !strings.HasPrefix(s, "urbex 0.1.0 (commit 1a2b3c4, built 2026-11-16T10:00:00Z, ") { + t.Errorf("String() = %q", s) + } +} + +func TestGet_LocalBuild(t *testing.T) { + withVars(t, "dev", "", "") + bi := &debug.BuildInfo{Settings: []debug.BuildSetting{ + {Key: "vcs.revision", Value: "abcdef0123456789"}, + {Key: "vcs.time", Value: "2026-11-15T09:00:00Z"}, + {Key: "vcs.modified", Value: "true"}, + }} + i := get(bi) + if i.Version != "dev" || i.Commit != "abcdef0123456789" || !i.Modified || i.Date != "" || i.CommitDate != "2026-11-15T09:00:00Z" { + t.Fatalf("got %+v", i) + } + if s := i.String(); !strings.HasPrefix(s, "urbex dev (commit abcdef0-dirty, committed 2026-11-15T09:00:00Z, ") { + t.Errorf("String() = %q", s) + } +} + +func TestGet_NoBuildInfo(t *testing.T) { + withVars(t, "dev", "", "") + i := get(nil) + if i.Commit != "" || i.Go == "" || i.Platform == "" { + t.Fatalf("got %+v", i) + } + if s := i.String(); !strings.HasPrefix(s, "urbex dev (") { + t.Errorf("String() = %q", s) + } +} From a85a781a4e42a7c224e29c6c8ea661f8087e46af Mon Sep 17 00:00:00 2001 From: Teg79 Date: Mon, 16 Nov 2026 19:48:40 +0100 Subject: [PATCH 2/3] build(release): binaries with GoReleaser on a version tag Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0182yxsfwRowwnxCfgrQwjnA --- .github/workflows/release.yml | 66 +++++++++++++++++++++++++++++ .gitignore | 1 + .goreleaser.yaml | 80 +++++++++++++++++++++++++++++++++++ README.md | 9 ++++ mise.toml | 6 +++ 5 files changed, 162 insertions(+) create mode 100644 .github/workflows/release.yml create mode 100644 .goreleaser.yaml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..40a2c15 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,66 @@ +# The release: on a v* tag (pushed by Teg - a tag publishes), the tests, +# then GoReleaser (.goreleaser.yaml) builds the binaries and archives and +# drafts the GitHub release, then the release is published: as a +# pre-release while urbex is 0.x or the tag has a suffix (v0.1.0-rc.1). +name: release + +on: + push: + tags: ["v*"] + +permissions: + contents: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + test: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: jdx/mise-action@236a21c3b91f5db6d4e174b348674a0f0caac06d # v5.2.9 + with: + install_args: go deno + - run: mise run lint + - run: mise run test + + release: + needs: test + if: github.repository == 'urbforge/urbex-cli' + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: write # the release and its assets + id-token: write # build provenance + attestations: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 # the changelog since the previous tag + persist-credentials: false + - uses: jdx/mise-action@236a21c3b91f5db6d4e174b348674a0f0caac06d # v5.2.9 + with: + install_args: go goreleaser + - name: Build and draft the release + run: goreleaser release --clean + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Build provenance of the archives + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-path: dist/*.tar.gz + - name: Publish the release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG: ${{ github.ref_name }} + run: | + case "$TAG" in + v0.* | *-*) pre=true ;; + *) pre=false ;; + esac + gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --draft=false --prerelease="$pre" diff --git a/.gitignore b/.gitignore index e6d76fb..02010ac 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ .DS_Store /e2e/.work/ /mise.local.toml +/dist/ diff --git a/.goreleaser.yaml b/.goreleaser.yaml new file mode 100644 index 0000000..7e26630 --- /dev/null +++ b/.goreleaser.yaml @@ -0,0 +1,80 @@ +# The release of urbex: on a v* tag, .github/workflows/release.yml runs +# this, and publishes the GitHub release it drafts. Try it locally, with +# nothing published: mise run release-snapshot (binaries and archives in +# dist/). +version: 2 + +project_name: urbex + +builds: + - id: urbex + main: ./cmd/urbex + binary: urbex + env: + - CGO_ENABLED=0 + goos: [linux, darwin] + goarch: [amd64, arm64] + flags: + - -trimpath + # The version urbex version prints (internal/version). + ldflags: + - -s -w + - -X github.com/urbforge/urbex-cli/internal/version.Version={{ .Version }} + - -X github.com/urbforge/urbex-cli/internal/version.Commit={{ .FullCommit }} + - -X github.com/urbforge/urbex-cli/internal/version.Date={{ .Date }} + mod_timestamp: "{{ .CommitTimestamp }}" + +archives: + - id: urbex + formats: [tar.gz] + name_template: "urbex_{{ .Version }}_{{ .Os }}_{{ .Arch }}" + files: + - LICENSE + - README.md + +checksum: + name_template: checksums.txt + +snapshot: + version_template: "{{ incpatch .Version }}-snapshot+{{ .ShortCommit }}" + +changelog: + sort: asc + use: github + # The commit and its title: no author, so no email address. + abbrev: 7 + format: "{{ .SHA }} {{ .Message }}" + groups: + - title: Features + regexp: '^.*?feat(\(.+\))??!?:.+$' + order: 0 + - title: Fixes + regexp: '^.*?fix(\(.+\))??!?:.+$' + order: 1 + - title: Performance + regexp: '^.*?perf(\(.+\))??!?:.+$' + order: 2 + - title: Others + order: 999 + filters: + exclude: + - '^.*?(test|ci|chore|style)(\(.+\))??!?:.+$' + - '^Merge ' + +release: + github: + owner: urbforge + name: urbex-cli + # Drafted: the workflow publishes it, as a pre-release while urbex is + # 0.x or the tag has a suffix (v0.1.0-rc.1). GoReleaser's own + # prerelease setting only sees the suffix. + draft: true + replace_existing_draft: true + prerelease: auto + name_template: "urbex {{ .Version }}" + header: | + urbex {{ .Version }}{{ if or (eq .Major 0) .Prerelease }} - a preview release{{ end }}. + Install: download the archive for your system below, check it against + `checksums.txt`, and put `urbex` on your `PATH`. See + [getting started](https://github.com/urbforge/urbex/blob/main/docs/getting-started.md) + and the [known limitations](https://github.com/urbforge/urbex/blob/main/docs/known-limitations.md). diff --git a/README.md b/README.md index eb96890..9faadf2 100644 --- a/README.md +++ b/README.md @@ -181,9 +181,18 @@ mise run build # ./urbex mise run test # unit tests mise run lint # go vet + gofmt check (mise run fmt formats) mise run e2e # end-to-end, needs podman - see e2e/README.md +mise run release-snapshot # the release archives in dist/, publishing nothing mise tasks # every task ``` +A release is a `v*` tag, pushed by a maintainer: +[`.github/workflows/release.yml`](.github/workflows/release.yml) runs the +tests, then [GoReleaser](https://goreleaser.com) (`.goreleaser.yaml`) +builds `urbex` for Linux and macOS (amd64, arm64), with checksums, +provenance and a changelog from the commit titles, and publishes the +GitHub release - a pre-release while urbex is 0.x or the tag has a +suffix (`v0.1.0-rc.1`). + With mise [activated in your shell](https://mise.jdx.dev/getting-started.html), `go`, `terraform`, `ansible-playbook`... are the pinned ones whenever you are in this directory; otherwise prefix commands with `mise exec --`. diff --git a/mise.toml b/mise.toml index e40018d..c2cd57f 100644 --- a/mise.toml +++ b/mise.toml @@ -19,6 +19,8 @@ uv = "0.12.23" "pipx:ansible-core" = "2.21.5" # The runtime of Komodo's Actions: tests the reconciler's logic. deno = "2.9.7" +# Builds the release binaries and archives (.goreleaser.yaml). +goreleaser = "2.19.0" [settings] # Install Python tools (ansible-core) with uv. @@ -47,6 +49,10 @@ run = [ description = "Format the code with gofmt" run = "gofmt -w cmd internal" +[tasks.release-snapshot] +description = "Build the release binaries and archives into dist/, publishing nothing" +run = "goreleaser release --snapshot --clean" + [tasks.e2e] description = "End-to-end test, needs podman (see e2e/README.md)" run = "e2e/run.sh" From 2c2266557d7ffc3b0abc6112cf408a38e9cd1f80 Mon Sep 17 00:00:00 2001 From: Teg79 Date: Mon, 16 Nov 2026 19:52:20 +0100 Subject: [PATCH 3/3] build(release): publish the urbex-op image on ghcr.io and use it by default The release workflow builds tools/operator/Containerfile's release target from GoReleaser's binaries, for linux/amd64 and linux/arm64, pushes ghcr.io/urbforge/urbex-op: (and :latest without a suffix), and attaches urbex-op set to that version. urbex-op runs its version's image and pulls it the first time; from a checkout, the image build makes, as before. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0182yxsfwRowwnxCfgrQwjnA --- .github/workflows/release.yml | 58 +++++++++++++++++++++++++++++++++-- README.md | 5 +++ tools/operator/Containerfile | 31 ++++++++++++++----- tools/operator/README.md | 26 ++++++++++++++-- tools/operator/urbex-op | 35 +++++++++++++++++++-- 5 files changed, 140 insertions(+), 15 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 40a2c15..34ee03f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,7 +1,9 @@ # The release: on a v* tag (pushed by Teg - a tag publishes), the tests, # then GoReleaser (.goreleaser.yaml) builds the binaries and archives and -# drafts the GitHub release, then the release is published: as a -# pre-release while urbex is 0.x or the tag has a suffix (v0.1.0-rc.1). +# drafts the GitHub release; the operator image is built from those +# binaries and pushed to ghcr.io/urbforge/urbex-op, urbex-op is attached +# to the release, and the release is published: as a pre-release while +# urbex is 0.x or the tag has a suffix (v0.1.0-rc.1). name: release on: @@ -36,6 +38,7 @@ jobs: timeout-minutes: 30 permissions: contents: write # the release and its assets + packages: write # the operator image on ghcr.io id-token: write # build provenance attestations: write steps: @@ -54,6 +57,57 @@ jobs: uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 with: subject-path: dist/*.tar.gz + - name: The image's context, and its tags + id: image + env: + TAG: ${{ github.ref_name }} + run: | + # //urbex, as the Containerfile's release stage reads it. + jq -r '.[] | select(.type == "Binary" and .goos == "linux") | "\(.goarch) \(.path)"' dist/artifacts.json | + while read -r arch path; do + mkdir -p "dist/image/linux/$arch" + cp "$path" "dist/image/linux/$arch/urbex" + done + cp mise.toml dist/image/ + version=${TAG#v} + tags="ghcr.io/urbforge/urbex-op:$version" + case "$TAG" in *-*) ;; *) tags="$tags,ghcr.io/urbforge/urbex-op:latest" ;; esac + echo "version=$version" >>"$GITHUB_OUTPUT" + echo "tags=$tags" >>"$GITHUB_OUTPUT" + echo "mise=$(sed -n 's/^min_version = "\(.*\)"$/\1/p' mise.toml)" >>"$GITHUB_OUTPUT" + - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0 + - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Build and push the operator image + uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + with: + context: dist/image + file: tools/operator/Containerfile + target: release + platforms: linux/amd64,linux/arm64 + build-args: MISE_VERSION=${{ steps.image.outputs.mise }} + tags: ${{ steps.image.outputs.tags }} + labels: | + org.opencontainers.image.source=https://github.com/${{ github.repository }} + org.opencontainers.image.version=${{ steps.image.outputs.version }} + org.opencontainers.image.description=urbex and the tools it runs, for urbex-op + org.opencontainers.image.licenses=Apache-2.0 + push: true + provenance: mode=max + - name: Attach urbex-op, set to this release's image + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG: ${{ github.ref_name }} + VERSION: ${{ steps.image.outputs.version }} + run: | + sed "s/^URBEX_OP_VERSION=dev\$/URBEX_OP_VERSION=$VERSION/" tools/operator/urbex-op >dist/urbex-op + grep -qx "URBEX_OP_VERSION=$VERSION" dist/urbex-op + chmod +x dist/urbex-op + gh release upload "$TAG" dist/urbex-op --repo "$GITHUB_REPOSITORY" --clobber - name: Publish the release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index 9faadf2..7208135 100644 --- a/README.md +++ b/README.md @@ -163,6 +163,11 @@ credentials, the keys, the GitOps repo and your projects. Only podman or docker is needed, on Linux or on macOS (docker with colima, or podman machine). See [`tools/operator/README.md`](tools/operator/README.md). +Each release attaches `urbex-op` and publishes its image, +`ghcr.io/urbforge/urbex-op:`, which `urbex-op` pulls the first +time: download the one file and run it. From a checkout, build the image +first: + ```sh tools/operator/urbex-op build && tools/operator/urbex-op -w ~/urbex-work init export URBEX_PROXMOX_TOKEN=... diff --git a/tools/operator/Containerfile b/tools/operator/Containerfile index 671a407..83b279f 100644 --- a/tools/operator/Containerfile +++ b/tools/operator/Containerfile @@ -1,17 +1,24 @@ -# The operator image: urbex, built from this checkout, and everything it -# shells out to - terraform, ansible-playbook, sops, age, git, ssh - at the -# versions pinned in mise.toml. Build it with `tools/operator/urbex-op -# build` (or `mise run operator-image`), which passes mise.toml's Go and -# mise versions as GO_VERSION and MISE_VERSION. -ARG GO_VERSION +# The operator image: urbex and everything it shells out to - terraform, +# ansible-playbook, sops, age, git, ssh - at the versions pinned in +# mise.toml. Two ways to build it, both passing mise.toml's Go and mise +# versions as GO_VERSION and MISE_VERSION: +# +# - from this checkout (the last stage, the default): `tools/operator/urbex-op +# build`, or `mise run operator-image`; +# - from a release's binaries (--target release): the release workflow, +# with a context holding mise.toml and //urbex for each +# platform - published as ghcr.io/urbforge/urbex-op. +ARG GO_VERSION=1 FROM docker.io/library/golang:${GO_VERSION} AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . -RUN CGO_ENABLED=0 go build -o /out/urbex ./cmd/urbex +# The commit urbex version reports: the context has no .git for Go to read. +ARG URBEX_COMMIT= +RUN CGO_ENABLED=0 go build -ldflags "-X github.com/urbforge/urbex-cli/internal/version.Commit=${URBEX_COMMIT}" -o /out/urbex ./cmd/urbex -FROM docker.io/library/debian:13-slim +FROM docker.io/library/debian:13-slim AS tools ARG MISE_VERSION # The tools, from mise.toml, linked into /usr/local/bin; mise itself and # uv are only needed to install them, and are removed in the same layer. @@ -36,4 +43,12 @@ RUN apt-get update \ && chmod +x /usr/local/bin/urbex-python \ && rm -rf /tmp/mise /tmp/mise-cache "$MISE_DATA_DIR/installs/uv" "$MISE_DATA_DIR/shims" WORKDIR / + +# A release: the binary GoReleaser built for this platform. +FROM tools AS release +ARG TARGETPLATFORM +COPY ${TARGETPLATFORM}/urbex /usr/local/bin/urbex + +# From this checkout. +FROM tools COPY --from=build /out/urbex /usr/local/bin/urbex diff --git a/tools/operator/README.md b/tools/operator/README.md index c4c24bc..3ef41a6 100644 --- a/tools/operator/README.md +++ b/tools/operator/README.md @@ -20,6 +20,21 @@ script expands its arrays the way macOS's bash 3.2 accepts. What it needs: ## Quick start +From a release, nothing to clone: download `urbex-op` from the +[release](https://github.com/urbforge/urbex-cli/releases) (one file). It +runs that release's image, `ghcr.io/urbforge/urbex-op:`, and +pulls it the first time: + +```sh +curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.1.0/urbex-op +chmod +x ~/bin/urbex-op +urbex-op version # urbex-op 0.1.0, image ghcr.io/urbforge/urbex-op:0.1.0 +urbex-op -w ~/urbex-work init # the workspace: SSH key, age key +``` + +From a checkout of this repository (to work on urbex), build the image +from it first: + ```sh tools/operator/urbex-op build # the image, from this checkout tools/operator/urbex-op -w ~/urbex-work init # the workspace: SSH key, age key @@ -115,9 +130,14 @@ See *Find every endpoint* in the cookbook | Variable | Default | Meaning | |---|---|---| | `URBEX_WORKSPACE` | `~/urbex-workspace` | The workspace, if `-w` isn't given. | -| `URBEX_OPERATOR_IMAGE` | `urbex-operator` | The image `build` creates and runs use. | +| `URBEX_OPERATOR_IMAGE` | a release's `urbex-op`: `ghcr.io/urbforge/urbex-op:`; from a checkout: `urbex-operator` | The image runs use (and `build` creates). | | `URBEX_PROXMOX_TOKEN`, `URBEX_CLOUDFLARE_TOKEN`, `URBEX_AGE_KEY` | - | Passed to the container when set; otherwise the credentials file is used. | -Rebuild the image (`urbex-op build`, or `mise run operator-image`) after -updating this checkout: the image contains the `urbex` binary built from +From a checkout, rebuild the image (`urbex-op build`, or `mise run +operator-image`) after updating it: the image contains the `urbex` binary built from it, and the tools at the versions `mise.toml` pins. + +A release builds the same Containerfile with `--target release`, from +the binaries GoReleaser made, for linux/amd64 and linux/arm64, and pushes +it to `ghcr.io/urbforge/urbex-op` (`:`, and `:latest` unless the +tag has a suffix such as `-rc.1`). diff --git a/tools/operator/urbex-op b/tools/operator/urbex-op index 05e529e..e6daa2a 100755 --- a/tools/operator/urbex-op +++ b/tools/operator/urbex-op @@ -3,6 +3,7 @@ # holds everything a platform needs on the operator's side. See README.md. # # urbex-op build build the operator image from this checkout +# urbex-op version this script's version and the image it runs # urbex-op [-w DIR] init create the workspace: keys, folders # urbex-op [-w DIR] set KEY store a credential in the workspace (asks for it) # urbex-op [-w DIR] shell a shell in the container, ready to run urbex @@ -11,25 +12,52 @@ # DIR defaults to $URBEX_WORKSPACE, then ~/urbex-workspace. Tokens come from # the environment if set (URBEX_PROXMOX_TOKEN, URBEX_CLOUDFLARE_TOKEN), else # from the workspace's credentials file - 'set proxmoxToken' puts them there. +# +# A release's urbex-op runs that release's image, ghcr.io/urbforge/urbex-op, +# pulled the first time; from a checkout, the image 'build' makes. +# URBEX_OPERATOR_IMAGE overrides either. set -euo pipefail +# The release workflow sets this in the copy attached to a release. +URBEX_OP_VERSION=dev + WS=${URBEX_WORKSPACE:-$HOME/urbex-workspace} if [ "${1:-}" = "-w" ]; then WS=$2; shift 2; fi -IMAGE=${URBEX_OPERATOR_IMAGE:-urbex-operator} +if [ "$URBEX_OP_VERSION" = dev ]; then + IMAGE=${URBEX_OPERATOR_IMAGE:-urbex-operator} +else + IMAGE=${URBEX_OPERATOR_IMAGE:-ghcr.io/urbforge/urbex-op:$URBEX_OP_VERSION} +fi REPO=$(cd "$(dirname "$0")/../.." && pwd) ENGINE=$(command -v podman || command -v docker || { echo "urbex-op: podman or docker is needed" >&2; exit 1; }) # Files the container writes stay owned by you: podman maps your user in. # macOS bash 3.2 calls an empty "${a[@]}" unbound under set -u: expand arrays as ${a[@]+"${a[@]}"}. USERNS=(); [[ "$ENGINE" == *podman ]] && USERNS=(--userns keep-id) +# The image, pulled the first time when it is a published one. +need_image() { + "$ENGINE" image inspect "$IMAGE" >/dev/null 2>&1 && return + case "$IMAGE" in + */*) echo "urbex-op: pulling $IMAGE" >&2; "$ENGINE" pull "$IMAGE" >&2 ;; + *) echo "urbex-op: no image $IMAGE - run 'urbex-op build' in a checkout of urbforge/urbex-cli" >&2; exit 1 ;; + esac +} + case "${1:-}" in ""|-h|--help) - sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//' + sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//' + exit 0 ;; + version|--version) + echo "urbex-op $URBEX_OP_VERSION, image $IMAGE" exit 0 ;; build) + [ -f "$REPO/tools/operator/Containerfile" ] || { + echo "urbex-op: build needs a checkout of urbforge/urbex-cli; a release's urbex-op pulls its image" >&2; exit 1; } # Go's and mise's versions come from mise.toml, like every other tool's. pinned() { sed -n "s/^$1 = \"\(.*\)\"\$/\1/p" "$REPO/mise.toml"; } + COMMIT=$(git -C "$REPO" rev-parse HEAD 2>/dev/null || true) exec "$ENGINE" build -t "$IMAGE" --build-arg "GO_VERSION=$(pinned go)" --build-arg "MISE_VERSION=$(pinned min_version)" \ + --build-arg "URBEX_COMMIT=$COMMIT" \ -f "$REPO/tools/operator/Containerfile" "$REPO" ;; set) KEY=${2:?usage: urbex-op set KEY - e.g. proxmoxToken, cloudflareToken, ageKey} @@ -37,6 +65,7 @@ case "${1:-}" in VALUE= if [ -t 0 ]; then read -rsp "$KEY: " VALUE || true; echo; else IFS= read -r VALUE || true; fi [ -n "$VALUE" ] || { echo "urbex-op: empty value, nothing stored" >&2; exit 1; } + need_image # Written with the image's Python (Ansible's, which has PyYAML), so the file stays valid YAML and # keeps every other credential; mode 0600. printf '%s' "$VALUE" | "$ENGINE" run --rm -i ${USERNS[@]+"${USERNS[@]}"} --user "$(id -u):$(id -g)" \ @@ -59,6 +88,7 @@ os.chmod(path, 0o600) chmod 700 "$WS/home/.ssh" "$WS/home/.urbex" [ -f "$WS/home/.ssh/urbex" ] || ssh-keygen -q -t ed25519 -N "" -C urbex -f "$WS/home/.ssh/urbex" if [ ! -f "$WS/home/age.key" ]; then + need_image "$ENGINE" run --rm -v "$WS/home:/h:z" "$IMAGE" age-keygen -o /h/age.key 2>/dev/null chmod 600 "$WS/home/age.key" fi @@ -76,6 +106,7 @@ esac [ -d "$WS/home" ] || { echo "urbex-op: no workspace at $WS - run 'urbex-op -w $WS init' first" >&2; exit 1; } CMD=$1 [ "$CMD" = shell ] && CMD="exec bash" +need_image TTY=(); [ -t 0 ] && [ -t 1 ] && TTY=(-it) # OpenSSH (Ansible's transport) refuses to run for a uid with no passwd entry. Podman's keep-id adds