From 572700e41e5a3c67cd6a8c6a6cd0a2167d699801 Mon Sep 17 00:00:00 2001 From: Mohsen Mottaghi Date: Thu, 3 Sep 2026 20:32:50 +0330 Subject: [PATCH] fix(ci): docker image use semver pattern Signed-off-by: Mohsen Mottaghi --- .github/workflows/docker.yaml | 5 +-- README.md | 3 +- docs/installation.md | 84 ++++++++++++++++++++++++++++++++++- 3 files changed, 85 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml index 0b08e32..501bbaa 100644 --- a/.github/workflows/docker.yaml +++ b/.github/workflows/docker.yaml @@ -53,13 +53,10 @@ jobs: with: images: ${{ steps.images.outputs.ghcr }} # `latest` tracks the main branch - # Release tags publish immutable X.Y.Z tags + # Release tags publish a single immutable X.Y.Z tag tags: | type=raw,value=latest,enable={{is_default_branch}} - type=sha,format=short,enable={{is_default_branch}} type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - type=semver,pattern={{major}} flavor: | latest=false labels: | diff --git a/README.md b/README.md index 6fdddbd..ee84c75 100644 --- a/README.md +++ b/README.md @@ -83,8 +83,7 @@ the GitHub Container Registry: | Reference | Points to | | :-- | :-- | | `ghcr.io/infraz/mmdb-cli:latest` | Latest commit on `main` | -| `ghcr.io/infraz/mmdb-cli:1.2.3` (also `:1.2`, `:1`) | Tagged release `v1.2.3` | -| `ghcr.io/infraz/mmdb-cli:sha-abc1234` | A specific `main` commit | +| `ghcr.io/infraz/mmdb-cli:1.2.3` | Tagged release `v1.2.3` | The image `ENTRYPOINT` is `mmdb-cli` and the working directory is `/data`, so mount your files there: diff --git a/docs/installation.md b/docs/installation.md index ec7e96a..fbb25ae 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -12,7 +12,7 @@ tags: # MMDB CLI Installation -MMDB CLI ships as a single static binary. You can install it with [Homebrew](#installation-macos-homebrew) on macOS, Linux package managers, pre-built archives from [GitHub Releases](https://github.com/InfraZ/mmdb-cli/releases), or [build from source](./building-from-source). +MMDB CLI ships as a single static binary. You can install it with [Homebrew](#installation-macos-homebrew) on macOS, Linux package managers, pre-built archives from [GitHub Releases](https://github.com/InfraZ/mmdb-cli/releases), a [container image](#installation-docker), or [build from source](./building-from-source). ## Supported Platforms @@ -31,6 +31,8 @@ Pre-built binaries are published for the following OS and architecture combinati **Note:** If your platform is not listed above, you can [build MMDB CLI from source](./building-from-source). +**Note:** A multi-arch container image (`linux/amd64`, `linux/arm64`) is also published to the GitHub Container Registry — see [Installation (Docker)](#installation-docker). + **Note:** We mainly test MMDB CLI on Linux (amd64) and macOS (arm64). If you encounter issues on other platforms, please [open an issue](https://github.com/InfraZ/mmdb-cli/issues). :::tip[Linux packages] @@ -75,6 +77,86 @@ xattr -dr com.apple.quarantine "$(which mmdb-cli)" ::: +## Installation (Docker) + +Container images are published to the **GitHub Container Registry (GHCR)** for +`linux/amd64` and `linux/arm64`. No registry login is required to pull public images. + +```bash +docker pull ghcr.io/infraz/mmdb-cli:latest +``` + +### Image tags + +| Tag | Points to | Mutable? | +| :-- | :-- | :-: | +| `latest` | Latest commit on the `main` branch | yes | +| `X.Y.Z` (e.g. `0.5.0`) | The matching `vX.Y.Z` release | no | + +:::tip[Pin a version for reproducible use] + +For CI and scripts, pin an immutable `X.Y.Z` release tag (or a digest, +`ghcr.io/infraz/mmdb-cli@sha256:...`) rather than `latest`. + +::: + +### Running the image + +The image `ENTRYPOINT` is `mmdb-cli` and its working directory is `/data`. +Mount the directory that holds your MMDB/JSON files at `/data`, then pass the +subcommand and flags as usual: + +```bash +# Show version (no mount needed) +docker run --rm ghcr.io/infraz/mmdb-cli:latest version + +# Inspect an IP against a local database +docker run --rm -v "$PWD:/data" ghcr.io/infraz/mmdb-cli:latest \ + inspect -i GeoLite2-City.mmdb 8.8.8.8 + +# Print metadata as JSON +docker run --rm -v "$PWD:/data" ghcr.io/infraz/mmdb-cli:latest \ + metadata -i GeoLite2-City.mmdb -f json +``` + +### Writing files back to the host + +The container runs as a non-root user (UID `1000`). When a command writes output +to the mounted directory, add `--user` so the new files are owned by you: + +```bash +docker run --rm -v "$PWD:/data" --user "$(id -u):$(id -g)" \ + ghcr.io/infraz/mmdb-cli:latest \ + generate -i dataset.json -o custom.mmdb +``` + +:::caution[SELinux hosts] + +On Fedora, RHEL, and derivatives, append `:z` (or `:Z`) to the volume so the +bind mount is relabelled: `-v "$PWD:/data:z"`. + +::: + +### Shell alias (optional) + +To use the container as if it were a locally installed binary: + +```bash +alias mmdb-cli='docker run --rm -v "$PWD:/data" --user "$(id -u):$(id -g)" ghcr.io/infraz/mmdb-cli:latest' + +mmdb-cli version +mmdb-cli verify -i GeoLite2-City.mmdb +``` + +### Supply-chain metadata + +Every image is published with SLSA build provenance and an SBOM attestation. +Inspect them with: + +```bash +docker buildx imagetools inspect ghcr.io/infraz/mmdb-cli:latest +``` + ## Installation Instructions (Linux Package Manager) ### Debian and Ubuntu