@nx-tools/nx-docker v3.0.8

@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

¹ 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