diff --git a/_docs/_index.md b/_docs/content/_index.md similarity index 50% rename from _docs/_index.md rename to _docs/content/_index.md index fb1db19..f306b1b 100644 --- a/_docs/_index.md +++ b/_docs/content/_index.md @@ -21,6 +21,30 @@ Drone plugin to build and publish multiarch Docker images. The tags follow the major version of Docker, e.g. `19`, the minor and patch part reflects the "version" of the plugin. A full example would be `19.6.5`. Minor versions may introduce breaking changes, while patch versions may be considered non-breaking. +## Usage + +```YAML +kind: pipeline +name: default + +steps: + - name: docker + image: thegeeklab/drone-docker + settings: + username: octocat + password: secure + repo: octocat/example + tags: latest +``` + +### Parameters + + + +{{< propertylist name=drone-docker.data >}} + + + ## Build Build the binary with the following command: @@ -40,7 +64,7 @@ Build the Docker image with the following command: docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-docker . ``` -## Usage +## Test {{< hint type=important >}} Be aware that the this plugin requires privileged capabilities, otherwise the integrated Docker daemon is not able to start. @@ -56,110 +80,3 @@ docker run --rm \ --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 -: sets the docker daemon storage path (default `/var/lib/docker`) - -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 -: sets dockerfile to use for the image build (default `./Dockerfile`) - -context -: sets the path of the build context to use (default `./`) - -tags -: sets repository tags to use for the image; tags can also be loaded from a `.tags` file (default `latest`) - -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 -: enforces to pull base image at build time (default `true`) - -compress -: enables compression og the build context using gzip - -repo -: sets repository name for the image - -registry -: sets docker registry to authenticate with (default `https://index.docker.io/v1/`) - -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 -: enables cleanup of the docker environment at the end of a build (default `true`) - -no_cache -: disables the usage of cached intermediate containers - -add_host -: sets additional host:ip mapping diff --git a/_docs/data/data.yaml b/_docs/data/data.yaml new file mode 100644 index 0000000..b8a3d3f --- /dev/null +++ b/_docs/data/data.yaml @@ -0,0 +1,200 @@ +--- +parameters: + dry_run: + description: Disable docker push. + type: bool + required: false + + drone_remote_url: + description: The git remote url. + type: string + required: false + + mirror: + description: Use a registry mirror to pull images. + type: string + required: false + + storage_driver: + description: The docker daemon storage driver. + type: string + required: false + + storage_path: + description: The docker daemon storage path. + defaultValue: /var/lib/docker + type: string + required: false + + bip: + description: Allows the docker daemon to bride IP address. + type: string + required: false + + mtu: + description: A docker daemon custom MTU. + type: string + required: false + + custom_dns: + description: Custom docker daemon DNS server. + type: list + required: false + + custom_dns_search: + description: Custom docker daemon DNS search domain. + type: list + required: false + + insecure: + description: Enable the usage of insecure registries. + type: bool + defaultValue: false + required: false + + ipv6: + description: Enable docker daemon IPv6 support. + type: bool + defaultValue: false + required: false + + experimental: + description: Enable docker daemon experimental mode. + type: bool + defaultValue: false + required: false + + daemon_debug: + description: Enable verbose debug mode for the docker daemon. + type: string + defaultValue: false + required: false + + daemon_off: + description: Disable the startup of the docker daemon. + type: string + defaultValue: false + required: false + + dockerfile: + description: Set dockerfile to use for the image build. + defaultValue: Dockerfile + type: string + required: false + + context: + description: Set the path of the build context to use. + defaultValue: . + type: string + required: false + + tags: + description: Set repository tags to use for the image. Tags can also be loaded from a `.tags` file. + defaultValue: latest + type: list + required: false + + auto_tag: + description: > + Generate tag names automatically based on git branch and git tag. When this feature is enabled and the event type is `tag`, + the plugin will automatically tag the image using the standard semVer convention. For example: + + - `1.0.0` produces docker tags `1`, `1.0`, `1.0.0` + - `1.0.0-rc.1` produces docker tags `1.0.0-rc.1` + + When the event type is `push` and the target branch is your default branch, the plugin will automatically tag the image + as `latest`. All other event types and branches are ignored. + defaultValue: false + type: bool + required: false + + auto_tag_suffix: + description: Generate tag names with the given suffix. + type: string + required: false + + build_args: + description: Ccustom build arguments to pass to the build. + type: list + required: false + + build_args_from_env: + description: Forward environment variables as custom arguments to the build. + type: list + required: false + + quiet: + description: Enable suppression of the build output. + defaultValue: false + type: bool + required: false + + target: + description: The docker build target. + type: string + required: false + + cache_from: + description: Images to consider as cache sources. + type: list + required: false + + pull_image: + description: Enforce to pull the base image at build time. + defaultValue: true + type: bool + required: false + + compress: + description: Enable compression og the build context using gzip. + defaultValue: false + type: bool + required: false + + repo: + description: Repository name for the image. + type: string + required: false + + registry: + description: Docker registry to upload images. + defaultValue: https://index.docker.io/v1/ + type: string + required: false + + username: + description: Username for authentication with the registry. + type: string + required: false + + password: + description: Password for authentication with the registry. + type: string + required: false + + email: + description: E-Mail address for authentication with the registry. + type: string + required: false + + config: + description: Content of the docker daemon json config. + type: string + required: false + + purge: + description: Enable cleanup of the docker environment at the end of a build. + defaultValue: true + type: bool + required: false + + no_cache: + description: Disable the usage of cached intermediate containers. + defaultValue: false + type: string + required: false + + add_host: + description: Additional `host:ip` mapping. + type: list + required: false diff --git a/cmd/drone-docker/config.go b/cmd/drone-docker/config.go index 9cee18f..0a00194 100644 --- a/cmd/drone-docker/config.go +++ b/cmd/drone-docker/config.go @@ -11,35 +11,35 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.BoolFlag{ Name: "dry-run", EnvVars: []string{"PLUGIN_DRY_RUN"}, - Usage: "disables docker push", + Usage: "disable docker push", Destination: &settings.Dryrun, Category: category, }, &cli.StringFlag{ Name: "remote.url", EnvVars: []string{"DRONE_REMOTE_URL"}, - Usage: "sets the git remote url", + Usage: "git remote url", Destination: &settings.Build.Remote, Category: category, }, &cli.StringFlag{ Name: "daemon.mirror", EnvVars: []string{"PLUGIN_MIRROR", "DOCKER_PLUGIN_MIRROR"}, - Usage: "sets a registry mirror to pull images", + Usage: "registry mirror to pull images", Destination: &settings.Daemon.Mirror, Category: category, }, &cli.StringFlag{ Name: "daemon.storage-driver", EnvVars: []string{"PLUGIN_STORAGE_DRIVER"}, - Usage: "sets the docker daemon storage driver", + Usage: "docker daemon storage driver", Destination: &settings.Daemon.StorageDriver, Category: category, }, &cli.StringFlag{ Name: "daemon.storage-path", EnvVars: []string{"PLUGIN_STORAGE_PATH"}, - Usage: "sets the docker daemon storage path", + Usage: "docker daemon storage path", Value: "/var/lib/docker", Destination: &settings.Daemon.StoragePath, Category: category, @@ -47,70 +47,75 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.StringFlag{ Name: "daemon.bip", EnvVars: []string{"PLUGIN_BIP"}, - Usage: "allows the docker daemon to bride ip address", + Usage: "allow the docker daemon to bride ip address", Destination: &settings.Daemon.Bip, Category: category, }, &cli.StringFlag{ Name: "daemon.mtu", EnvVars: []string{"PLUGIN_MTU"}, - Usage: "sets docker daemon custom mtu setting", + Usage: "docker daemon custom mtu setting", Destination: &settings.Daemon.MTU, Category: category, }, &cli.StringSliceFlag{ Name: "daemon.dns", EnvVars: []string{"PLUGIN_CUSTOM_DNS"}, - Usage: "sets custom docker daemon dns server", + Usage: "custom docker daemon dns server", Destination: &settings.Daemon.DNS, Category: category, }, &cli.StringSliceFlag{ Name: "daemon.dns-search", EnvVars: []string{"PLUGIN_CUSTOM_DNS_SEARCH"}, - Usage: "sets custom docker daemon dns search domain", + Usage: "custom docker daemon dns search domain", Destination: &settings.Daemon.DNSSearch, Category: category, }, &cli.BoolFlag{ Name: "daemon.insecure", EnvVars: []string{"PLUGIN_INSECURE"}, - Usage: "allows the docker daemon to use insecure registries", + Usage: "allow the docker daemon to use insecure registries", + Value: false, Destination: &settings.Daemon.Insecure, Category: category, }, &cli.BoolFlag{ Name: "daemon.ipv6", EnvVars: []string{"PLUGIN_IPV6"}, - Usage: "enables docker daemon IPv6 support", + Usage: "enable docker daemon IPv6 support", + Value: false, Destination: &settings.Daemon.IPv6, Category: category, }, &cli.BoolFlag{ Name: "daemon.experimental", EnvVars: []string{"PLUGIN_EXPERIMENTAL"}, - Usage: "enables docker daemon experimental mode", + Usage: "enable docker daemon experimental mode", + Value: false, Destination: &settings.Daemon.Experimental, Category: category, }, &cli.BoolFlag{ Name: "daemon.debug", EnvVars: []string{"PLUGIN_DEBUG", "DOCKER_LAUNCH_DEBUG"}, - Usage: "enables verbose debug mode for the docker daemon", + Usage: "enable verbose debug mode for the docker daemon", + Value: false, Destination: &settings.Daemon.Debug, Category: category, }, &cli.BoolFlag{ Name: "daemon.off", EnvVars: []string{"PLUGIN_DAEMON_OFF"}, - Usage: "disables the startup of the docker daemon", + Usage: "disable the startup of the docker daemon", + Value: false, Destination: &settings.Daemon.Disabled, Category: category, }, &cli.StringFlag{ Name: "dockerfile", EnvVars: []string{"PLUGIN_DOCKERFILE"}, - Usage: "sets dockerfile to use for the image build", + Usage: "dockerfile to use for the image build", Value: "Dockerfile", Destination: &settings.Build.Dockerfile, Category: category, @@ -118,7 +123,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.StringFlag{ Name: "context", EnvVars: []string{"PLUGIN_CONTEXT"}, - Usage: "sets the path of the build context to use", + Usage: "path of the build context", Value: ".", Destination: &settings.Build.Context, Category: category, @@ -126,7 +131,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.StringSliceFlag{ Name: "tags", EnvVars: []string{"PLUGIN_TAG", "PLUGIN_TAGS"}, - Usage: "sets repository tags to use for the image", + Usage: "repository tags to use for the image", FilePath: ".tags", Destination: &settings.Build.Tags, Category: category, @@ -134,56 +139,58 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.BoolFlag{ Name: "tags.auto", EnvVars: []string{"PLUGIN_DEFAULT_TAGS", "PLUGIN_AUTO_TAG"}, - Usage: "generates tag names automatically based on git branch and git tag", + Usage: "generate tag names automatically based on git branch and git tag", + Value: false, Destination: &settings.Build.TagsAuto, Category: category, }, &cli.StringFlag{ Name: "tags.suffix", EnvVars: []string{"PLUGIN_DEFAULT_SUFFIX", "PLUGIN_AUTO_TAG_SUFFIX"}, - Usage: "generates tag names with the given suffix", + Usage: "generate tag names with the given suffix", Destination: &settings.Build.TagsSuffix, Category: category, }, &cli.StringSliceFlag{ Name: "args", EnvVars: []string{"PLUGIN_BUILD_ARGS"}, - Usage: "sets custom build arguments for the build", + Usage: "custom build arguments for the build", Destination: &settings.Build.Args, Category: category, }, &cli.StringSliceFlag{ Name: "args-from-env", EnvVars: []string{"PLUGIN_BUILD_ARGS_FROM_ENV"}, - Usage: "forwards environment variables as custom arguments to the build", + Usage: "forward environment variables as custom arguments to the build", Destination: &settings.Build.ArgsEnv, Category: category, }, &cli.BoolFlag{ Name: "quiet", EnvVars: []string{"PLUGIN_QUIET"}, - Usage: "enables suppression of the build output", + Usage: "enable suppression of the build output", + Value: false, Destination: &settings.Build.Quiet, Category: category, }, &cli.StringFlag{ Name: "target", EnvVars: []string{"PLUGIN_TARGET"}, - Usage: "sets the build target to use", + Usage: "build target to use", Destination: &settings.Build.Target, Category: category, }, &cli.StringSliceFlag{ Name: "cache-from", EnvVars: []string{"PLUGIN_CACHE_FROM"}, - Usage: "sets images to consider as cache sources", + Usage: "images to consider as cache sources", Destination: &settings.Build.CacheFrom, Category: category, }, &cli.BoolFlag{ Name: "pull-image", EnvVars: []string{"PLUGIN_PULL_IMAGE"}, - Usage: "enforces to pull base image at build time", + Usage: "enforce to pull base image at build time", Value: true, Destination: &settings.Build.Pull, Category: category, @@ -191,21 +198,22 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.BoolFlag{ Name: "compress", EnvVars: []string{"PLUGIN_COMPRESS"}, - Usage: "enables compression og the build context using gzip", + Usage: "enable compression og the build context using gzip", + Value: false, Destination: &settings.Build.Compress, Category: category, }, &cli.StringFlag{ Name: "repo", EnvVars: []string{"PLUGIN_REPO"}, - Usage: "sets repository name for the image", + Usage: "repository name for the image", Destination: &settings.Build.Repo, Category: category, }, &cli.StringFlag{ Name: "docker.registry", EnvVars: []string{"PLUGIN_REGISTRY", "DOCKER_REGISTRY"}, - Usage: "sets docker registry to authenticate with", + Usage: "docker registry to authenticate with", Value: "https://index.docker.io/v1/", Destination: &settings.Login.Registry, Category: category, @@ -213,35 +221,35 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.StringFlag{ Name: "docker.username", EnvVars: []string{"PLUGIN_USERNAME", "DOCKER_USERNAME"}, - Usage: "sets username to authenticates with", + Usage: "username for registry authentication", Destination: &settings.Login.Username, Category: category, }, &cli.StringFlag{ Name: "docker.password", EnvVars: []string{"PLUGIN_PASSWORD", "DOCKER_PASSWORD"}, - Usage: "sets password to authenticates with", + Usage: "password for registry authentication", Destination: &settings.Login.Password, Category: category, }, &cli.StringFlag{ Name: "docker.email", EnvVars: []string{"PLUGIN_EMAIL", "DOCKER_EMAIL"}, - Usage: "sets email address to authenticates with", + Usage: "email address for registry authentication", Destination: &settings.Login.Email, Category: category, }, &cli.StringFlag{ Name: "docker.config", EnvVars: []string{"PLUGIN_CONFIG", "DOCKER_PLUGIN_CONFIG"}, - Usage: "sets content of the docker daemon json config", + Usage: "content of the docker daemon json config", Destination: &settings.Login.Config, Category: category, }, &cli.BoolFlag{ Name: "docker.purge", EnvVars: []string{"PLUGIN_PURGE"}, - Usage: "enables cleanup of the docker environment at the end of a build", + Usage: "enable cleanup of the docker environment at the end of a build", Value: true, Destination: &settings.Cleanup, Category: category, @@ -249,14 +257,15 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag { &cli.BoolFlag{ Name: "no-cache", EnvVars: []string{"PLUGIN_NO_CACHE"}, - Usage: "disables the usage of cached intermediate containers", + Usage: "disable the usage of cached intermediate containers", + Value: false, Destination: &settings.Build.NoCache, Category: category, }, &cli.StringSliceFlag{ Name: "add-host", EnvVars: []string{"PLUGIN_ADD_HOST"}, - Usage: "sets additional host:ip mapping", + Usage: "additional host:ip mapping", Destination: &settings.Build.AddHost, Category: category, },