Docker runner

Warning

This feature is experimental and subject to breaking changes. See the Conan stability section for more information.

How to use a docker runner

To run Conan inside a docker container you need to define a [runner] section in your host profile using the following fields:

  • type (mandatory): define the runner we want to use, in this case docker.

  • dockerfile (optional, default None): absolute path to a Dockerfile in case you want to build a docker image.

  • image (optional, default conan-runner-default): docker image name you want to download from a docker registry or the name of the built image in case you define a dockerfile path.

  • cache (optional, default clean): how docker container uses (or not) the host’s Conan cache.

    • clean: use an empty cache.

    • copy: copy the host cache inside the container using the conan cache save/restore command.

    • shared: mount the host’s Conan cache as a shared volume.

  • remove (optional, default false): true or false. Remove the container after running the Conan command.

  • configfile (optional, default None): Absolute path to a configuration file with extra parameters (see extra configuration section for more info).

Note

  • You can only use profiles that are inside the conan profiles folder.

  • Shared cache can cause permissions issues depending on the user inside and outside the container. We recommend using the copy cache even though it may be a bit slower to setup.

  • The runner profile section doesn’t affect the package id.

Extra configuration

If you need more control over the build and execution of the container, you can define more parameters inside a configfile yaml.

  1. image: image_name # The image to build or run.
  2. build:
  3.     dockerfile: /dockerfile/path # Dockerfile path.
  4.     build_context: /build/context/path # Path within the build context to the Dockerfile.
  5.     build_args: # A dictionary of build arguments
  6.         foo: bar
  7.     cacheFrom: # A list of images used for build cache resolution
  8.         - image_1
  9. run:
  10.     name: container_name # The name for this container.
  11.     containerEnv: # Environment variables to set inside the container.
  12.         env_var_1: env_value
  13.     containerUser: user_name # Username or UID to run commands as inside the container.
  14.     privileged: False # Run as privileged
  15.     capAdd: # Add kernel capabilities.
  16.         - SYS_ADMIN
  17.         - MKNOD
  18.     securityOpt: # A list of string values to customize labels for MLS systems, such as SELinux.
  19.         - opt_1
  20.     mount: # A dictionary to configure volumes mounted inside the container.
  21.         /home/user1/: # The host path or a volume name
  22.             bind: /mnt/vol2 # The path to mount the volume inside the container
  23.             mode: rw # rw to mount the volume read/write, or ro to mount it read-only.
  24.     network: my-network # Specifies the network for the container.

How to run a conan create in a runner

Note

The docker runner feature is only supported by conan create command. The conan install --build command is not supported.

In the following links you can find some examples about how to use a conan docker runner: