---
title: Docker
---

Since [v0.31.0](https://github.com/goreleaser/goreleaser/releases/tag/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:

```yaml
dockers:
  - image: user/repo
```

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

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

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

## Customization

Of course, you can customize a lot of things:

```yaml
# .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
    # Docker image name.
    image: myuser/myimage
    # Path to the Dockerfile (from the project root).
    dockerfile: Dockerfile
    # Template of the docker tag. Defaults to `{{ .Version }}`. Other allowed
    # fields are `.Tag`, `.Major`, `.Minor` and `.Patch` and
    # `.Env.VARIABLE_NAME`.
    tag_templates:
    - "{{ .Tag }}"
    - "{{ .Tag }}-{{ .Env.GO_VERSION }}"
    - "v{{ .Major }}"
    - latest
    # If your Dockerfile copies files other than the binary itself,
    # you should list them here as well.
    extra_files:
    - config.yml
```

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.

## Passing environment variables to tag_template

You can do that by using `{{ .Env.VARIABLE_NAME }}` in the template, for
example:

```yaml
dockers:
  -
    tag_template: "{{ .Tag }}-{{ .Env.GOVERSION_NR }}"
```

Then you can run:

```console
GOVERSION_NR=$(go version | awk '{print $3}') goreleaser
```

## 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`:

```yaml
# .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

Hope this feature serves you well!

More info:

* [#461](https://github.com/goreleaser/goreleaser/issues/461)
* [#505](https://github.com/goreleaser/goreleaser/issues/505)