From 2ab3b97193860518739459a3d5f67bc4a412e598 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Sat, 11 Sep 2021 12:40:31 +0200 Subject: [PATCH] docs: prepare standalone plugin documentation (#27) * docs: prepare standalone plugin documentation * add markdownlint config --- .dictionary | 12 ++ .drone.jsonnet | 61 +++++++- .drone.yml | 373 ++++++++++++++++++++++------------------------ .markdownlint.yml | 6 + README.md | 143 +----------------- _docs/_index.md | 154 +++++++++++++++++++ 6 files changed, 412 insertions(+), 337 deletions(-) create mode 100644 .dictionary create mode 100644 .markdownlint.yml create mode 100644 _docs/_index.md diff --git a/.dictionary b/.dictionary new file mode 100644 index 0000000..b516618 --- /dev/null +++ b/.dictionary @@ -0,0 +1,12 @@ +url +ip +mtu +dns +ipv6 +dockerfile +og +gzip +json +config +host:ip +multiarch diff --git a/.drone.jsonnet b/.drone.jsonnet index 5d07f96..5f0ea90 100644 --- a/.drone.jsonnet +++ b/.drone.jsonnet @@ -235,6 +235,61 @@ local PipelineBuildContainer(arch='amd64') = { }, }; +local PipelineDocs = { + kind: 'pipeline', + name: 'docs', + platform: { + os: 'linux', + arch: 'amd64', + }, + concurrency: { + limit: 1, + }, + steps: [ + { + name: 'markdownlint', + image: 'thegeeklab/markdownlint-cli', + commands: [ + "markdownlint 'docs/content/**/*.md' 'README.md' 'CONTRIBUTING.md'", + ], + }, + { + name: 'spellcheck', + image: 'node:lts-alpine', + commands: [ + 'npm install -g spellchecker-cli', + "spellchecker --files '_docs/**/*.md' 'README.md' 'CONTRIBUTING.md' -d .dictionary -p spell indefinite-article syntax-urls --no-suggestions", + ], + environment: { + FORCE_COLOR: true, + NPM_CONFIG_LOGLEVEL: 'error', + }, + }, + { + name: 'publish', + image: 'plugins/gh-pages', + settings: { + username: { from_secret: 'github_username' }, + password: { from_secret: 'github_token' }, + pages_directory: '_docs/', + target_branch: 'docs', + }, + when: { + ref: ['refs/heads/main'], + }, + }, + ], + depends_on: [ + 'build-binaries', + 'build-container-amd64', + 'build-container-arm64', + 'build-container-arm', + ], + trigger: { + ref: ['refs/heads/main', 'refs/tags/**', 'refs/pull/**'], + }, +}; + local PipelineNotifications = { kind: 'pipeline', image_pull_secrets: ['docker_config'], @@ -320,10 +375,7 @@ local PipelineNotifications = { }, ], depends_on: [ - 'build-binaries', - 'build-container-amd64', - 'build-container-arm64', - 'build-container-arm', + 'docs', ], trigger: { ref: ['refs/heads/main', 'refs/tags/**'], @@ -337,5 +389,6 @@ local PipelineNotifications = { PipelineBuildContainer(arch='amd64'), PipelineBuildContainer(arch='arm64'), PipelineBuildContainer(arch='arm'), + PipelineDocs, PipelineNotifications, ] diff --git a/.drone.yml b/.drone.yml index 6f152f9..e7cd622 100644 --- a/.drone.yml +++ b/.drone.yml @@ -1,106 +1,96 @@ --- -kind: pipeline -name: test - -platform: - os: linux - arch: amd64 - -steps: -- name: staticcheck - image: golang:1.16 - commands: - - go run honnef.co/go/tools/cmd/staticcheck ./... - volumes: - - name: gopath - path: /go - -- name: lint - image: golang:1.16 - commands: - - go run golang.org/x/lint/golint -set_exit_status ./... - volumes: - - name: gopath - path: /go - -- name: vet - image: golang:1.16 - commands: - - go vet ./... - volumes: - - name: gopath - path: /go - -- name: test - image: golang:1.16 - commands: - - go test -cover ./... - volumes: - - name: gopath - path: /go - -volumes: -- name: gopath - temp: {} - image_pull_secrets: - docker_config - +kind: pipeline +name: test +platform: + arch: amd64 + os: linux +steps: +- commands: + - go run honnef.co/go/tools/cmd/staticcheck ./... + image: golang:1.16 + name: staticcheck + volumes: + - name: gopath + path: /go +- commands: + - go run golang.org/x/lint/golint -set_exit_status ./... + image: golang:1.16 + name: lint + volumes: + - name: gopath + path: /go +- commands: + - go vet ./... + image: golang:1.16 + name: vet + volumes: + - name: gopath + path: /go +- commands: + - go test -cover ./... + image: golang:1.16 + name: test + volumes: + - name: gopath + path: /go trigger: ref: - refs/heads/main - refs/tags/** - refs/pull/** - +volumes: +- name: gopath + temp: {} --- +depends_on: +- test +image_pull_secrets: +- docker_config kind: pipeline name: build-binaries - platform: - os: linux arch: amd64 - + os: linux steps: -- name: build - image: techknowlogick/xgo:go-1.16.x - commands: - - "[ -z \"${DRONE_TAG}\" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}" +- commands: + - '[ -z "${DRONE_TAG}" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}' - mkdir -p release/ - - cd cmd/drone-docker && xgo -ldflags "-s -w -X main.version=$BUILD_VERSION" -tags netgo -targets 'linux/amd64,linux/arm-6,linux/arm-7,linux/arm64' -out drone-docker . + - cd cmd/drone-docker && xgo -ldflags "-s -w -X main.version=$BUILD_VERSION" -tags + netgo -targets 'linux/amd64,linux/arm-6,linux/arm-7,linux/arm64' -out drone-docker + . - mv /build/* /drone/src/release/ - ls -l /drone/src/release/ - -- name: executable - image: alpine - commands: + image: techknowlogick/xgo:go-1.16.x + name: build +- commands: - $(find release/ -executable -type f | grep drone-docker-linux-amd64) --help - -- name: compress image: alpine - commands: + name: executable +- commands: - apk add upx - find release/ -maxdepth 1 -executable -type f -exec upx {} \; - ls -lh release/ - -- name: checksum image: alpine - commands: + name: compress +- commands: - cd release/ && sha256sum * > sha256sum.txt - -- name: changelog-generate - image: thegeeklab/git-chglog - commands: + image: alpine + name: checksum +- commands: - git fetch -tq - - git-chglog --no-color --no-emoji -o CHANGELOG.md ${DRONE_TAG:---next-tag unreleased unreleased} - -- name: changelog-format - image: thegeeklab/alpine-tools - commands: + - git-chglog --no-color --no-emoji -o CHANGELOG.md ${DRONE_TAG:---next-tag unreleased + unreleased} + image: thegeeklab/git-chglog + name: changelog-generate +- commands: - prettier CHANGELOG.md - prettier -w CHANGELOG.md - -- name: publish - image: plugins/github-release + image: thegeeklab/alpine-tools + name: changelog-format +- image: plugins/github-release + name: publish settings: api_key: from_secret: github_token @@ -112,36 +102,32 @@ steps: when: ref: - refs/tags/** - -image_pull_secrets: -- docker_config - trigger: ref: - refs/heads/main - refs/tags/** - refs/pull/** - +--- depends_on: - test - ---- +image_pull_secrets: +- docker_config kind: pipeline name: build-container-amd64 - platform: - os: linux arch: amd64 - + os: linux steps: -- name: build +- commands: + - '[ -z "${DRONE_TAG}" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}' + - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/amd64/drone-docker + ./cmd/drone-docker image: golang:1.16 - commands: - - "[ -z \"${DRONE_TAG}\" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}" - - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/amd64/drone-docker ./cmd/drone-docker - -- name: dryrun + name: build +- depends_on: + - build image: plugins/docker:19 + name: dryrun settings: config: from_secret: docker_config @@ -155,11 +141,10 @@ steps: when: ref: - refs/pull/** - depends_on: - - build - -- name: publish-dockerhub +- depends_on: + - dryrun image: plugins/docker:19 + name: publish-dockerhub settings: auto_tag: true auto_tag_suffix: amd64 @@ -175,11 +160,10 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: +- depends_on: - dryrun - -- name: publish-quay image: plugins/docker:19 + name: publish-quay settings: auto_tag: true auto_tag_suffix: amd64 @@ -196,38 +180,32 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: - - dryrun - -image_pull_secrets: -- docker_config - trigger: ref: - refs/heads/main - refs/tags/** - refs/pull/** - +--- depends_on: - test - ---- +image_pull_secrets: +- docker_config kind: pipeline name: build-container-arm64 - platform: - os: linux arch: arm64 - + os: linux steps: -- name: build +- commands: + - '[ -z "${DRONE_TAG}" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}' + - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/arm64/drone-docker + ./cmd/drone-docker image: golang:1.16 - commands: - - "[ -z \"${DRONE_TAG}\" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}" - - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/arm64/drone-docker ./cmd/drone-docker - -- name: dryrun + name: build +- depends_on: + - build image: plugins/docker:19 + name: dryrun settings: config: from_secret: docker_config @@ -241,11 +219,10 @@ steps: when: ref: - refs/pull/** - depends_on: - - build - -- name: publish-dockerhub +- depends_on: + - dryrun image: plugins/docker:19 + name: publish-dockerhub settings: auto_tag: true auto_tag_suffix: arm64 @@ -261,11 +238,10 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: +- depends_on: - dryrun - -- name: publish-quay image: plugins/docker:19 + name: publish-quay settings: auto_tag: true auto_tag_suffix: arm64 @@ -282,38 +258,32 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: - - dryrun - -image_pull_secrets: -- docker_config - trigger: ref: - refs/heads/main - refs/tags/** - refs/pull/** - +--- depends_on: - test - ---- +image_pull_secrets: +- docker_config kind: pipeline name: build-container-arm - platform: - os: linux arch: arm - + os: linux steps: -- name: build +- commands: + - '[ -z "${DRONE_TAG}" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}' + - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/arm/drone-docker + ./cmd/drone-docker image: golang:1.16 - commands: - - "[ -z \"${DRONE_TAG}\" ] && BUILD_VERSION=${DRONE_COMMIT_SHA:0:8} || BUILD_VERSION=${DRONE_TAG##v}" - - go build -v -ldflags "-X main.version=$BUILD_VERSION" -a -tags netgo -o release/arm/drone-docker ./cmd/drone-docker - -- name: dryrun + name: build +- depends_on: + - build image: plugins/docker:19 + name: dryrun settings: config: from_secret: docker_config @@ -327,11 +297,10 @@ steps: when: ref: - refs/pull/** - depends_on: - - build - -- name: publish-dockerhub +- depends_on: + - dryrun image: plugins/docker:19 + name: publish-dockerhub settings: auto_tag: true auto_tag_suffix: arm @@ -347,11 +316,10 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: +- depends_on: - dryrun - -- name: publish-quay image: plugins/docker:19 + name: publish-quay settings: auto_tag: true auto_tag_suffix: arm @@ -368,32 +336,68 @@ steps: ref: - refs/heads/main - refs/tags/** - depends_on: - - dryrun - -image_pull_secrets: -- docker_config - trigger: ref: - refs/heads/main - refs/tags/** - refs/pull/** - -depends_on: -- test - --- +concurrency: + limit: 1 +depends_on: +- build-binaries +- build-container-amd64 +- build-container-arm64 +- build-container-arm +kind: pipeline +name: docs +platform: + arch: amd64 + os: linux +steps: +- commands: + - markdownlint 'docs/content/**/*.md' 'README.md' 'CONTRIBUTING.md' + image: thegeeklab/markdownlint-cli + name: markdownlint +- commands: + - npm install -g spellchecker-cli + - spellchecker --files '_docs/**/*.md' 'README.md' 'CONTRIBUTING.md' -d .dictionary + -p spell indefinite-article syntax-urls --no-suggestions + environment: + FORCE_COLOR: true + NPM_CONFIG_LOGLEVEL: error + image: node:lts-alpine + name: spellcheck +- image: plugins/gh-pages + name: publish + settings: + pages_directory: _docs/ + password: + from_secret: github_token + target_branch: docs + username: + from_secret: github_username + when: + ref: + - refs/heads/main +trigger: + ref: + - refs/heads/main + - refs/tags/** + - refs/pull/** +--- +depends_on: +- docs +image_pull_secrets: +- docker_config kind: pipeline name: notifications - platform: - os: linux arch: amd64 - + os: linux steps: -- name: manifest-dockerhub - image: plugins/manifest +- image: plugins/manifest + name: manifest-dockerhub settings: auto_tag: true ignore_missing: true @@ -405,9 +409,8 @@ steps: when: status: - success - -- name: manifest-quay - image: plugins/manifest +- image: plugins/manifest + name: manifest-quay settings: auto_tag: true ignore_missing: true @@ -419,10 +422,7 @@ steps: when: status: - success - -- name: pushrm-dockerhub - image: chko/docker-pushrm:1 - environment: +- environment: DOCKER_PASS: from_secret: docker_password DOCKER_USER: @@ -430,23 +430,23 @@ steps: PUSHRM_FILE: README.md PUSHRM_SHORT: Drone plugin to build multiarch Docker images PUSHRM_TARGET: thegeeklab/${DRONE_REPO_NAME} + image: chko/docker-pushrm:1 + name: pushrm-dockerhub when: status: - success - -- name: pushrm-quay - image: chko/docker-pushrm:1 - environment: +- environment: APIKEY__QUAY_IO: from_secret: quay_token PUSHRM_FILE: README.md PUSHRM_TARGET: quay.io/thegeeklab/${DRONE_REPO_NAME} + image: chko/docker-pushrm:1 + name: pushrm-quay when: status: - success - -- name: matrix - image: plugins/matrix +- image: plugins/matrix + name: matrix settings: homeserver: from_secret: matrix_homeserver @@ -454,17 +454,15 @@ steps: from_secret: matrix_password roomid: from_secret: matrix_roomid - template: "Status: **{{ build.status }}**
Build: [{{ repo.Owner }}/{{ repo.Name }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}
Message: {{ build.message }}" + template: 'Status: **{{ build.status }}**
Build: [{{ repo.Owner }}/{{ repo.Name + }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}
Message: + {{ build.message }}' username: from_secret: matrix_username when: status: - success - failure - -image_pull_secrets: -- docker_config - trigger: ref: - refs/heads/main @@ -472,15 +470,8 @@ trigger: status: - success - failure - -depends_on: -- build-binaries -- build-container-amd64 -- build-container-arm64 -- build-container-arm - --- kind: signature -hmac: aaee4bd5867ef52fc980b533cb9e34a242bace19bbf23a465731a7d360b7dac7 +hmac: 890ccacd8805efc2b185d83ee4e171999cdaa1ce9a779955406baa626ef0b69a ... diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..b59a114 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,6 @@ +--- +default: True +MD013: False +MD041: False +MD004: + style: dash diff --git a/README.md b/README.md index c660233..5d478f0 100644 --- a/README.md +++ b/README.md @@ -10,153 +10,12 @@ Drone plugin to build multiarch Docker images [![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/drone-docker) [![License: MIT](https://img.shields.io/github/license/thegeeklab/drone-docker)](https://github.com/thegeeklab/drone-docker/blob/main/LICENSE) -Drone plugin to build multiarch Docker images. This plugin is a fork of [drone-plugins/drone-docker](https://github.com/drone-plugins/drone-docker). +Drone plugin to build multiarch Docker images. This plugin is a fork of [drone-plugins/drone-docker](https://github.com/drone-plugins/drone-docker). You can find the full documentation at You can find the full documentation at [https://drone-plugins.geekdocs.de](https://drone-plugins.geekdocs.de). ## Docker Tags Tags are following the main Docker version e.g. `19.03`, the second part is reflecting the plugin "version". A full example would be `19.03.5`. -## Build - -Build the binary with the following command: - -```Shell -export GOOS=linux -export GOARCH=amd64 -export CGO_ENABLED=0 -export GO111MODULE=on - -go build -v -a -tags netgo -o release/drone-docker -``` - -Build the Docker image with the following command: - -```Shell -docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-docker . -``` - -## Usage - -> Notice: Be aware that the tis plugin requires privileged capabilities, otherwise the integrated Docker daemon is not able to start. - -```console -docker run --rm \ - -e PLUGIN_TAG=latest \ - -e PLUGIN_REPO=octocat/hello-world \ - -e DRONE_COMMIT_SHA=00000000 \ - -v $(pwd):$(pwd) \ - -w $(pwd) \ - --privileged \ - thegeeklab/drone-docker --dry-run -``` - -## Parameters - -dry_run -: disables docker push - -drone_remote_url -: sets the git remote url - -mirror -: sets a registry mirror to pull images - -storage_driver -: sets the docker daemon storage driver - -storage_path (default `/var/lib/docker`) -: sets the docker daemon storage path - -bip -: allows the docker daemon to bride ip address - -mtu -: sets docker daemon custom mtu setting - -custom_dns -: sets custom docker daemon dns server - -custom_dns_search -: sets custom docker daemon dns search domain - -insecure -: allows the docker daemon to use insecure registries - -ipv6 -: enables docker daemon ipv6 support - -experimental -: enables docker daemon experimental mode - -debug "docker_launch_debug -: enables verbose debug mode for the docker daemon - -daemon_off -: disables the startup of the docker daemon - -dockerfile (default `./Dockerfile`) -: sets dockerfile to use for the image build - -context (default `./`) -: sets the path of the build context to use - -tags (default `latest`) -: sets repository tags to use for the image; tags can also be loaded from a `.tags` file - -auto_tag -: generates tag names automatically based on git branch and git tag - -auto_tag_suffix -: generates tag names with the given suffix - -build_args -: sets custom build arguments for the build - -build_args_from_env -: forwards environment variables as custom arguments to the build - -quiet -: enables suppression of the build output - -target -: sets the build target to use - -cache_from -: sets images to consider as cache sources - -pull_image (default `true`) -: enforces to pull base image at build time - -compress -: enables compression og the build context using gzip - -repo -: sets repository name for the image - -registry (default `https://index.docker.io/v1/`) -: sets docker registry to authenticate with - -username -: sets username to authenticates with - -password -: sets password to authenticates with - -email -: sets email addres to authenticates with - -config -: sets content of the docker daemon json config - -purge (default `true`) -: enables cleanup of the docker environment at the end of a build - -no_cache -: disables the usage of cached intermediate containers - -add_host -: sets additional host:ip mapping - ## Contributors Special thanks goes to all [contributors](https://github.com/thegeeklab/drone-docker/graphs/contributors). If you would like to contribute, diff --git a/_docs/_index.md b/_docs/_index.md new file mode 100644 index 0000000..5dc9fa8 --- /dev/null +++ b/_docs/_index.md @@ -0,0 +1,154 @@ +--- +title: drone-docker +--- + + + +{{< toc >}} + + + +## Build + +Build the binary with the following command: + +```Shell +export GOOS=linux +export GOARCH=amd64 +export CGO_ENABLED=0 +export GO111MODULE=on + +go build -v -a -tags netgo -o release/drone-docker +``` + +Build the Docker image with the following command: + +```Shell +docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-docker . +``` + +## Usage + +{{< hint [warning] >}} +**Note**\ +Be aware that the this plugin requires privileged capabilities, otherwise the +integrated Docker daemon is not able to start. +{{< /hint >}} + +```Shell +docker run --rm \ + -e PLUGIN_TAG=latest \ + -e PLUGIN_REPO=octocat/hello-world \ + -e DRONE_COMMIT_SHA=00000000 \ + -v $(pwd):$(pwd) \ + -w $(pwd) \ + --privileged \ + thegeeklab/drone-docker --dry-run +``` + +## Parameters + +dry_run +: disables docker push + +drone_remote_url +: sets the git remote url + +mirror +: sets a registry mirror to pull images + +storage_driver +: sets the docker daemon storage driver + +storage_path (default `/var/lib/docker`) +: sets the docker daemon storage path + +bip +: allows the docker daemon to bride ip address + +mtu +: sets docker daemon custom mtu setting + +custom_dns +: sets custom docker daemon dns server + +custom_dns_search +: sets custom docker daemon dns search domain + +insecure +: allows the docker daemon to use insecure registries + +ipv6 +: enables docker daemon ipv6 support + +experimental +: enables docker daemon experimental mode + +debug "docker_launch_debug +: enables verbose debug mode for the docker daemon + +daemon_off +: disables the startup of the docker daemon + +dockerfile (default `./Dockerfile`) +: sets dockerfile to use for the image build + +context (default `./`) +: sets the path of the build context to use + +tags (default `latest`) +: sets repository tags to use for the image; tags can also be loaded from a `.tags` file + +auto_tag +: generates tag names automatically based on git branch and git tag + +auto_tag_suffix +: generates tag names with the given suffix + +build_args +: sets custom build arguments for the build + +build_args_from_env +: forwards environment variables as custom arguments to the build + +quiet +: enables suppression of the build output + +target +: sets the build target to use + +cache_from +: sets images to consider as cache sources + +pull_image (default `true`) +: enforces to pull base image at build time + +compress +: enables compression og the build context using gzip + +repo +: sets repository name for the image + +registry (default `https://index.docker.io/v1/`) +: sets docker registry to authenticate with + +username +: sets username to authenticates with + +password +: sets password to authenticates with + +email +: sets email address to authenticates with + +config +: sets content of the docker daemon json config + +purge (default `true`) +: enables cleanup of the docker environment at the end of a build + +no_cache +: disables the usage of cached intermediate containers + +add_host +: sets additional host:ip mapping