@nx-tools/nx-docker

@nx-tools/nx-docker

Upgrade from v1

v2 of this plugin (2.0.0-alpha.1) includes significant updates but minimal changes in the configuration schema to facilitate the migration process.

Upgrade notes with many usage examples have been added to handle most use cases.

About

This builder provides the tools needed to build and push Docker images with Buildx with full support of the features provided by Moby BuildKit builder toolkit. This includes multi-platform build, secrets, remote cache, etc. and different builder deployment/namespacing options.

• Usage
• Advanced usage
  • Multi-platform image
  • Isolated builders
  • Push to multi-registries
  • Cache
  • Local registry
  • Export image to Docker
  • Handle tags and labels
• Customizing
  • inputs
• Usage with CI
  • GitLab CI
  • GitHub Actions
• Troubleshooting

Usage

The first step is install this package

npm i -D @nx-tools/nx-docker

Then configure the builder in your angular.json or workspace.json, so add something like this to every project you need to dockerize:

  "docker": {
    "executor": "@nx-tools/nx-docker:build",
    "options": {
      "push": true,
      "tags": ["your-org/api:latest", "your-org/api:v1"],
    }
  }

By default, this builder uses the Dockerfile file inside the app folder which are tried to build.

This build not handle registry login steps, so if you wanna push your docker images, please run docker login first.

Advanced usage

• Multi-platform image
• Isolated builders
• Push to multi-registries
• Cache
• Local registry
• Export image to Docker
• Handle tags and labels

Customizing

inputs

This builder can be customized using environment variables and values in your angular.json/workspace.json and always env variables takes precedence

Note: all environmet values should be prefixed with INPUT_ so INPUT_PUSH=true will replace the "push": false configuration of your angular.json/workspace.json file

Note: For list values use a comma-delimited string, like INPUT_TAGS=user/app:v1,user/app:latest

Following inputs can be used as step.with keys

Name	Type	Description
add-hosts	List/CSV	List of customs host-to-IP mapping (e.g., docker:10.180.0.1)
allow	List/CSV	List of extra privileged entitlement (eg. network.host,security.insecure)
build-args	List	List of build-time variables
builder	String	Builder instance (see setup-buildx action)
cache-from	List	List of external cache sources (eg. type=local,src=path/to/dir)
cache-to	List	List of cache export destinations (eg. type=local,dest=path/to/dir)
cgroup-parent¹	String	Optional parent cgroup for the container used in the build
context	String	Build's context is the set of files located in the specified PATH or URL (default Git context)
file	String	Path to the Dockerfile (default ./Dockerfile)
labels	List	List of metadata for an image
load	Bool	Load is a shorthand for --output=type=docker (default false)
no-cache	Bool	Do not use cache when building the image (default false)
outputs	List	List of output destinations (format: type=local,dest=path)
platforms	List/CSV	List of target platforms for build
pull	Bool	Always attempt to pull a newer version of the image (default false)
push	Bool	Push is a shorthand for --output=type=registry (default false)
secret-files	List	List of secret files to expose to the build (eg. key=filename, MY_SECRET=./secret.txt)
secrets	List	List of secrets to expose to the build (eg. key=value, GIT_AUTH_TOKEN=mytoken)
shm-size¹	String	Size of /dev/shm (e.g., 2g)
ssh	List	List of SSH agent socket or keys to expose to the build
tags	List/CSV	List of tags
target	String	Sets the target stage to build
ulimit¹	List	Ulimit options (e.g., nofile=1024:1024)
metadata.images	List	List of Docker images to use as base name for tags
metadata.tags	List	List of tags as key-value pair attributes
metadata.flavor	List	Flavor to apply
metadata.labels	List	List of custom labels
metadata.sep-tags	String	Separator to use for tags output (default \n)
metadata.sep-labels	String	Separator to use for labels output (default \n)

¹ cgroup-parent, shm-size and ulimit are only available using moby/buildkit:master as builder image atm:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v1
  with:
  driver-opts: |
    image=moby/buildkit:master

To check all possible options please check this schema.json file

For deep explanation about metadata extraction, how the options works and see some config examples, please check this

Usage with CI

Gitlab CI

To use with Gitlab CI we provide a custom node image with Docker and Buildx integrated. Just only need to use in your pipeline:

build:
  image: ghcr.io/nx-tools/nx-docker:16.14-alpine # On Docker Hub: gperdomor/nx-docker:16.14-alpine
  services:
    - docker:20.10.14-dind
  variables:
    GIT_DEPTH: 0
    DOCKER_HOST: tcp://docker:2375/
    DOCKER_DRIVER: overlay2
  script:
    - npm i
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
    - docker run --privileged --rm tonistiigi/binfmt --install all # required for multi-platform build
    - docker buildx create --use
    - npx nx affected --target=docker

Note: Circle CI uses docker based pipelines so you can use this image as well

GitHub Actions

To use with Github Actions just only need add something like this to your workflow

name: Build
# This workflow is triggered on pushes to the repository.
on: [push]

jobs:
  build:
    name: Docker build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v1

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1

      - name: Login to DockerHub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: 'Install Dependencies'
        run: npm i

      - name: 'nx build'
        run: npx nx affected --target=docker

Troubleshooting

See TROUBLESHOOTING.md