> ## 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.

# Installation

# Overview

This repository contains the installer for Binarly On-Prem. The installer uses Helmfile and various Helm charts to set up all necessary components.

# Prerequisites

* Access to a Kubernetes cluster (at least with version `1.29.0` or newer).
* `kubectl` configured to interact with your cluster.
* `helm` and `helmfile` installed.
* A Linux, macOS, or Windows with WSL enabled.
* Access credentials for Binarly's Artifact Registry (provided with the installer).
* A domain name, like "binarly.domain.com".

# Dependencies

The following table lists the exact dependencies known to work and necessary for the Binarly On-Prem Installer:

| Dependency                                               | Description                                                                        | Minimum Version | Installation Instructions                                                               |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------- |
| [helmfile](https://helmfile.readthedocs.io/en/stable/)   | A declarative specification for deploying Helm charts                              | 0.162.0         | [Helmfile Installation](https://helmfile.readthedocs.io/en/latest/#installation)        |
| [helm](https://github.com/helm/helm)                     | The Kubernetes package manager                                                     | 3.15.0          | [Helm Installation](https://helm.sh/docs/intro/install/)                                |
| [helm-diff](https://github.com/databus23/helm-diff)      | A Helm plugin that shows a diff explaining what a Helm upgrade would change        | 3.9.5           | [Helm-diff Installation](https://github.com/databus23/helm-diff#install)                |
| [helm-secrets](https://github.com/jkroepke/helm-secrets) | A Helm plugin that helps manage secrets with Git workflows and store them securely | 4.6.0           | [Helm-secrets Installation](https://github.com/jkroepke/helm-secrets/wiki/Installation) |

## Checking Dependencies are Installed Correctly

To ensure all dependencies are installed correctly, you can run the following commands:

```bash theme={null}
helmfile --version
helm version
helm plugin list
```

> \[!NOTE]
> Make sure the versions of the installed dependencies meet or exceed the minimum versions specified in the table above.

# Unpacking the Installer

1. Unpack the provided `tgz` file containing the Binarly On-Prem Installer:

   ```bash theme={null}
   tar -xzvf binarly-installer.tgz
   cd binarly-installer
   ```

2. Verify the contents match the following directory structure:

   ```console theme={null}
   binarly-installer
   ├── .envrc.local-template
   ├── .gitignore
   ├── helmfile.yaml.gotmpl
   ├── k8s
   │  └── apps
   │     ├── argocd
   │     │  └── values.yaml
   │     ├── binarly
   │     │  └── values.yaml.gotmpl
   │     ├── binarly-secrets
   │     │  └── values.yaml.gotmpl
   │     ├── cert-manager
   │     │  └── values.yaml
   │     ├── ingress-nginx
   │     │  └── values.yaml
   │     ├── minio-operator
   │     │  └── values.yaml
   │     ├── postgres-operator
   │     │  └── values.yaml
   │     ├── secretgen-controller
   │     │  └── values.yaml
   │     └── trust-manager
   │        └── values.yaml
   ├── README.md
   └── secrets
      ├── .gitkeep
      └── binarly-registry-credentials
   ```

# Directory Structure

The installer package contains the following key files and directories:

* `.envrc.local-template`: Template for environment configuration file with required env variables. Should be renamed/copied to `.envrc.local`.
* `helmfile.yaml.gotmpl`: Helmfile template for deployment of the Kubernetes helm charts.
* `k8s/apps/`: Contains configuration for various applications necessary to deploy Binarly On Prem to Kuberentes (ArgoCD, Binarly, cert-manager, etc.).
* `secrets/`: Directory for storing sensitive information (i.e: the Artifact Registry credentials).

## Kubernetes Helm Chart Configuration

The file `helmfile.yaml.gotmpl` contains all of the charts to install Binarly On-Prem on your Kubernetes cluster. There are two main groups of charts listed:

### External Dependencies

Binarly On-Prem depends on the following projects:

* [ArgoCD](https://argo-cd.readthedocs.io/en/stable/)
* [MinIO-Operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html)
* [Secretgen Controller](https://github.com/carvel-dev/secretgen-controller)
* [Zalando Postgres Operator](https://postgres-operator.readthedocs.io/en/latest/)

Each of these dependencies can be easily configured by just going to the `k8s/apps` directory and the name of the dependency. Default settings should be more than enough to have
a working cluster but, we recommend configuring each dependency to meet your requirements and policies towards security and best practices. We offer below some advice to some of them.

### Configuring ArgoCD

<Note>
  By default, ArgoCD does not need any configuration. There are optional steps in the [configuration document](./configuration/#binarly-secrets).
</Note>

## Installation

### Configure Environment Variables

1. Enter the `binarly-installer` directory.

2. Rename `.envrc.local-template` to `.envrc.local`:

   ```bash theme={null}
   mv .envrc.local-template .envrc.local
   ```

3. Put your Binarly Artifact Registry credentials inside a file called `binarly-registry-credentials` in a `secrets/` directory.

<Warning>
  Treat this file with maximum security as it grants access to your personal Artifact Registry.
</Warning>

4. Edit `.envrc.local` and you will see the following environment variables:

   ```bash theme={null}
   # Binarly Registry
   export BINARLY_REGISTRY_HOST="us-central1-docker.pkg.dev"
   export BINARLY_REGISTRY_PATH="binarly-tenant-1"
   export BINARLY_REGISTRY_FQDN="${BINARLY_REGISTRY_HOST}/${BINARLY_REGISTRY_PATH}"
   export BINARLY_REGISTRY_USERNAME="_json_key_base64"
   export BINARLY_REGISTRY_PASSWORD=$(cat $PWD/secrets/binarly-registry-credentials)

   # Binarly Secrets
   export BINARLY_SECRET_NVD_API_KEY=""
   export BINARLY_SECRET_SERVER_INTEGRATION_SECRET=""
   ```

<Warning>
  Ensure your `$BINARLY_REGISTRY_HOST` and `$BINARLY_REGISTRY_PATH` contains the correct Artifact Registry connection details (the previous ones are just placeholder values).
</Warning>

5. Source the `.envrc.local` to have the variables available to your shell session:

   ```bash theme={null}
   source .envrc.local
   ```

<Warning>
  If you make a change again to the `.envrc.local` file, ensure you run again the command to update your variables in your shell session.
</Warning>

You can verify everything is correctly setup correcty by issuing `echo` commands to test the output of the previous variables on your terminal.

```bash theme={null}
% echo $BINARLY_REGISTRY_HOST
us-central1-docker.pkg.dev

echo $BINARLY_REGISTRY_PATH
binarly-tenant-1

% echo $BINARLY_REGISTRY_FQDN
us-central1-docker.pkg.dev/binarly-tenant-1

echo $BINARLY_REGISTRY_USERNAME
_json_key_base64

echo $BINARLY_REGISTRY_PASSWORD
eyJ0eXBlIjoic2VydmljZV9hY2NvdW50IiwicHJvamVjdF9p.......

echo $BINARLY_SECRET_NVD_API_KEY
awea...

echo $BINARLY_SECRET_SERVER_INTEGRATION_SECRET
uyyal...
```

### Configure binarly-secrets chart

Please see the [configuration](./configuration/#binarly-secrets) section for more information on the secrets chart.

1. Ensure you have added to the `.envrc.local` the following variables for the secrets:
   * `BINARLY_SECRET_NVD_API_KEY`: NVD API Key.
   * `BINARLY_SECRET_SERVER_INTEGRATION_SECRET`: Encryption Key for Jira Integration setup. Must be random 32 character string.

### Configure binarly chart

Please see the [configuration](./configuration/#binarly-chart) section for more information on the secrets chart.

1. Edit `k8s/apps/binarly/values.yaml.gotmpl`, make sure to specify:
   * `basedomain`: Base domain name at which Binarly Transparency Platform should be available on the local network.
   * `keycloakHelmChart.chart.values.ingress.hostname`: Should be `"auth.{{basedomain}}"` with `basedomain` substituted with Base domain name.
   * `clusterIssuer`: Certificate Issuer to configure cert-manager to issue TLS certificates for the chosen domain name (for ex. "dashboard.binarly.domain.com").

### Install helm charts

Once everything is configured, let's install Binarly On-Prem on your Kubernetes cluster. To do so, first let's do it in batches. If we have a look to the `helmfile.yaml.gotmpl` file, we can discover we have two kind of helm charts defined:

* Dependencies (or base) charts: All extra necessary charts for Binarly to run.
* binarly: Charts specific for Binarly.

With helmfile, we can use the concept of `selectors`, i.e: this allows to select group of chars inside the `relase` entry.

1. We will start first those base dependencies on the cluster, to do so:

```bash theme={null}
helmfile sync --selector kind=base
```

If everything goes well you should see on the terminal that helm is installing ArgoCD, postgres-operator, etc on the Kubernetes cluster (all of the `releases` inside the `helmfile.yaml.gotmpl` with a label of `kind=base`).

2. Now it's time to install the second group, the Binarly charts. To do so:

```bash theme={null}
helmfile sync --selector kind=binarly
```

And as before, it will proceed with the installation of the `secrets` and `binarly` charts.

#### Sync Binarly ArgoCD applications

ArgoCD will be installed on the `argocd` namespace, and if it's using the default settings, we can do the following for displaying the UI (otherwise if we have added an Ingress, we can use the domain assigned to ArgoCD):

1. Obtain the credentials (from `argocd-initial-admin-secret` if you haven't changed the ArgoCD password or from `argocd-secret`):

ArgoCD default password:

```bash theme={null}
kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 --decode
```

2. And now do a port-forward:

```bash theme={null}
kubectl port-forward svc/argocd-server 9090:80 -n argocd
```

3. Navigate with your browser to `http://localhost:9090` and fill the credentials with user `admin` and password the one you obtained before. It should list all of the Binarly applications.

4. We can proceed to sync the applications in the following order:

   1. `minio-buckets` (wait for it to be `healthy` in ArgoCD).
   2. `fetch-artefacts` (wait for it to be `healthy` in ArgoCD).
   3. `common` (don't wait for it to be `healthy` in ArgoCD and deploy `keycloak`).
   4. `keycloak` (wait for `common` and `keycloak` to be healthy in ArgoCD).
   5. `dashboard` (wait for it to be `healthy` in ArgoCD).
   6. `server` (wait for it to be `healthy` in ArgoCD).

<Warning>
  When syncing `common` there's a strict dependency on `keycloak`. So better to sync both `applications` at the same time. First sync `common` and whilst is still syncing, just sync `keycloak`. Once both are green, then proceed to `fetch-artefacts`.
</Warning>

Once all of the ArgoCD Apps are synced, Binarly should be running at the URL of choice.

## Extra Helm chart additions

There are additional projects that can be used alongside the Binarly application:

* [Cert-Manager](https://cert-manager.io/)
* [Ingress-Nginx](https://kubernetes.github.io/ingress-nginx/)
* [Trust-Manager](https://cert-manager.io/docs/trust/trust-manager/)

Your environment may require more charts to be installed. These can be added to the `helmfile.yaml` file and a corresponding `values.yaml` file in the `k8s/apps` directory.