version: support OCI labels, version file in tar files, app version report, and dashboard (other dashboard enhancements)

[gmarzot]

The deployed relay still reports 0.1.0 after the v0.2.1 release — the version is the static CMake project version and nothing updates it.

This bakes git describe --tags into the image at publish time:

• release commit → bare tag: v0.2.1
• main/PR snapshot → v0.2.1-14-g<sha> — identifies exactly what's deployed
• local builds → unchanged (static project-version fallback; the docker build context has no .git, hence the build-arg approach)

Flows to the dashboard badge through the existing /info → json-exporter → moqx_build_info chain — zero dashboard changes. Publish checkout gains fetch-depth: 0 so describe can see tags.

Caveat: the Dockerfile path only runs in the main publish job, so the proof is the first post-merge publish — the badge should flip from v0.1.0 to v0.2.1-N-g… on the following deploy.

---

This change is 

[michalhosna]

Why is this docker-only? Shouldn't we be able to bake this to every binary? Even for local-dev builds this would be nice.

I.e. move this logic from docker to cmake?

@michalhosna made 2 comments.
Reviewable status: 0 of 3 files reviewed, 1 unresolved discussion (waiting on afrind, gmarzot, and mondain).

---

.github/workflows/ci-main.yml line 389 at r1 (raw file):

          # Leading "v" stripped — /info reports bare semver-style ("0.2.1",
          # "0.2.1-14-gabc1234"); display layers add their own "v".
          echo "describe=$(git describe --tags --always | sed 's/^v//')" >> "$GITHUB_OUTPUT"

This may resolve to snapshot-latest, it probably needs some logic to only care about v prefixed tags?

[michalhosna]

@michalhosna made 1 comment.
Reviewable status: 0 of 3 files reviewed, 1 unresolved discussion (waiting on afrind, gmarzot, and mondain).

---

.github/workflows/ci-main.yml line 389 at r1 (raw file):

Previously, michalhosna (Michal Hošna) wrote…

This may resolve to snapshot-latest, it probably needs some logic to only care about v prefixed tags?

Something like this should work

git describe --tags --match 'v[0-9].*'

[mondain]

@mondain reviewed 3 files and all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on afrind and gmarzot).

[gmarzot]

Why is this docker-only? Shouldn't we be able to bake this to every binary? Even for local-dev builds this would be nice.

I.e. move this logic from docker to cmake?

yes - good idea. updates added.

[gmarzot]

Both review points addressed in 73a1bf7.

"Why is this docker-only? Move the logic to cmake" — done. Derivation now lives in cmake/MoqxVersion.cmake with an explicit precedence chain:

1. -DMOQX_VERSION_STRING — explicit (the release workflow passes the exact tag)
2. <src>/VERSION — stamped by CI; the docker context and source tarballs have no .git, so this is how they resolve
3. git describe — any clone, including local dev builds
4. v${PROJECT_VERSION} — last resort

The build arg is now just an override, not the mechanism. Local builds get a real version with no CI involvement (and a -dirty suffix when the tree is modified).

"This may resolve to snapshot-latest" — correct, and it's a live bug, not a theoretical one. Demonstrated on the commit snapshot-latest currently points at:

git describe --tags 4969f8c5                  -> snapshot-latest    # version of every main image
git describe --tags --match 'v[0-9]*' 4969f8c5 -> 4969f8c5           # honest sha fallback

The tag moves to the newest main commit on every publish, so it would have overtaken v0.2.1 on the next one. Fixed with --match 'v[0-9]*' (keeping --always for the no-tag case) in both the cmake path and the CI stamp, with a comment explaining why it's load-bearing so it doesn't get "simplified" away later. Same hazard applies to the 21 build-* and 4 other snapshot-* tags.

One deliberate change of direction: the leading v is now kept rather than stripped. The string is a git identifier, so it round-trips into git checkout / gh release view.

Since the version is no longer welded to moqx_core as a private compile definition (it's an interface target carrying a generated header), it's usable anywhere — the generalization payoff, all verified in a real container build:

moqx --version   -> moqx version v0.2.1-2-g59fe6a9b
/info            -> {"service":"moqx","version":"v0.2.1-2-g59fe6a9b"}
cat /usr/local/VERSION -> v0.2.1-2-g59fe6a9b   # identify an image without running it

plus a startup log banner so a relay's log stream is attributable to a build, and VERSION shipped in the install tree so release/snapshot tarballs carry the identifier.

Verified locally end to end: full docker build with no build-arg (resolving purely through the stamped VERSION file), all four precedence levels exercised, and both workflow files YAML-validated.

[gmarzot]

@michalhosna good to go?

[michalhosna]

@michalhosna made 4 comments.
Reviewable status: 0 of 9 files reviewed, 5 unresolved discussions (waiting on afrind, gmarzot, and mondain).

---

-- commits line 67 at r3:
What commit message will land on main? This doesn't seem reviable

---

cmake/MoqxVersion.cmake line 9 at r3 (raw file):

#
# Format is git-describe output with the "v" tag prefix retained, so the
# string round-trips into `git checkout` / `gh release view`:

Why does the PR comment, commit message and this comment talk about gh release view?

It seems to me everything this does is pure git, and gh is used only in the CI.

---

cmake/MoqxVersion.cmake line 31 at r3 (raw file):

#
# Only v-prefixed numeric tags are considered. The repo also carries moving
# tags (snapshot-latest, build-*, archive/*) that are NOT versions; an

Nit: I don't think remarks about what other tags currently exists (snapshot-latest, build-*, archive/*) really make sense.
If we start doing tags differently, this file becomes out-of-date.

Generally, could the comments (and git commit messages) be toned down? Its adding a lot of not-that-useful text to review.

---

docker/Dockerfile line 55 at r3 (raw file):

# executing it — inspecting a layer, or a foreign-arch image that cannot run
# here. `docker run --rm <image> moqx --version` reports the same string.
COPY --from=builder /install/VERSION /usr/local/VERSION

VERSION file can drift from the baked-in version.

Even just passing MOQX_VERSION_STRING build arg different from the VERSION file will make them drift.

Is /usr/local/VERSION something standard/commonly used? I cannot find a good outside reference.

Why not use standardized labels? See https://specs.opencontainers.org/image-spec/annotations/

For example

ARG MOQX_VERSION_STRING=""
LABEL org.opencontainers.image.version="$MOQX_VERSION_STRING" \
        org.opencontainers.image.source="https://github.com/openmoq/moqx"

but probably include a more complete set if we want to do this. FYI there's oficial action for gh https://github.com/docker/metadata-action

And then the whole VERSION file logic can be dropped

[michalhosna]

@michalhosna made 1 comment.
Reviewable status: 0 of 9 files reviewed, 6 unresolved discussions (waiting on afrind, gmarzot, and mondain).

---

cmake/MoqxVersion.cmake line 53 at r3 (raw file):

  execute_process(
    COMMAND "${GIT_EXECUTABLE}" describe --tags --match "v[0-9]*" --always --dirty

--dirty is good, but FYI it doesn't catch untracked files, i.e. new files not yet in git.

[michalhosna]

@michalhosna reviewed 10 files and all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on afrind, gmarzot, and mondain).

[gmarzot]

-- commits line 67 at r3:

Previously, michalhosna (Michal Hošna) wrote…

What commit message will land on main? This doesn't seem reviable

with squash-merge the pr title is the merged commit message. this detail is retained for more complete history

[gmarzot]

cmake/MoqxVersion.cmake line 9 at r3 (raw file):

Previously, michalhosna (Michal Hošna) wrote…

Why does the PR comment, commit message and this comment talk about gh release view?

It seems to me everything this does is pure git, and gh is used only in the CI.

i think the point was the even though we tag w/ M.m.f the reported and and expected format in a number of cases has vM.m.f
in anycase I trimmed the comment

[gmarzot]

cmake/MoqxVersion.cmake line 53 at r3 (raw file):

Previously, michalhosna (Michal Hošna) wrote…

--dirty is good, but FYI it doesn't catch untracked files, i.e. new files not yet in git.

--porcelain appears to produce the more sensitive detection of "dirty" .. but may also produce dirty in cases where it is not really relevant .. but it is now the sensitive mode and will catch the untracked file case

[gmarzot]

docker/Dockerfile line 55 at r3 (raw file):

Previously, michalhosna (Michal Hošna) wrote…

VERSION file can drift from the baked-in version.

Even just passing MOQX_VERSION_STRING build arg different from the VERSION file will make them drift.

Is /usr/local/VERSION something standard/commonly used? I cannot find a good outside reference.

Why not use standardized labels? See https://specs.opencontainers.org/image-spec/annotations/

For example

ARG MOQX_VERSION_STRING=""
LABEL org.opencontainers.image.version="$MOQX_VERSION_STRING" \
        org.opencontainers.image.source="https://github.com/openmoq/moqx"

but probably include a more complete set if we want to do this. FYI there's oficial action for gh https://github.com/docker/metadata-action

And then the whole VERSION file logic can be dropped

The other sources of version trump the file and the file is written/over-written by the true version. the VERSION file now is only relevant to tar files

[gmarzot]

@gmarzot made 1 comment and resolved 2 discussions.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on afrind, michalhosna, and mondain).

---

.github/workflows/ci-main.yml line 389 at r1 (raw file):

Previously, michalhosna (Michal Hošna) wrote…

Something like this should work

git describe --tags --match 'v[0-9].*'

Done.

[michalhosna]

@michalhosna reviewed 2 files and all commit messages, made 1 comment, and resolved 4 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on afrind and mondain).

---

-- commits line 67 at r3:

Previously, gmarzot (Giovanni Marzot) wrote…

with squash-merge the pr tiotle is the merged commit message. this detail is retained for more complete history

I'd prefer to see more human readable/human curated PR descriptions and commit messages, this is challenging to read.