Configuration reference

This page documents configuration options for self-hosted Wave deployments. If you are using Wave as a service, these configuration options do not apply to your setup.

Configure Wave by setting YAML values in the config.yml configuration file:

wave:
    mail:
        from: "wave-app@seqera.io"

Configuration paths in this reference use dot notation to represent nested YAML keys. In the example above, the from value nested under the mail section is referenced as wave.mail.from.

You can configure Wave using either the config.yml file or environment variables. Environment variables are provided where available, though not all configuration options support them.

General

Configure general Wave application settings, such as application name, port, anonymous access permissions, and platform URLs with the following options:

tower.endpoint.url (optional)

Specifies the URL pointing to the Seqera platform API service (default: https://api.cloud.seqera.io). Can be set using the ${TOWER_ENDPOINT_URL} environment variable.

wave.allowAnonymous (required)

Enables anonymous access to the Wave server (default: false).

Modify this option based on your security requirements.

wave.denyPaths (optional)

Filter out API calls for specific artifacts, like manifests, that don't exist.

wave.server.url (required)

Specifies the URL for the Wave server. Can be set using the ${WAVE_SERVER_URL} environment variable.

wave.tokens.cache.duration (optional)

Sets the duration for cached tokens generated by Wave (default: 1h).

Container registry

Wave uses the generic format wave.registries.<REGISTRY_NAME>.username and wave.registries.<REGISTRY_NAME>.password for registry authentication. You must specify all repositories used in your Wave installation.

The examples below show standard formats for known registries, but you can customize the registry name (for example, change azurecr.io to seqeralabs.azurecr.io).

note

You can also define container registry credentials in the config.yml file. These configurations enable Wave authentication for repositories used to push or pull artifacts.

Configure container registry authentication with the following options:

wave.registries.<AWS_ECR_REPO_NAME>.password (optional)

Specifies the AWS ECR password for authentication. For example: 195996028523.dkr.ecr.eu-west-1.amazonaws.com. Can be set using the ${AWS_SECRET_ACCESS_KEY} environment variable.

wave.registries.<AWS_ECR_REPO_NAME>.username (optional)

Specifies the AWS ECR (Elastic Container Registry) username for authentication. For example, 195996028523.dkr.ecr.eu-west-1.amazonaws.com. Can be set using the ${AWS_ACCESS_KEY_ID} environment variable.

wave.registries.default (optional)

Sets the default container registry for Wave (default: docker.io).

wave.registries.docker.io.password (optional)

Specifies the Docker Hub password or PAT (Personal Access Token) for authentication. Can be set using the ${DOCKER_PAT} environment variable.

wave.registries.docker.io.username (optional)

Specifies the Docker Hub username for authentication. Can be set using the ${DOCKER_USER} environment variable.

wave.registries.quay.io.password (optional)

Specifies the Quay.io password or PAT for authentication. Can be set using the ${QUAY_PAT} environment variable.

wave.registries.quay.io.username (optional)

Specifies the Quay.io username for authentication. Can be set using the ${QUAY_USER} environment variable.

HTTP client

Configure the HTTP client with the following options:

wave.httpclient.connectTimeout (optional)

Sets the connection timeout for the HTTP client (default: 20s).

wave.httpclient.retry.attempts (optional)

Sets the number of HTTP client retry attempts (default: 5).

wave.httpclient.retry.delay (optional)

Sets the delay for HTTP client retries (default: 1s).

wave.httpclient.retry.jitter (optional)

Sets the jitter for HTTP client retries (default: 0.25).

wave.httpclient.retry.maxDelay (optional)

Sets the maximum delay for HTTP client retries.

wave.httpclient.retry.multiplier (optional)

Sets the multiplier for HTTP client retries (default: 1.0).

Container build process

Configure how Wave builds container images and manages associated logs for monitoring, troubleshooting, and delivery with the following options:

wave.build.buildkit-image (required)

Sets the Buildkit container image used in the Wave build process (default: moby/buildkit:v0.13.2-rootless).

wave.build.cache (required)

Sets the container repository used to cache layers of images built by Wave.

wave.build.cleanup (optional)

Sets the cleanup strategy after the build process. For example, set to OnSuccess for cleanup only if a build is successful.

wave.build.compression (optional)

Sets which type of compression will be applied to cache layers (default: gzip). Options include: uncompressed,estargz, and zstd.

wave.build.force-compression (optional)

Enables forced compression for each cache layers produced by the build process (default: false).

wave.build.oci-mediatypes (optional)

Enables OCI media types in exported manifests (default: true).

wave.build.public-repo (optional)

Specifies a public repository for the container images built by Wave. Wave uses this repository when you freeze container images without specifying wave.build.repo. When not configured, you must specify wave.build.repo for freeze mode operations.

wave.build.repo (required)

Sets the Docker container repository for the container images built by Wave.

wave.build.singularity-image (optional)

Sets the Singularity image used in the build process (default: quay.io/singularity/singularity:v3.11.4-slim).

wave.build.singularity-image-arm64 (optional)

Sets the ARM64 version of the Singularity image for the build process (default: quay.io/singularity/singularity:v3.11.4-slim-arm64).

wave.build.status.delay (optional)

Sets the delay between build status checks (default: 5s).

wave.build.status.duration (optional)

Sets the duration for build status checks (default: 1d).

wave.build.timeout (optional)

Sets the maximum duration for the build process (default: 5m).

wave.build.trusted-timeout (optional)

Sets the maximum duration for the build process when you are authenticated and freeze mode is enabled (default: 10m). If set to less than wave.build.timeout, the longer wave.build.timeout value is used.

wave.build.workspace (required)

Sets the path to the directory used by Wave to store artifacts such as Containerfiles, Trivy cache for scan, Buildkit context, and authentication configuration files. For example, /efs/wave/build.

Build process logs

Configure how Wave stores and delivers build logs from containers and Kubernetes pods, which can be retrieved later or included in build completion emails, with the following options:

wave.build.locks.path (required)

Sets the path inside wave.build.logs.bucket where Wave will store conda lock files.

wave.build.logs.bucket (required)

Sets the AWS S3 bucket where Wave will store build process logs.

wave.build.logs.maxLength (optional)

Determines the maximum number of bytes that can be read from a log file. If a log file exceeds this limit, it will be truncated (default: 100000 (100 KB)).

wave.build.logs.path (required)

Sets the path inside wave.build.logs.bucket where Wave will store build logs.

wave.build.logs.prefix (optional)

Sets the prefix for build process log files in the specified S3 bucket.

Kubernetes container build process

Configure Kubernetes-specific settings for Wave, where build and scan processes share most configurations except for CPU and memory requirements, with the following options:

wave.build.k8s.labels (optional)

Sets labels on Wave build Kubernetes pods.

wave.build.k8s.namespace (required)

Sets the Kubernetes namespace where Wave will run its build pods.

wave.build.k8s.node-selector (optional)

Sets the node selector for Wave build Kubernetes pods.

wave.build.k8s.resources.requests.cpu (optional)

Sets the CPU resources to allocate to Wave build processes. For example, set to 2 (2 CPU cores) or 1500Mi (1.5 CPU cores).

wave.build.k8s.resources.requests.memory (optional)

Sets the memory resources to allocate to Wave build processes. For example, set to 3Gi (3 Gigabytes) or 2000Mi (2000 Megabytes).

wave.build.k8s.service-account (optional)

Specifies the Kubernetes service account name to be used by Wave build pods.

wave.build.k8s.storage.claimName (optional)

Sets the volume claim name for the Wave build Kubernetes pods.

wave.build.k8s.storage.mountPath (optional)

Sets the volume mount path on Wave build Kubernetes pods.

Container scan process

Configure how Wave's vulnerability scanning process uses a Trivy docker image with customizable tags and severity levels with the following options:

wave.scan.enabled (optional)

Enables vulnerability scanning (default: true).

wave.scan.image.name  (optional)

Sets the Trivy docker image to use for container security scanning (default: aquasec/trivy:0.47.0).

wave.scan.reports.path (required)

Sets the path inside the S3 bucket where Wave will store SBOM reports. For example, s3://wave-store/scan-reports.

wave.scan.severity (optional)

Sets the severity levels to report in vulnerability scanning.

Options include: MEDIUM,HIGH, and CRITICAL.

Kubernetes Wave scan process

Configure Wave scanning process resource requirements for Kubernetes deployments with the following options:

wave.scan.k8s.resources.requests.cpu (optional)

Sets the amount of CPU resources allocated to Wave scan processes. For example, set to 2 (2 CPU cores) or 1500Mi (1.5 CPU cores).

wave.scan.k8s.resources.requests.memory (optional)

Sets the memory resources allocated to Wave scan processes. For example, set to 3Gi (3 Gigabytes) or 2000Mi (2000 Megabytes).

Rate limits

Configure how Wave controls rate limits for anonymous and authenticated user access with the following options:

rate-limit.build.anonymous (required)

Sets the rate limit for build requests from anonymous users (default: 25 build requests per day (25/1d); max: 25).

rate-limit.build.authenticated (required)

Sets the rate limit for build requests from authenticated users (default: 100 build requests per hour (100/1h); max: 100).

rate-limit.pull.anonymous (required)

Sets the rate limit for anonymous pull requests from anonymous users (default: 250 pull requests per hour (250/1h); max: 250).

rate-limit.pull.authenticated (required)

Sets the rate limit for authenticated pull requests from authenticated users (default: 2k pull requests per minute (2000/1m); max: 2k).

Database and cache

Wave uses external database and caching services to store application data and improve performance.

Redis

Configure Redis with the following options:

redis.client.timeout (optional)

Sets the timeout duration (in milliseconds) for Redis client operations (default: 5000 (5 seconds)).

redis.password (optional)

Specifies the password used to authenticate with the Redis server. Can be set using the ${REDIS_PASSWORD} environment variable.

redis.pool.enabled (optional)

Enables the Redis pool (default: true).

redis.pool.maxIdle (optional)

Sets the maximum number of idle connections to maintain in the Redis connection pool (default: 10).

redis.pool.maxTotal (optional)

Sets the maximum number of connections that can be maintained in the Redis connection pool (default: 50).

redis.pool.minIdle (optional)

Sets the minimum number of idle connections to maintain in the Redis connection pool (default: 0).

redis.uri (required)

Specifies the URI for connecting to Redis (default format: redis://${REDIS_HOST:redis}:${REDIS_PORT:6379}). Can be set using the ${REDIS_URI} environment variable.

PostgreSQL

Configure PostgreSQL with the following options:

wave.db.password (required)

Specifies the password for the PostgreSQL database user. Can be set using the ${WAVE_DB_PASSWORD} environment variable.

wave.db.uri (required)

Specifies the JDBC connection string for the PostgreSQL database. For example, jdbc:postgresql://localhost:5432/wave. Can be set using the ${WAVE_DB_URI} environment variable.

wave.db.user (required)

Specifies the username for authenticating with the PostgreSQL database. Can be set using the ${WAVE_DB_USER} environment variable.

Blob cache

Configure how Wave caches container blobs to improve client performance and optionally delegates transfer tasks to Kubernetes pods for scalability with the following options:

wave.blobCache.baseUrl (optional)

Specifies the URL, which will override the base URL (part of URL before the blob path) of blobs sent to the end client.

wave.blobCache.cloudflare.lifetime (optional)

Sets the validity of the Cloudflare WAF token.

wave.blobCache.cloudflare.secret-key (optional)

Specifies the Cloudflare secret to create the WAF token.

wave.blobCache.cloudflare.urlSignatureDuration (optional)

Sets the validity of the AWS S3 URL signature (default: 30m).

wave.blobCache.enabled (optional)

Enables the blob cache (default: false).

wave.blobCache.requestsCpu (optional)

Sets the amount of CPU resources allocated to the k8s pod used for blob binary transfers.

wave.blobCache.requestsMemory (optional)

Sets the memory resources allocated to the k8s pod used for blob binary transfers.

wave.blobCache.s5cmdImage (optional)

Sets the container image that supplies the s5cmd tool to upload blob binaries to the S3 bucket (default: public.cr.seqera.io/wave/s5cmd:v2.2.2).

wave.blobCache.signing-strategy (optional)

Sets the URL signing strategy for different services. Currently supports AWS S3 and Cloudflare service. Options include: aws-presigned-url and cloudflare-waf-token.

wave.blobCache.status.delay (optional)

Sets the time delay in checking the status of the transfer of the blob binary from the repository to the cache (default: 5s).

wave.blobCache.status.duration (optional)

Sets the time for which Wave will store the blob binary in cache (default: 5d).

wave.blobCache.storage.accessKey (optional)

Specifies the access key (part of credentials) to access the resources of the service used for caching.

wave.blobCache.storage.bucket (required)

Sets the name of Cloudflare or S3 bucket. For example, s3://wave-blob-cache.

wave.blobCache.storage.endpoint (optional)

Specifies the URL for the storage location for the download or upload of blob binaries.

wave.blobCache.storage.region (required)

Sets the AWS region where the bucket is created.

wave.blobCache.storage.secretKey (optional)

Specifies the secret key (part of credentials) to access the resources of the service used for caching.

wave.blobCache.timeout (optional)

Sets the timeout for blob binary transfer, after which Wave will throw a TransferTimeoutException exception (default: 5m).

Email configuration

Configure how Wave sends email notifications on behalf of the service with the following options:

mail.from (required)

Specifies the sender's email address for Wave notifications. Can be set using the ${MAIL_FROM} environment variable.

Metrics

Configure how Wave Metrics service provides data about container builds and pulls per organization and date with the following options:

wave.metrics.enabled (optional)

Enables Wave metrics (default: false).

Accounts

Configure user credentials for accessing authenticated Wave APIs and services with the following options:

wave.accounts (required)

Sets a list of credentials to access authenticated Wave APIs like metrics APIs. Format of the credential list: - <USERNAME>:<PASSWORD_CHECKSUM>