@nx-tools/nx-container

The Nx Plugin for Containers contains executors, generators, and utilities for build and push containers images from your applications. It provides:

• Easy way to build container images with three different engines:
  • Buildx through Moby BuildKit builder toolkit.
  • Podman.
  • Kaniko.
• Automatic tag management and OCI Image Format Specification for labels,
• Backward compatibility with @nx-tools/nx-docker api.
• Generators to help to setup your apps quickly.

This executor not handle registry login steps, so if you wanna push your container images to a remote registry, please setup the credentials using the docker login or podman login. For kaniko engine, you need to create the /kaniko/.docker/config.json according to this documentation.

This is the succesor of @nx-tools/nx-docker. For docs about nx-docker please go check this

Setting up the Container plugin

Adding the Container plugin to an existing Nx workspace can be done with the following:

npm install -D @nx-tools/nx-container

yarn add -D @nx-tools/nx-container

If you want an "automatic" tag management and OCI Image Format Specification for labels, you need to install the optional @nx-tools/container-metadata package:

npm install -D @nx-tools/container-metadata

yarn add -D @nx-tools/container-metadata

@nx-tools/container-metadata is the succesor of @nx-tools/docker-metadata.

Using the Container Plugin

Configuring an application

It's straightforward to setup your application:

nx g @nx-tools/nx-container:configuration appName

By default, the application will be configured with:

• A Dockerfile in the application root.
• A target to build your application using the Docker engine.

We can then build our application with the following command:

nx container appName

To use a different engine, you need to update the options.engine property of your project target or use the INPUT_ENGINE environment variable. All possible values are docker (the default), podman and kaniko

Tip: You can set docker or podman engine in your project.json targets to use in your dev machine, and use INPUT_ENGINE env variable to use kaniko in your CI/CD pipelines.

Migrate from @nx-tools/nx-docker

Just change @nx-tools/nx-docker:build to @nx-tools/nx-container:build in your project targets and you will continue building images using the docker/buildx engine.

"docker": {
  "executor": "@nx-tools/nx-container:build",
  "options": {
    ...
  }
}

More Documentation

• 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.md

Package reference

Here is a list of all the executors and generators available from this package:

Executors

• build: Builds an image using instructions from the Dockerfile and a specified build context directory.

Generators

• init: Setup required files to build your app.