diff --git a/docs/self-hosted.mdx b/docs/self-hosted.mdx new file mode 100644 index 000000000..7bfb95c43 --- /dev/null +++ b/docs/self-hosted.mdx @@ -0,0 +1,290 @@ +--- +title: Self-hosted installation +--- + +This documentation is about hosting your own version of the Wave service - not using the normal Seqera-hosted version of Wave to generate containers. + +### Requirements + +* Java 21 or later +* Linux or macOS +* Redis 6.2 (or later) +* Docker engine (for development) +* Kubernetes cluster (for production) + +**Notes** + +* Suggested instance type for Wave backend `m5a.2xlarge` +* This deployment does not support the build of ARM (Graviton) CPU architecture containers. + +### Get started + +1. Clone the Wave repository from GitHub: + +`git clone https://github.com/seqeralabs/wave && cd wave` + +2. Define one of more of those environment variable pairs depending the target registry you need to access: + +``` +export DOCKER_USER="" +export DOCKER_PAT="" +export QUAY_USER="" +export QUAY_PAT="" +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" +export AZURECR_USER="" +export AZURECR_PAT="" +``` + +3. Set up a [local tunnel](https://github.com/localtunnel/localtunnel) to make the Wave service accessible to the Docker client (only needed if you are running on macOS): + +`npx localtunnel --port 9090` + +4. Then configure the following variable in your environment using the domain name return by local tunnel, e.g.: + +`export WAVE_SERVER_URL="https://sweet-nights-report.loca.lt"` + +5. Run the service in your computer: + +`bash run.sh` + +6. Submit a container request to the Wave service using the `curl` tool: + +``` +curl \ + -H "Content-Type: application/json" \ + -X POST $WAVE_SERVER_URL/container-token \ + -d '{"containerImage":"ubuntu:latest"}' \ + | jq -r .targetImage +``` + +7. Pull the container image using the name returned in the previous command, for example: + +`docker pull sweet-nights-report.loca.lt/wt/617e7da1b37a/library/ubuntu:latest` + +**Note** You can use the [Wave](https://github.com/seqeralabs/wave-cli) command line tool instead of `curl` to interact with the Wave service and submit more complex requests. + +## Debugging + +To debug http requests made proxy client add the following Jvm setting: + +`'-Djdk.httpclient.HttpClient.log=requests,headers'` + +## Comprehensive installation + +Build and augment container images for Nextflow workflows. + +### Requirements + +* AWS EKS cluster +* AWS OpenID Connect (OIDC) provider for EKS +* AWS S3 bucket for logs +* AWS EFS for shared files +* AWS EFS CSI driver for EKS +* AWS Application Load Balancer +* AWS Certificate Manager +* AWS SES (simple email service) +* AWS ECR service +* AWS Elasticache +* AWS Route53 + +### AWS EKS preparation + +* Create a EKS cluster instance following the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html). When the cluster is ready create a new Kubernetes namespace where the Wave service is going to be deployed e.g. `wave-production`. +* Create an AWS S3 bucket in the same region where the EKS cluster is running. The bucket will host Wave logs, e.g. `wave-logs-prod`. +* Create an EFS file system instance as described in the [AWS documentation](https://docs.aws.amazon.com/efs/latest/ug/gs-step-two-create-efs-resources.html). Make sure to use the same VPC used for the EKS cluster and [EFS CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html) for EKS. Also make sure Your EFS file system's security group must have an inbound and outbound rule that allows NFS traffic from the CIDR for your cluster's VPC. Allow port 2049 for inbound and outbound traffic. +* Create AWS Certificate to allow HTTPS traffic to your Wave service by using the AWS Certificate Manager. The certificate should be in the same region where the EKS cluster is running. See the [AWS documentation](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) for further details. +* Create two container repositories in the same region where the container is deployed. The first repository is used to host the container images built by Wave and the second one will be used for caching purposes. Make sure to create two repository have the same name prefix e.g. `wave/build` and `wave/cache`. +* Create an AWS Elasticache instance used by Wave for caching purposes. It's required the use of a single-node cluster. For production deployment it's adviced the used of instance type `cache.t3.medium` and using Redis 6.2.x engine version or later (serverless is not supported). Make sure to use the same VPC used for the EKS cluster. +* The AWS SES service is required by Wave to send email notification. Make sure to have configured a AWS SES service for production usage. See the [AWS documentation](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) for further details. + +### AWS policy and role creation + +Create an AWS IAM policy that will grant access to the AWS infrastructure to the Wave application. This requires your cluster to have an existing AWS Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your EKS cluster. To determine whether you already have one, or to create one, see [Creating an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html). + +1. Make sure the file `settings.sh` have a valid value for the following settings: + * `AWS_REGION`: The AWS region where your cluster is deployed e.g. `eu-central-1`. + * `AWS_ACCOUNT`: The ID of the AWS account where the cluster is deployed. + * `WAVE_CONFIG_NAME`: The name for this Wave deployment e.g. `seqera-wave`. + * `WAVE_LOGS_BUCKET`: The S3 bucket for storing Wave logs, created in the previous step. + * `WAVE_CONTAINER_NAME_PREFIX`: The name prefix given the build cache ECR repository e.g. `wave` + * `AWS_EKS_CLUSTER_NAME`: The name of the cluster name where the service is going to be deployed. + * `WAVE_NAMESPACE`: The Kubernetes namespace where the Wave service is going to be deployed e.g. `wave-test`. + * `WAVE_BUILD_NAMESPACE`: The Kubernetes namespace where container build jobs will be executed e.g. `wave-build`. +2. Create the IAM policy using the template included in this repo with name `seqera-wave-policy.json` and using the command below: + +``` +source settings.sh + +aws \ + + --region $AWS_REGION \ + + iam create-policy \ + + --policy-name $WAVE_CONFIG_NAME \ + --policy-document file://<( cat policies/seqera-wave-policy.json | envsubst ) +``` + +Take note of the policy Arn show in the command result. Find your cluster's OIDC provider URL using the command below: + +``` +aws \ + + --region $AWS_REGION \ + + eks describe-cluster \ + + --name $AWS_EKS_CLUSTER_NAME \ + + --query "cluster.identity.oidc.issuer" \ + + --output text +``` + +An example output is as follows: + +`https://oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE` + + +Set the variable `AWS_EKS_OIDC_ID` in the `settings.sh` using the ID value from your result. Then run the command below: + +``` +source settings.sh +aws \ + --region $AWS_REGION \ + iam create-role \ + --role-name $WAVE_CONFIG_NAME \ + --assume-role-policy-document file://<( cat policies/seqera-wave-role.json | envsubst ) +``` + +Take note of the Arn of the IAM role created and use it as value for the variable `AWS_IAM_ROLE` in the `settings.sh` file. + +Finally, attach to the role the policy created in the previous step, using the command below: + +``` +source settings.sh + +aws \ + + --region $AWS_REGION \ + + iam attach-role-policy \ + + --role-name $WAVE_CONFIG_NAME \ + + --policy-arn arn:aws:iam::$AWS_ACCOUNT:policy/$WAVE_CONFIG_NAME +``` + +## Deployment + +### Kubernetes manifests preparation + +Update the variables in the file `settings.sh` with the values corresponding your AWS infrastructure created in the previous step. The following settings are required: + +* `WAVE_HOSTNAME`: The host name to use to access the Wave service e.g. `wave.your-company.com`. This should match the host name used when creating the HTTPS certificate by using AWS Certificate manager. +* `WAVE_CONTAINER_BUILD_REPO`: The ECR repository name used to host the containers built by Wave e.g. `<YOUR ACCOUNT>.dkr.ecr.<YOUR REGION>.amazonaws.com/wave/build`. +* `WAVE_CONTAINER_CACHE_REPO`: The ECR repository name used to cache the containers built by Wave e.g. `<YOUR ACCOUNT>.dkr.ecr.<YOUR REGION>.amazonaws.com/wave/cache`. +* `WAVE_LOGS_BUCKET`: The AWS S3 bucket used to store the Wave logs e.g. `wave-logs-prod`. +* `WAVE_REDIS_HOSTNAME`: The AWS Elasticache instance hostname and port e.g. `<YOUR ELASTICACHE INSTANCE>.cache.amazonaws.com:6379`. +* `WAVE_SENDER_EMAIL`: The email address that will be used by Wave to send email e.g. `wave-app@your-company.com`. Note: it must an email address validated in your AWS SES setup. +* `TOWER_API_URL`: The API URL of your Seqera Platform installation e.g. `<https://your-platform-hostname.com>/api`. +* `AWS_EFS_VOLUME_HANDLE`: The AWS EFS shared file system instance ID e.g. `fs-12345667890` +* `AWS_CERTIFICATE_ARN`: The arn of the AWS Certificate created during the environment preparation e.g. `arn:aws:acm:<YOUR REGION>:<YOUR ACCOUNT>:certificate/<YOUR CERTIFICATE ID>` +* `AWS_IAM_ROLE`: The arn of the AWS IAM role granting permissions to AWS resources to the Wave service. +* `SURREAL_DB_PASSWORD`: User defined password to be used for embedded Surreal DB deployed by Wave. +* `SEQERA_CR_USER`: The username to access the Seqera container registry to providing the images for installing Wave service +* `SEQERA_CR_PASSWORD`: The password to access the Seqera container registry to providing the images for installing Wave service + +### Application deployment + +Once the application manifest files have been updated replacing the above variables with the corresponding values, proceed with the application deployment following those steps: + +1. Export the content of the `settings.sh` file in your environment using this command: + + `source settings.sh` + +2. Create storage, app namespace and roles: + + `kubectl apply -f <(cat src/create.yml | envsubst)` + `kubectl config set-context --current --namespace=${WAVE_NAMESPACE}` + +3. Set up the Container registry credentials to access the Wave container image: + +``` +kubectl create secret \ + + docker-registry seqera-reg-creds \ + + --namespace "${WAVE_NAMESPACE}" \ + + --docker-server=cr.seqera.io \ + + --docker-username="${SEQERA_CR_USER}" \ + + --docker-password="${SEQERA_CR_PASSWORD}" +``` + +4. Create build storage and namespace: + + `kubectl apply -f <(cat src/build.yml | envsubst)` + +5. Deploy Surreal DB: + + `kubectl apply -f <(cat src/surrealdb.yml | envsubst)` + +6. Deploy the main application resources: + + `kubectl apply -f <(cat src/app.yml | envsubst)` + +7. Deploy the Ingress controller: + + `kubectl apply -f <(cat src/ingress.yml | envsubst)` + +The ingress controller will automatically create an AWS application load balancer to serve the Wave service traffic. The load balancer address can be retrieved using the following command: + +`kubectl get ingress wave-ingress -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'` + +Use the load balancerhostname to create an *alias* record in your Route53 DNS so that the Wave service hostname is mapped to the load balancer hostname created by the ingress. See the [AWS documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer.html) for details. + +Once the DNS is configured verify the Wave API is accessible using this command: + +`curl https://${WAVE_HOSTNAME}/service-info | jq` + +8. Pair Seqera Platform with Wave + +Once the Wave service is ready, you will need to configure the Seqera Platform to pair with the Wave service in your infrastructure. Follow the documentation available at [this link](https://docs.seqera.io/platform/latest/enterprise/configuration/wave) replacing the Wave endpoint `https://wave.seqera.io` with the one defined in your installation. + +9. Verify the service is operating correctly. Check the Wave pod logs. There should not be any errors and it should be reported the line: + +`Opening pairing session - endpoint: ` + +10. Sign in to the Seqera Platform and create a Personal access token. Then export the token value as shown below: + +`export TOWER_ACCESS_TOKEN=` + +3. Download the [Wave CLI](https://github.com/seqeralabs/wave-cli) tool, and use it request a Wave container using the command below: + +``` +wave \ + + --wave-endpoint https://$WAVE_HOSTNAME \ + + --tower-endpoint $TOWER_API_URL \ + + --image alpine:latest +``` + +It will show the Wave container name for the requested `alpine` image. You should be able to pull the container using a simple `docker pull ` command. To verify the Wave build is working as expected run: + +``` +wave \ + + --wave-endpoint https://$WAVE_HOSTNAME \ + + --tower-endpoint $TOWER_API_URL \ + + --conda-package cowpy +``` + +You should receive an email notification when the Wave build process completes and the container is ready to be pulled. diff --git a/docs/self_hosted_configuration.mdx b/docs/self_hosted_configuration.mdx new file mode 100644 index 000000000..6e293ef1d --- /dev/null +++ b/docs/self_hosted_configuration.mdx @@ -0,0 +1,184 @@ +--- +title: Wave application configuration +--- + +Set Wave configuration values using environment variables or in the `config.yml` configuration file. + +### config.yml configuration + +Declare YAML configuration values in `config.yml`: + +``` +wave: + mail: + from: "wave-app@seqera.i +``` + +YAML configuration keys on this page are listed in "dot" notation, i.e., the `mail from` value in the snippet above is represented as `wave.mail.from` in the tables that follow. Environment variables for various attributes has been listed in third column, either you can provide those attributes values in config.yml or using corresponding environment variable. + + +## General configuration + +General configuration options such as wave application name, port, whether to allow anonymous access (without tower token), wave and Seqera platform url. + +- `micronaut.application.name`: The name of the Wave application. By default, it is set to `wave-app`. *Optional*. +- **`micronaut.server.port`**: the port used by the Wave server. The default port is `8080`. *Optional*. +- **`wave.allowAnonymous`**: Specifies whether anonymous access to the Wave server is permitted. By default, it is set to `false`, meaning authentication is required. Change this option based on your security requirements. *Mandatory*. +- **`wave.server.url`**: The URL for the Wave server. You can also set it using `${WAVE_SERVER_URL}` environment variable. *Optional*. +- **`wave.tokens.cache.duration`**: the duration for cached tokens generated by Wave. The default is `1h`, and you can modify it according to your token caching preferences. *Optional*. +- **`tower.endpoint.url`**: The URL pointing to the Seqera platform API service. The default is pointing to Seqera hosted platform [https://api.cloud.seqera.io](https://api.cloud.seqera.io). *Optional*. +- **`logger.levels.io.seqera`**: The [logger level](https://logging.apache.org/log4j/2.x/manual/customloglevels.html) for the `io.seqera` package. By default, it is set to `TRACE`, providing detailed logging. Adjust this based on logging requirements. *Optional*. + +## Container registry configuration + +The generic format for the attributes is `wave.registries.<registry_name>.username` and `wave.registries..password`. You need to specify all the repositories you will use in the respective wave installation. Below are the standard format for known registries, but you can change registry name `(azurecr.io)` to specific one like `seqeralabs.azurecr.io `. + +**Note**: Container registry credentials can be defined in `[config.yml](http://./config.yml)` too. These configurations are important for the wave authentication to the repositories used to push or pull artifacts. + +- **`wave.registries.default`**: the default Docker registry for Wave. The default is `docker.io`, and it represents the Docker Hub. *Optional*. +- **`wave.registries.docker.io.username`**: the Docker Hub username for authentication. It can be set using `${DOCKER_USER}` environment variable. *Optional*. +- **`wave.registries.docker.io.password`**: the Docker Hub password or PAT (Personal Access Token) for authentication. It can be set using `${DOCKER_PAT}` environment variable. *Optional*. +- **`wave.registries.quay.io.username`**: the Quay.io username for authentication. It can be set using `${QUAY_USER}` environment variable. *Optional*. +- **`wave.registries.quay.io.password`**: the Quay.io password or PAT for authentication. It can be set using `${QUAY_PAT}` environment variable. *Optional*. +- **`wave.registries..username`**: the AWS ECR (Elastic Container Registry) username for authentication. An example AWS ECR Repo name is `195996028523.dkr.ecr.eu-west-1.amazonaws.com`. It can be set using `${AWS_ACCESS_KEY_ID}` environment variable. *Optional*. +- **`wave.registries..password`**: the AWS ECR password for authentication. An example AWS ECR Repo name is `195996028523.dkr.ecr.eu-west-1.amazonaws.com`. It can be set using `${AWS_SECRET_ACCESS_KEY}` environment variable. *Optional*. +- **`wave.registries..username`**: the Azure Container Registry username for authentication. An example of an Azure Container Registry Repo name is `seqeralabs.azurecr.io`. It can be set using `${AZURECR_USER}` environment variable. *Optional*. +- **`wave.registries..password`**: the Azure Container Registry password or PAT for authentication. An example of an Azure Container Registry Repo name is `seqeralabs.azurecr.io`. It can be set using `${AZURECR_PAT}` environment variable. *Optional*. + +## HTTP client configuration + +- **`wave.httpclient.connectTimeout`**: sets the connection timeout for the HTTP client. Its default value is `20s`. *Optional*. +- **`wave.httpclient.retry.delay`**: sets the delay for HTTP client retries. Its default value is `1s`. *Optional*. +- **`wave.httpclient.retry.attempts`**: defines the number of HTTP client retry attempts. Its default value is `5`. *Optional*. +- **`wave.httpclient.retry.maxDelay`**: sets the maximum delay for HTTP client retries. *Optional*. +- **`wave.httpclient.retry.jitter`**: introduces jitter for HTTP client retries. Its default value is `0.25`. *Optional*. +- **`wave.httpclient.retry.multiplier`**: defines the multiplier for HTTP client retries. Its default value is `1.0`. *Optional*. +- **`micronaut.http.services.stream-client.read-timeout`**: sets the read timeout for the streaming HTTP client. Its default value is `30s`. *Optional*. +- **`micronaut.http.services.stream-client.read-idle-timeout`**: configures the read idle timeout for the streaming HTTP client. Its default value is `120s`.*Optional*. + +## Container build process configuration + +- **`wave.build.timeout`**: the timeout for the build process. Its default value is `5m` (5 minutes), providing a reasonable time frame for the build operation. *Optional*. +- **`wave.build.workspace`**: defines the path to the directory used by Wave to store artifacts such as Dockerfiles, Trivy cache for scan, Buildkit context, authentication configuration files, etc. For example, `/efs/wave/build`. *Mandatory*. +- **`wave.build.cleanup`**: determines the cleanup strategy after the build process. Options include `OnSuccess`, meaning cleanup occurs only if the build is successful. *Optional*. +- **`wave.build.buildkit-image`**: specifies the [Buildkit](https://github.com/moby/buildkit) Docker image used in the Wave build process. The default is `moby/buildkit:v0.13.2-rootless`. *Optional*. +- **`wave.build.singularity-image`**: sets the [Singularity](https://quay.io/repository/singularity/singularity?tab=tags) image used in the build process. The default is `quay.io/singularity/singularity:v3.11.4-slim`. *Optional*. +- **`wave.build.singularity-image-arm64`**: the ARM64 version of the Singularity image for the build process. The default is `quay.io/singularity/singularity:v3.11.4-slim-arm64`. *Optional*. +- **`wave.build.repo`**: specifies the Docker container repository for the Docker images built by Wave. This setting is required to define where the images will be stored. *Mandatory*. +- **`wave.build.cache`**: determines the Docker container repository used to cache layers of images built by Wave. *Mandatory*. +- **`wave.build.status.delay`**: sets the delay between build status checks. Its default value is `5s`, providing a reasonable interval for status checks. *Optional*. +- **`wave.build.status.duration`**: defines the duration for build status checks. Its default value is `1d` (1 day), indicating how long the system should check the build status. *Optional*. +- **`wave.build.public`**: indicates whether the Docker container repository is public. If set to true, Wave freeze will prefer this public repository over `wave.build.repo`. *Optional*. +- **`wave.build.oci-mediatypes`**: defines whether to use OCI mediatypes in exported manifests. Its default value is `true`. *Optional*. +- **`wave.build.compression`**: defines which type of compression will be applied to cache layers. Its default value is `gzip`, and other options are `uncompressed|estargz|zstd`. *Optional*. +- **`wave.build.force-compression`**: determines whether to force the compression for each cache layer produced by the build process. The default is `false`, enabling compression for more efficient storage. *Optional*. + +### Build process logs configuration + +This configuration specifies attributes for the persistence of the logs fetched from containers or k8s pods used for building requested images, which can be accessed later and also attached to the build completion email. + +- **`wave.build.logs.bucket`**: the AWS S3 bucket where Wave will store build process logs. *Mandatory*. +- **`wave.build.logs.prefix`**: sets the prefix to be used for build process log files in the specified S3 bucket. *Optional*. +- **`wave.build.logs.maxLength`**: 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. The default value is `100000` (100 KB). *Optional*. + +### Kubernetes configuration for container build process + +Kubernetes configuration has options specific for k8s, and most of them, except CPU and memory, are the same for the build and scan process. + +**Note**: only applies when using Kubernetes. + +- **`wave.build.k8s.namespace`**: the Kubernetes namespace where Wave will run its build pods. This is a required setting, specifying the namespace to isolate and manage the Wave build processes within the Kubernetes cluster. *Mandatory*. +- **`wave.build.k8s.storage.claimName`**: the volume claim name for the Wave build Kubernetes pods. *Optional*. +- **`wave.build.k8s.storage.mountPath`**: defines the volume mount path on Wave build Kubernetes pods. *Optional*. +- **`wave.build.k8s.labels`**: allows you to set labels on Wave build Kubernetes pods. *Optional*. +- **`wave.build.k8s.node-selector`**: configures the node selector for Wave build Kubernetes pods. *Optional*. +- **`wave.build.k8s.service-account`**: specifies the Kubernetes service account name to be used by Wave build pods. *Optional*. +- **`wave.build.k8s.resources.requests.cpu`**: sets the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) to allocate to Wave build processes. For example, it could be configured as `2` or `1500Mi` (1.5 CPU cores). *Optional*. +- **`wave.build.k8s.resources.requests.memory`**: determines the amount of [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) to allocate to Wave build processes. For instance, it could be set to `3Gi` or `2000Mi` (3 or 2000 Megabytes). *Optional*. + +## Container scan process configuration + +Scan process configuration lets the user provide a [Trivy docker image](https://hub.docker.com/r/aquasec/trivy) with any tag and severity levels of vulnerability that need to be scanned. + +- **`wave.scan.enabled`**: specifies whether vulnerability scanning is enabled or disabled. It's `false` by default and can be enabled by changing it to `true`. *Optional*. +- **`wave.scan.severity`**: the [severity levels](https://aquasecurity.github.io/trivy/v0.22.0/vulnerability/examples/filter/) to report in vulnerability scanning. For example, you can configure it with `MEDIUM,HIGH,CRITICAL` to include vulnerabilities of these severity levels in the scan report. *Optional*. +- **`wave.scan.image.name`**: the [Trivy docker image](https://hub.docker.com/r/aquasec/trivy) used for container security scanning. The default value is `aquasec/trivy:0.47.0`. This is the image that Wave will use to perform vulnerability scanning on containers. *Optional*. + +### Kubernetes configuration for Wave scan process + +Wave scan process uses the same k8s configuration of the build process except for CPU and memory requirements for the k8s pod. + +**Note**: only applies when using Kubernetes. + +- **`wave.scan.k8s.resources.requests.cpu`**: the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. For instance, you can set it to `2` or `1500Mi` (1.5 CPU cores). *Optional*. +- **`wave.scan.k8s.resources.requests.memory`**: the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. For example, it could be set to `3Gi` or `2000Mi` (3 or 2000 Megabytes). *Optional*. + +## Rate limit configuration + +Rate limit configuration controls the limits of anonymous and authenticated users' access to Wave. + +**Note**: Change these properties to tweak rate limits in wave. + +- **`rate-limit.build.anonymous`**: the rate limit for anonymous build requests. By default, it allows up to 10 build requests per hour (`10/1h`) from anonymous users. This setting controls the frequency at which anonymous users can trigger build processes in Wave. *Mandatory*. +- **`rate-limit.build.authenticated`**: the rate limit for authenticated build requests. By default, it allows up to 10 build requests per minute (`10/1m`) from authenticated users. This setting governs the rate at which authenticated users can initiate build processes in Wave. *Mandatory*. +- **`rate-limit.pull.anonymous`**: the rate limit for anonymous pull requests. It is set to allow up to 100 pull requests per hour (`100/1h`) from anonymous users by default. This setting controls how frequently anonymous users can perform pull operations in Wave. *Mandatory*. +- **`rate-limit.pull.authenticated`**: the rate limit for authenticated pull requests. By default, it allows up to 100 pull requests per minute (`100/1m`) from authenticated users. This setting governs the rate at which authenticated users can perform pull operations in Wave. *Mandatory*. +- **`wave.denyPaths`**: used to filter out API calls for specific artifacts like manifests, which don't exist. *Optional*. + +## Database and cache configuration + +- **`redis.uri`**: the Uniform Resource Identifier (URI) for connecting to Redis, a popular in-memory data store. By default, it uses the format `redis://${REDIS_HOST:redis}:${REDIS_PORT:6379}`, allowing customization of the Redis host and port through environment variables. *Mandatory*. +- **`redis.pool.enabled`**: whether to enable the Redis pool. It is set to `true` by default, enabling the use of a connection pool for efficient management of connections to the Redis server. *Optional*. +- **`redis.pool.minIdle`**: Specifies the minimum number of idle connections to maintain in the Redis connection pool. The default value is `0`. This ensures that connections are readily available for use. *Optional*. +- **`redis.pool.maxIdle`**: Specifies the maximum number of idle connections to maintain in the Redis connection pool. The default value is `10`. *Optional*. +- **`redis.pool.maxTotal`**: Specifies the maximum number of connections that can be maintained in the Redis connection pool. The default value is `50`. This helps to manage resource usage efficiently while supporting high demand. *Optional*. +- **`redis.client.timeout`**: Defines the timeout duration (in milliseconds) for Redis client operations. The default value is `5000` (5 seconds). *Optional*. +- **`redis.password`**: Specifies the password used to authenticate with the Redis server. This is needed when Redis authentication is enabled. *Optional*. +- **`surreal.default.ns`**: the namespace for the Surreal database. It can be set using `${SURREALDB_NS}` environment variable. *Mandatory*. +- **`surreal.default.db`**: the name of the Surreal database. It can be set using `${SURREALDB_DB}` environment variable. This setting defines the target database within the Surreal database system that Wave should interact with. *Mandatory*. +- **`surreal.default.url`**: the URL for connecting to the Surreal database. It can be set using `${SURREALDB_URL}` environment variable. This URL defines the endpoint that Wave uses to establish a connection with the Surreal database. *Mandatory*. +- **`surreal.default.user`**: the username used for authentication when connecting to the Surreal database. It can be set using `${SURREALDB_USER}` environment variable. *Mandatory*. +- **`surreal.default.password`**: the password used for authentication when connecting to the Surreal database. It can be set using `${SURREALDB_PASSWORD}` environment variable. *Mandatory*. +- **`surreal.default.init-db`**: whether to create database tables, records, and indices at application startup and `db`. *Optional*. + +## Blob Cache configuration + +Wave offers a feature to provide a cache for Docker blobs, which improves the performance of supplying blobs to the client. If you use Kubernetes, Wave can also use the k8s pod to delegate the transfer task for scalability. + +- **`wave.blobCache.enabled`**: whether to enable the blob cache. It is `false` by default. *Optional*. +- **`wave.blobCache.s5cmdImage`**: the Docker image that supplies the [s5cmd tool](https://github.com/peak/s5cmd). This tool is used to upload blob binaries to the S3 bucket. The default image used by Wave is `public.cr.seqera.io/wave/s5cmd:v2.2.2`. *Optional*. +- **`wave.blobCache.status.delay`**: the time delay in checking the status of the transfer of the blob binary from the repository to the cache. Its default value is `5s`. *Optional*. +- **`wave.blobCache.status.duration`**: the time for which Wave will store the blob binary in cache. Its default value is `5d`. *Optional*. +- **`wave.blobCache.timeout`**: timeout for blob binary transfer, after which Wave will throw a `TransferTimeoutException` exception. Its default value is `5m`. *Optional*. +- **`wave.blobCache.baseUrl`**: the URL, which will override the base URL (part of the URL before the blob path) of blobs sent to the end client. *Optional*. +- **`wave.blobCache.signing-strategy`**: the URL signing strategy for different services. Currently, Wave offers it for AWS S3 and Cloudflare, and you can use the respective values to enable them: `aws-presigned-url` and `cloudflare-waf-token`. *Mandatory*. +- **`wave.blobCache.cloudflare.lifetime`**: the validity of the Cloudflare WAF token. *Mandatory*. +- **`wave.blobCache.cloudflare.urlSignatureDuration`**: the validity of the AWS S3 URL signature. Its default value is `30m`. *Optional*. +- **`wave.blobCache.cloudflare.secret-key`**: the [Cloudflare secret](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/) to create the WAF token. *Mandatory*. +- **`wave.blobCache.storage.bucket`**: the name of the Cloudflare or S3 bucket. For example, `s3://wave-blob-cache`. *Mandatory*. +- **`wave.blobCache.storage.region`**: the AWS region where the bucket is created. *Mandatory*. +- **`wave.blobCache.storage.endpoint`**: the URL for the storage location. This will be used for the download or upload of blob binaries. *Optional*. +- **`wave.blobCache.storage.accessKey`**: the access key (part of credentials) to access the resources of the service used for caching. *Optional*. +- **`wave.blobCache.storage.secretKey`**: the secret key (part of credentials) to access the resources of the service used for caching. *Optional*. +- **`wave.blobCache.requestsCpu`**: the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to the k8s pod used for blob binary transfers. *Optional*. +- **`wave.blobCache.requestsMemory`**: the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to the k8s pod used for blob binary transfers. *Optional*. + +## Email configuration + +Email id to send emails from on the behalf of the Wave service. + +- **`mail.from`**: specifies the sender's email address for Wave notifications. This email address serves as the point of origin for any emails sent by Wave, providing a recognizable source for notifications. This setting is crucial for configuring the sender identity when Wave sends email notifications. *Mandatory*. + +## Metrics configuration + +Wave Metrics service provides data about container builds and pulls per ip, container image, and user. + +- **`wave.metrics.enabled`**: whether to enable the Wave metrics. It is `false` by default. *Optional*. + +## Accounts configuration + +- **`wave.accounts`**: Specifies a list of credentials to access authenticated Wave APIs, such as metrics APIs. *Mandatory*. + + Format of the credential list + + `- :`