Engine Configuration

import { daggerVersion } from '../../partials/version.js';

Dagger is designed to be run out-of-the-box with sensible defaults. However, even with these defaults, it may sometimes be necessary to modify various settings.

To do so, there are two configuration mechanisms: using Dagger's engine.json file (introduced in v0.15.0), or using the legacy BuildKit-style engine.toml file. The engine.json file is a configuration file that follows the Engine configuration file schema, while the legacy engine.toml file uses BuildKit's configuration syntax).

:::note Some options are not yet supported by the newer engine.json, so the legacy engine.toml will need to be used for those. :::

If an option is specified in both engine.json and in engine.toml, then the engine.json settings will take precedence.

Configuration

Then, when the Dagger Engine is automatically started from a dagger command, it will pull in that configuration. Changes after the Dagger Engine has already been created and is running will not automatically apply to the new Engine. To reapply the config after changing it, you'll need to manually stop the Engine.

docker rm -f $(docker ps -q --filter "name=dagger-engine-*")

If you are not using an automatically provisioned Dagger Engine, and have followed the steps to setup a custom runner, then you'll need to manually mount your engine.json to the engine container's filesystem at /etc/dagger/engine.json. For example:

To configure with engine.toml, the engine.toml file needs to be manually mounted to /etc/dagger/engine.toml. For example:

Logging

Dagger supports various log verbosity levels. The default level is to enable debug.

For example, to only show logs of level warn and above:

{
  "logLevel": "error"
}

debug = true

Conversely, to disable debug logging:

debug = false

To enable trace logging:

trace = true

Conversely, to explicitly disable debug logging (the default):

trace = false

Security

By default, Dagger has an open security policy. This policy allows exec operations to access the insecureRootCapabilities options, which effectively allows all operations root access (similar to docker run's --privileged` flag.

This capability can be disabled to lock down a Dagger installation.

{
  "security": {
    "insecureRootCapabilities": true
  }
}

To disable the use of insecureRootCapabilities:

{
  "security": {
    "insecureRootCapabilities": false
  }
}

insecure-entitlements = ["security.insecure"]

To disable the use of insecureRootCapabilities, explicitly set insecure-entitlements to the empty array:

insecure-entitlements = []

:::important ROOTLESS MODE "Rootless mode" means running the Dagger Engine as a container without the --privileged flag. In this case, the container would not run as the root user of the system. Currently, the Dagger Engine cannot be run as a rootless container; network and filesystem constraints related to rootless usage would currently significantly limit its capabilities and performance. :::

Garbage collection

The Dagger Engine caches various operations to improve speed on subsequent runs of the same workflow.

The Dagger garbage collector runs in the background, looking for unused layers and artifacts, and clears them up once they exceed the storage allowed by the cache policy. This prevents the cache from getting too large and consuming too much of the available disk space.

:::warning Take care when configuring the garbage collector manually, and ensure not to accidentally configure it to clean up all cache, since this will severely impact performance. :::

{
    "gc": {
        "enabled": false
    }
}

[worker.oci]
gc = false

The default cache policy attempts to keep the long-term cache storage under 75% of the total disk, while also ensuring that at least 20% of the disk remains free for other applications and tools. The cache policy can be further tweaked to allow more fine-grained policies.

Each policy defines the amount of space if can consume using the following parameters:

• maxUsedSpace is the maximum amount of disk space that may be used by this buildkit worker - any usage above this threshold will be reclaimed during garbage collection.
• reservedSpace is the minimum amount of disk space guaranteed to be retained by this buildkit worker - any usage below this threshold will not be reclaimed during garbage collection.
• minFreeSpace is the target amount of free disk space that the garbage collector will attempt to leave empty - however, it will never be bought below reservedSpace.
• sweepSize defines the amount of space that should be collected on a single pass of the garbage collector. When set as a percentage, it's the percentage of the range of space allowed between reservedSpace and maxUsedSpace.

All disk space parameters can be an integer number of bytes (e.g. 512000000), a string with a unit (e.g. "512MB"), or a string percentage of the total disk space (e.g. "10%")

{
  "gc": {
    "maxUsedSpace": "200GB",
    "reservedSpace": "10GB",
    "minFreeSpace": "20%",
    "sweepSize": "50%"
  }
}

[worker.oci]
maxUsedSpace = "200GB"
reservedSpace = "10GB"
minFreeSpace = "20%"

Note that sweepSize is a dagger engine.json specific setting.

The top level configuration fields (as defined above) for the garbage collector set the default policy - more specific fine-grained policies are then generated from this. These more fine-grained policies can also be specified; however, the defaults for this are generally reasonable for most use-cases.

Each policy takes the same disk space parameters as above, as well as the following filtering tools:

• all is a boolean, that when set to true matches every cache record.
• keepDuration is a duration, that matches cache records older than the given amount (e.g. 30s, 5m, 4h).

{
  "gc": {
    "policies": [
      {
        "keepDuration": "6h",
        "maxUsedSpace": "200GB",
        "reservedSpace": "10GB",
        "minFreeSpace": "20%"
      },
      {
        "all": true,
        "maxUsedSpace": "50GB",
        "reservedSpace": "10GB",
        "minFreeSpace": "20%"
      }
    ]
  }
}

[worker.oci]
  keepDuration = "6h"
  maxUsedSpace = "200GB"
  reservedSpace = "10GB"
  minFreeSpace = "20%"

  [[worker.oci.gcpolicy]]
  keepDuration = "6h"
  maxUsedSpace = "50GB"
  reservedSpace = "10GB"
  minFreeSpace = "20%"

Custom registries

Dagger can be configured to use container registry mirrors for any registry URL. This allows container images that refer to one registry to instead be redirected to a different one.

For example, to mirror the default Docker Hub docker.io registry to mirror.gcr.io:

{
  "registries": {
    "docker.io": {
      "mirrors": ["mirror.gcr.io"]
    }
  }
}

To test the configuration:

dagger -M call --progress=plain container \
  from --address=hello-world \
  with-exec --args=/hello \
  stdout

The specified hello-world container will now be pulled from the mirror instead of from Docker Hub.

If your registry needs custom ca certificates, you can configure them as explained here and reference them:

{
  "registries": {
	"my.custom.registry": {
	  "ca": ["/usr/local/share/ca-certificates/my-custom-ca.crt"]
	}
  }
}

[registry."docker.io"]
  mirrors = ["mirror.gcr.io"]

The configuration can be repeated for multiple registries and mirrors if needed:

[registry."docker.io"]
  mirrors = ["mirror.a.com", "mirror.b.com"]

[registry."some.other.registry.com"]
  mirrors = ["mirror.foo.com", "mirror.bar.com"]

To test the configuration:

dagger -M call --progress=plain container \
  from --address=hello-world \
  with-exec --args=/hello \
  stdout

The specified hello-world container will now be pulled from the mirror instead of from Docker Hub.

:::note Verbose output may still show the canonical image reference (docker.io/...). That's expected: the mirror is used by the registry resolver, but Dagger reports the original image name. To verify that the mirror was contacted, check the mirror registry's access logs. :::

Custom proxy

Currently, custom proxies cannot be configured through engine.json or engine.toml, and must be configured separately.

Custom certificate authorities

Currently, custom certificate authorities cannot be configured through engine.json or engine.toml, and must be configured separately.