doc: update readme and examples

Signed-off-by: Yves Brissaud <[email protected]>

README.md

@@ -71,6 +71,8 @@ Or run the `hello` action:
 $ docker runx NAMESPACE/REPOSITORY hello
 ```
 
+See more examples in the [examples](/examples) directory.
+
 ## CLI Plugin Installation
 
 ### Manual Installation

examples/README.md

@@ -0,0 +1,36 @@
+# `docker runx` examples
+
+This directory contains examples used to decorate some images with `runx`.
+
+## Build
+
+### [hello](hello)
+
+```
+$ cd hello
+$ docker runx decorate alpine -t NAMESPACE/hello
+```
+
+An already built image is available under `eunomie/runx-hello`.
+
+### [golangci](golangci)
+
+```
+$ cd golangci
+$ docker runx decorate golangci/golangci-lint:latest -t NAMESPACE/golangci
+```
+
+An already built image is available under `eunomie/runx-golangci`.
+
+### [go](go)
+
+```
+$ cd go
+$ docker runx decorate scratch -t NAMESPACE/go
+```
+
+An already built image is available under `eunomie/go`.
+
+## Usage
+
+Once you built your images, explore them using `--docs` and `--list` options.

examples/go/Dockerfile

@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1.4
+
+ARG XX_VERSION=1.2.1
+ARG ALPINE_VERSION=3.20
+ARG GO_VERSION=1.23.1
+
+ARG BIN_NAME
+
+FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
+
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS build-base
+COPY --from=xx / /
+RUN apk add --no-cache curl
+RUN sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
+RUN apk add --no-cache git ca-certificates openssh-client
+
+FROM build-base AS build
+ARG TARGETPLATFORM
+RUN xx-go --wrap
+WORKDIR /go/src/
+COPY go.mod ./
+COPY go.sum ./
+RUN --mount=type=ssh \
+    --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod \
+     go mod download
+COPY . ./
+
+FROM build AS binary
+ENV CGO_ENABLED=0
+ARG BIN_NAME
+RUN --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod \
+    GIT_VERSION=$(git describe --tags | cut -c 2-) && \
+    xx-go build \
+      -o dist/${BIN_NAME} \
+      -ldflags="-w -s \
+        -X {{.PKG_NAME}}/internal/constants.Version=$GIT_VERSION" \
+      ./cmd/${BIN_NAME} && \
+    xx-verify dist/${BIN_NAME}
+
+FROM scratch AS export-bin
+ARG BIN_NAME
+ARG TARGETOS
+ARG TARGETARCH
+COPY --from=binary /go/src/dist/${BIN_NAME} /${BIN_NAME}-${TARGETOS}-${TARGETARCH}

examples/go/README.md

@@ -0,0 +1,36 @@
+# Go tools - runx version
+
+This is a set of multiple tools to work with Go codebases.
+
+## Usage
+
+### Linter
+
+`lint` action will run `golangci-lint` on the codebase.
+
+Go packages and cache are shared with `golangci-lint` to speed up the process.
+
+### Build
+
+`build` action will build the codebase using `docker buildx` and output as (multi-platform) binaries.
+
+By convention if the binary name is `tool`, it will try to build `cmd/tool/` and the output will be inside `dist` directory.
+
+To make it more convenient while working on a code base, create a file `.docker/runx.yaml` with the following content:
+
+```yaml
+ref: eunomie/go
+images:
+  eunomie/go:
+    actions:
+      build:
+        opts:
+          bin_name: <bin name>
+          platforms: <platforms to build against>
+```
+
+That way you will be able to run `docker runx build` without to specify anything else.
+
+### Mocks
+
+`mocks` action will generate mocks for the codebase using `mockery`.

examples/alpine-hello.runx.yaml → examples/go/runx.yaml

@@ -1,25 +1,4 @@
-default: hello
 actions:
-  - id: hello:user
-    desc: Say hello to the current user
-    type: run
-    env:
-      - USER
-    shell:
-      uname: uname
-    cmd: --rm {{.Ref}} echo hello {{env "USER"}} from {{sh "uname"}}
-
-  - id: hello
-    desc: Say hello!
-    type: run
-    opts:
-      - name: name
-        desc: User's name
-        prompt: Please enter your name
-        required: true
-    cmd: >
-      --rm {{.Ref}} echo hello {{opt "name"}}
-
   - id: lint
     desc: Run golangci-lint
     type: run
@@ -55,3 +34,20 @@ actions:
       --target export-bin
       --output type=local,dest=dist/
       .
+
+  - id: mocks
+    type: run
+    shell:
+      pwd: pwd
+      gopath: go env GOPATH
+      gocache: go env GOCACHE
+    cmd: >
+      --rm
+      -v {{sh "pwd"}}:/app
+      -v {{sh "gopath"}}/pkg:/go/pkg
+      -v {{sh "gocache"}}:/cache/go
+      -e GOCACHE=/cache/go
+      -v {{sh "pwd"}}:/src
+      -w /src
+      docker/mockery:v2.46
+      --keeptree -r --all

examples/golangci/runx.yaml

@@ -0,0 +1,44 @@
+default: lint
+actions:
+  - id: lint
+    desc: Run golangci-lint
+    type: run
+    shell:
+      pwd: pwd
+      gopath: go env GOPATH
+      gocache: go env GOCACHE
+    cmd: >
+      --rm
+        -v {{sh "pwd"}}:/app
+        -v {{sh "gopath"}}/pkg:/go/pkg
+        -v {{sh "gocache"}}:/cache/go
+        -e GOFLAGS=-buildvcs=false
+        -e GOCACHE=/cache/go
+        -e GOLANGCI_LINT_CACHE=/cache/go
+        -w /app
+        {{.Ref}}
+        golangci-lint run -v --timeout 5m
+
+  - id: with-config
+    desc: Run golangci-lint with a specific config file
+    type: run
+    shell:
+      pwd: pwd
+      gopath: go env GOPATH
+      gocache: go env GOCACHE
+    opts:
+      - name: config
+        prompt: Please enter the path to the config file
+        required: true
+    cmd: >
+      --rm
+        -v {{sh "pwd"}}:/app
+        -v {{sh "gopath"}}/pkg:/go/pkg
+        -v {{sh "gocache"}}:/cache/go
+        --mount type=bind,source={{sh "pwd"}}/{{opt "config"}},target=/.golangci.yml
+        -e GOFLAGS=-buildvcs=false
+        -e GOCACHE=/cache/go
+        -e GOLANGCI_LINT_CACHE=/cache/go
+        -w /app
+        {{.Ref}}
+        golangci-lint run -v -c /.golangci.yml --timeout 5m

examples/hello/README.md

@@ -0,0 +1,43 @@
+# docker runx - hello example
+
+This is a simple example of `docker runx` usage.
+
+The main idea is to use an `alpine` image and create two actions:
+- one, `user` that will get the user name from the environment variable
+- the other, `ask` that will ask the user for its name
+
+## Creation of the image
+
+This `README.md` file will be used as the documentation for the image.
+
+The [`runx.yaml`](runx.yaml) file contains the definition of the actions.
+
+```
+$ docker runx decorate alpine --tag NAMESPACE/REPOSITORY
+```
+
+## Usage
+
+### Print this file
+
+```
+$ docker runx NAMESPACE/REPOSITORY --docs
+```
+
+### Run the `user` action
+
+```
+$ docker runx NAMESPACE/REPOSITORY user
+```
+
+### Run the `ask` action
+
+```
+$ docker runx NAMESPACE/REPOSITORY ask
+```
+
+You can also provide the user name as an argument:
+
+```
+$ docker runx NAMESPACE/REPOSITORY ask --opt name=John
+```

examples/hello/runx.yaml

@@ -0,0 +1,20 @@
+actions:
+  - id: user
+    desc: Say hello to the current user
+    type: run
+    env:
+      - USER
+    shell:
+      uname: uname
+    cmd: --rm {{.Ref}} echo hello {{env "USER"}}
+
+  - id: ask
+    desc: Say hello!
+    type: run
+    opts:
+      - name: name
+        desc: User's name
+        prompt: Please enter your name
+        required: true
+    cmd: >
+      --rm {{.Ref}} echo hello {{opt "name"}}