> ## Documentation Index
> Fetch the complete documentation index at: https://docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

# Configure Binarly charts

There are two custom Helm charts for Binarly On-Prem:

1. Secrets: Creates necessary secrets for the Binarly components.
2. Binarly: Deploys core On-Prem components following the ArgoCD App of Apps pattern.

Let's describe how to configure them:

## Binarly Secrets

The chart is configured in `k8s/apps/binarly-secrets/values.yaml.gotmpl`. At least, it's necessary to provide the following secrets:

```yaml theme={null}
secrets:
  # @schema
  # type: string
  # @schema
  # -- API key for NVD. It will fill the value from $BINARLY_SECRET_NVD_API_KEY
  nvdApiKey: {{ requiredEnv "BINARLY_SECRET_NVD_API_KEY" }}

  # @schema
  # type: string
  # @schema
  # -- Integration Secret for server component. It will fill the value from $BINARLY_SECRET_SERVER_INTEGRATION_SECRET
  serverIntegrationSecret: {{ requiredEnv "BINARLY_SECRET_SERVER_INTEGRATION_SECRET" }}
```

Thanks to helmfile, we can easily provide those environment variables from our `.envrc.local` file:

```bash theme={null}
## Binarly Secrets
# NOTE: Fill these secrets with the provided credentials
export BINARLY_SECRET_NVD_API_KEY=""
export BINARLY_SECRET_SERVER_INTEGRATION_SECRET=""
```

Ensure to fill the values accordingly. For the `BINARLY_SECRET_NVD_API_KEY` it should be present on the Bitwarden secrets.

For the `BINARLY_SECRET_SERVER_INTEGRATION_SECRET` you need to generate it with the following terminal command:

```bash theme={null}
openssl rand -base64 32
```

<Warning>
  Ensure you keep the previous secrets in a safe place. If you loose access to the `BINARLY_SECRET_SERVER_INTEGRATION_SECRET` the Jira integration will be lost as the data is encrypted into the database.
</Warning>

<Note>
  Remember if you make any change to the `.envrc.local` file to apply again the `source .envrc.local` command to refresh the latest environment variables!
</Note>

Now, you can render the output of the Secrets chart to quickly check what secrets are going to be created in the Kubernetes cluster:

```bash theme={null}
helmfile template --selector name=secrets
```

The secrets will be installed in the following steps. You can also `lint` the Chart for any misconfiguration or issues as well:

```bash theme={null}
helmfile lint --selector name=secrets
```

## Binarly Chart

This is the main chart that contains the ArgoCD App of Apps for Binarly. Configuration is stored in `k8s/apps/binarly/values.yaml.gotmpl`.

### Image Pull Secrets

By default, the Binarly deployment will use the authenticated registry provided by Customer Success and this is already set up. If you are using a custom registry, this can be adjusted in the `binarly-repository-secrets` file.

`imagePullSecrets` should match with the `binarly-registry` (that is being created on the `secrets` chart). This will allow to access the custom Artifact Registry to be able to pull docker images:

```yaml theme={null}
global:
  imagePullSecrets:
    - name: binarly-registry
```

### Ingress

`basedomain` is base domain name for Binarly Transparency Platform:

```yaml theme={null}
basedomain: "binarly.domain.com"
```

To configure the ingress, just tweak the following parameters:

```yaml theme={null}
ingress:
  # @schema
  # type: boolean
  # @schema
  # -- Enable ingress for the application
  enabled: false

  # @schema
  # type: string
  # @schema
  # -- Ingress class name to use
  className: "nginx"

  # @schema
  # type: object
  # properties:
  #   nginx:
  #     type: object
  # @schema
  # -- Annotations for the ingress resource
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 5000m

  tls:
    # @schema
    # type: boolean
    # default: false
    # @schema
    # -- Enable TLS for the ingress resource
    enabled: false

    # @schema
    # type: boolean
    # default: false
    # @schema
    # -- Use cert-manager for TLS certificate management
    useCertManager: false

    # @schema
    # type: string
    # default: ""
    # @schema
    # -- Name of the TLS secret to use (if not using cert-manager)
    secretName: ""

  # -- Only applicable if useCertManager is enabled
  clusterIssuer:
    # @schema
    # type: string
    # default: letsencrypt
    # @schema
    # -- Name of the cluster issuer
    name: letsencrypt

    # @schema
    # type: object
    # @schema
    # -- Extra ingress annotations for cert-manager
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt

    # @schema
    # type: object
    # additionalProperties: true
    # @schema
    # -- Issuer configuration for cert-manager
    issuer:
      acme:
        email: ssl@binarly.io
        privateKeySecretRef:
          name: letsencrypt-dash-acct-key
        server: https://acme-v02.api.letsencrypt.org/directory
        solvers:
          - http01:
              ingress:
                class: nginx
```

Also, from the previous configuration for the ingress, you can select if you want to use a custom TLS certificate, or to use `cert-manager` with the `Let's Encrypt` known as `ACME` by setting to `true` the key `useCertManager`.

`cert-manager` suppors many certificate provider issuers and not only `ACME` as [we can see from the list here](https://cert-manager.io/docs/configuration/issuers/).

You can tweak the `issuer` section to match any of the `cert-manager` issuers providers to be able to customize to your specific settings.

Don't forget to configure the keycloak ingress (ensure, for the `hostname` to start with `auth` and the **`basedomain`** you have configured before):

```yaml theme={null}
keycloak:
  # @schema
  # type: string
  # @schema
  # -- Name of the keycloak hostname to use. Ensure it matches with keycloakHelmChart.ingress.hostname.
  hostname: "auth"

keycloakHelmChart:
  chart:
    values:
      ingress:
        # @schema
        # type: boolean
        # @schema
        # -- Enable ingress for the application.
        enabled: true

        # @schema
        # type: string
        # @schema
        # -- Ingress class name to use. For now only nginx is supported.
        ingressClassName: nginx

        # @schema
        # type: boolean
        # @schema
        # -- Enable tls for the application.
        tls: true

        # @schema
        # type: string
        # @schema
        # -- Name of the keycloak hostname to use. Ensure it matches with your basedomain.
        hostname: "auth.binarly.domain.com"

        # @schema
        # type: object
        # additionalProperties: true
        # @schema
        # -- Issuer annotations for the cluster.
        annotations:
          cert-manager.io/cluster-issuer: letsencrypt
```

<Note>
  If you are using a custom `clusterIssuer.issuer` just ensure to change the `ingressAnnotations` for both `clusterIssuer.ingressAnnotations` and `keycloakHelmChart.chart.values.annotations` to match with the new cerfiticate provider.
</Note>

<Note>
  Currently, we expect both Binarly `dashboard` and `auth` to use the same `basedomain`. If you have your own Certifcate Authority, you'll need your own certificates for `dashboard.{{basedomain}}` and `auth.{{basedomain}}`.
</Note>

### Role-Based Access Control (RBAC)

By default all access is managed via Keycloak. To enable RBAC, you can set the following values:

```yaml theme={null}
auth:
  enableRBAC: true
  enableRBACMiddleware: true

dashboard:
  appConfigData:
    features:
      rbac: true
```

To read more about RBAC in the Binarly application, please see the [dedicated page](../user-guides/rbac/roles).

### Air Gapped Environment

The Binarly Application will work in an air-gapped environment with a few caveats:

* There must be an internal registry capable of hosting images and charts.
* Chart addresses must be updated to use the internal registry.
* Image repository fields must be overwritten to use the internal registry.
* One component of the Binarly Application (Vulnerability Database) requires internet access to fetch vulnerability data.

#### Internal Registry

The registry in use should be populated with the contents of the private Binarly registry provided by Customer Success. The exact contents will be communicated prior to the installation.

#### Chart and Image Addresses

The chart address need to be updated in two places:

1. The `repositories` section of the `helmfile.d/*.yaml.gotmpl` file.
2. In the `envrc.local` file.

#### Vulnerability Database

The Vulnerability Database component of the Binarly Application requires internet access to fetch vulnerability data. This can be achieved by setting up a proxy server that allows the Vulnerability Database to access the internet, and passing this config in `k8s/apps/binarly/values.yaml.gotmpl`:

```yaml theme={null}
vdb:
  env:
    http_proxy: "http://proxy:port"
    https_proxy: "http://proxy:port"
```

# Configure Third-Party Charts

The Binarly Installation comes with a set of third-party charts, more information in [considerations](/on-prem/considerations#third-party-charts). These charts are configured in the `k8s/apps/{chart name}` directory.

## ArgoCD

### Improve password security for admin user

By default, and if the Helm chart values are not changed from default settings, ArgoCD will create automatically the initial `admin` user with the following credentials:

* Username: `admin`
* Password: A randomized string of 10 characters.

The password secret is stored in the `argocd` namespace within the following secret name: `argocd-initial-admin-secret`. We recommend though, to change the password of the account to improve the security settings of your cluster with a size of 32 characters.

To do so there are two ways:

#### Configure ArgoCD Helm chart

The other option is to directly configure the ArgoCD Helm chart, to deploy it with our password. We can do it like it follows:

1. Configure the `k8s/apps/argocd/values.yaml` to include a hashed password like it follows (ensure you have installed `htpasswd` and `openssl` cli tools):
   ```yaml theme={null}
   configs:
      secret:
         # -- Bcrypt hashed admin password
         ## Argo expects the password in the secret to be bcrypt hashed. You can create this hash with
         ## export ARGOCD_PASSWORD="$(openssl rand -base64 32)"
         ## htpasswd -nbBC 15 "" "${ARGOCD_PASSWORD}" | tr -d ':\n' | sed 's/$2y/$2a/'
         ## and copy the resulting string inside `argocdServerAdminPassword`
         argocdServerAdminPassword: "{bcrypt hashed password from htpasswd command}"
   ```
2. Ensure you save the `$ARGOCD_PASSWORD` safely, otherwise you won't be able to access ArgoCD with the `admin` credentials, unless you redeploy the chart.
3. Once ArgoCD is running and deployed in your Kubernetes cluster, the password secret is stored inside the `argocd-secret` (instead of the `argocd-initial-admin-secret` secret).
   ```bash theme={null}
   kubectl get secret argocd-secret -n argocd -o jsonpath="{.data.admin\.password}" | base64 -d
   ```

<Note>
  What happens if I forgot my admin password?
  In this particular case, you can always generate a new `admin` password, update the `k8s/apps/argocd/values.yaml` and perform a `helmfile apply --selector name=argocd` to update your ArgoCD instance with the fix.
</Note>

#### Use ArgoCD CLI

This entails deploying ArgoCD (by just following this guide) and once up and running:

1. Install the ArgoCD CLI [on your system as per the official docs guide](https://argo-cd.readthedocs.io/en/stable/getting_started/)
2. Connect [ArgoCD CLI to your ArgoCD instance](https://argo-cd.readthedocs.io/en/stable/getting_started/#5-register-a-cluster-to-deploy-apps-to-optional)
3. Use the `argocd account update-password` CLI command [as stated in their docs](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_account_update-password/).

<Note>
  What happens if I forgot my admin password? [This guide will help you to troubleshoot it](https://argo-cd.readthedocs.io/en/stable/faq/#i-forgot-the-admin-password-how-do-i-reset-it).
</Note>

### Configuring ArgoCD Ingress with Ingress-Nginx and TLS

There are two main approaches to configure the ingress:

#### Option 1: SSL-Passthrough

This method allows exposing the Argo CD API server with a single ingress rule and hostname:

1. Open `k8s/apps/argocd/values.yaml`
2. Add or modify the `server.ingress` section:

```yaml theme={null}
server:
  ingress:
    enabled: true
    ingressClassName: nginx
    hostname: argocd.binarly.domain.com
    annotations:
      nginx.ingress.kubernetes.io/ssl-passthrough: "true"
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    tls: true
```

3. Ensure the [nginx-ingress-controller is running with the `--enable-ssl-passthrough` flag](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#ssl-passthrough). Modify the `k8s/apps/ingress-nginx/values.yaml` to contain:

   ```yaml theme={null}
   controller:
     extraArgs:
       enable-ssl-passthrough: true
   ```

#### Option 2: SSL Termination at Ingress Controller

For this option, you need to provide your own TLS certificate.

1. Open `k8s/apps/argocd/values.yaml`

   ```yaml theme={null}
   server:
      ingress:
         enabled: true
         ingressClassName: nginx
         hosts:
            - argocd.binarly.domain.com
         annotations:
            nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
            nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
         tls:
            - hosts:
               - argocd.binarly.domain.com
            secretName: argocd-ingress-http
   ```

2. Enable insecure mode for the ArgoCD server:

   ```yaml theme={null}
   params:
     server.insecure: true
   ```

<Note>
  ArgoCD supports more configuration options to configure the ingress.
  [We recommend you visiting ArgoCD official documentation guide for more information](https://argo-cd.readthedocs.io/en/stable/operator-manual/ingress/).
</Note>

## MetalLB

1. Include into the `repositories` list the Helm registry:

```yaml theme={null}
repositories:
  - name: metallb
    url: "https://metallb.github.io/metallb"
```

2. Now, add the chart to the list of `releases`:

```yaml theme={null}
releases:
  - name: metallb
    namespace: metallb
    createNamespace: true
    chart: metallb/metallb
    version: "0.14.8"
    labels:
      name: metallb
      kind: base
    values:
      - ./k8s/apps/metallb/values.yaml
```

3. Create the folder and the file at the path `./k8s/apps/metallb/values.yaml`.

4. Customize the `values.yaml` [according to your necessities](https://metallb.universe.tf/configuration/) by following MetalLB instructions.

5. Continue with the rest of the instructions.