goreleaser/www/content/docker.md

title	series	hideFromIndex	weight
Docker	customization	true	140

Since v0.31.0, GoReleaser supports building and pushing Docker images.

How it works

You can declare multiple Docker images. They will be matched against the binaries generated by your builds section.

If you have only one build setup, the configuration is as easy as adding the name of your image to your .goreleaser.yml file:

dockers:
  - image: user/repo

You also need to create a Dockerfile in your project's root folder:

FROM scratch
COPY mybin /
ENTRYPOINT ["/mybin"]

This configuration will build and push a Docker image named user/repo:tagname.

Attention: Note that were are not building any go files in the docker build phase, we are merely copying the binary to a scratch image and setting up the entrypoint.

Customization

Of course, you can customize a lot of things:

# .goreleaser.yml
dockers:
  # You can have multiple Docker images.
  -
    # GOOS of the built binary that should be used.
    goos: linux
    # GOARCH of the built binary that should be used.
    goarch: amd64
    # GOARM of the built binary that should be used.
    goarm: ''
    # Name of the built binary that should be used.
    binary: mybinary
    # Template of the Docker image name.
    image: myuser/myimage
    # Publish to additional registries.
    additional_registries:
    - "gcr.io"
    - "localhost:5000"
    # Skips the docker push. Could be useful if you also do draft releases.
    # Defaults to false.
    skip_push: false
    # Path to the Dockerfile (from the project root).
    dockerfile: Dockerfile 
    # Template of the docker tag. Defaults to `{{ .Version }}`.
    tag_templates:
    - "{{ .Tag }}"
    - "{{ .Tag }}-{{ .Env.GO_VERSION }}"
    - "v{{ .Major }}"
    - latest
    # Template of the docker build flags.
    build_flag_templates:
    - "--label=org.label-schema.schema-version=1.0"
    - "--label=org.label-schema.version={{.Version}}"
    - "--label=org.label-schema.name={{.ProjectName}}"
    - "--build-arg=FOO={{.ENV.Bar}}"
    # If your Dockerfile copies files other than the binary itself,
    # you should list them here as well.
    extra_files:
    - config.yml

Learn more about the name template engine.

These settings should allow you to generate multiple Docker images, for example, using multiple FROM statements, as well as generate one image for each binary in your project.

Generic Image Names

Some users might want to keep their image name as generic as possible. That can be accomplished simply by adding template language in the definition:

# .goreleaser.yml
project: foo
dockers:
  -
    binary: mybinary
    image: myuser/{{.ProjectName}}

This will build and public the following images:

• myuser/foo

Learn more about the name template engine.

Keeping docker images updated for current major

Some users might want to when version to push docker tags :v1, :v1.6, :v1.6.4 and :latest when v1.6.4 (for example) is built. That can be accomplished by using multiple tag_templates:

# .goreleaser.yml
dockers:
  -
    binary: mybinary
    image: myuser/myimage
    tag_templates:
    - "{{ .Tag }}"
    - "v{{ .Major }}"
    - "v{{ .Major }}.{{ .Minor }}"
    - latest

This will build and publish the following images:

• myuser/myimage:v1.6.4
• myuser/myimage:v1
• myuser/myimage:v1.6
• myuser/myimage:latest

With these settings you can hopefully push several different docker images with multiple tags.

Learn more about the name template engine.

Applying docker build flags

Build flags can be applied using build_flag_templates. The flags must be valid docker build flags.

# .goreleaser.yml
dockers:
  -
    binary: mybinary
    image: myuser/myimage
    build_flag_templates:
    - "--label=org.label-schema.schema-version=1.0"
    - "--label=org.label-schema.version={{.Version}}"
    - "--label=org.label-schema.name={{.ProjectName}}"

This will execute the following command:

docker build -t myuser/myimage . \
  --label=org.label-schema.schema-version=1.0 \
  --label=org.label-schema.version=1.6.4 \
  --label=org.label-schema.name=mybinary"

Learn more about the name template engine.