# Quick-Start Guide

{% hint style="warning" %}
Our self-hosted solution is currently in alpha and available to a limited group of customers. Features and setup options are subject to change. Interested in early access? Reach out to your Customer Success Manager to learn more, or contact <go@toucantoco.com>.

Current limitations:

* Migration between v2 and v3 is not stable.
* SAML2 is not supported at the moment. We recommend using SSO via OIDC instead.

If you notice unexpected behavior, do not hesitate to contact us through predefined channels:

* Slack (available during the alpha period)
* Your Customer Success Manager.
* <help@toucantoco.com>.
  {% endhint %}

This topic includes instructions for installing and running Toucan on Kubernetes using Helm Charts.

[Helm](https://helm.sh) is an open-source command line tool used for managing Kubernetes applications. It is a graduate project in the [CNCF Landscape](https://www.cncf.io/projects/helm/).

## Before you begin

To install Toucan using Helm, ensure you have completed the following:

* Install a Kubernetes server on your machine (or use a managed Kubernetes). For information about installing Kubernetes, refer to [Install Kubernetes](https://kubernetes.io/docs/setup/).

{% hint style="info" %}
In this guide, we will use the minikube cluster.
{% endhint %}

* Install the latest stable version of Helm. For information on installing Helm, refer to [Install Helm](https://helm.sh/docs/intro/install/).
* Install the latest stable version of kubectl. For information on installing kubectl, refer to [Install kubectl](https://kubernetes.io/docs/tasks/tools/).
* Have access to the [Toucan Toco's Quay registry](https://quay.io/organization/toucantoco). If you don't have access, [contact us using our mail address: go@toucantoco.com](mailto:go@toucantoco.com).
* Have a Curity Community Edition license. You can sign up for one [here](https://developer.curity.io/).
* Install [cert-manager](https://cert-manager.io) on the Kubernetes Cluster to generate TLS certificates. For information on installing cert-manager, refer to [Install cert-manager](https://cert-manager.io/docs/installation/).
* An Ingress controller setup on the Kubernetes Cluster. For information on installing an Ingress controller, refer to [Install an Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress/). We'll assume you are using the [Nginx Ingress controller](https://kubernetes.github.io/ingress-nginx/).

{% hint style="info" %}
If you are using minikube, please enable the `ingress` addon and follow the steps described in "[Ingress DNS | minikube](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns/#Linux)".
{% endhint %}

* A DNS set up for the Toucan Toco's domain which points to your Ingress controller Load Balancer IP. For this example, we will use `demo.toucantoco.test` as the main domain, and `auth-demo.toucantoco.test` as the authentication domain.

{% hint style="info" %}
If you are using minikube, please enable the `ingress-dns` addon and follow the steps described in "[Ingress DNS | minikube](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns/#Linux)".
{% endhint %}

## Install Toucan using Helm

### Overview

![How Helm is used](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-38363dd1913d40302955ed286d765b1c526fd732%2Fhelmshort.png?alt=media)

You can simply consider the "Toucan Stack" Helm Chart as a single package.

To customize the chart, Helm can overrides the default values file by specifying additional values files. You can read more about it in the [official Helm documentation](https://helm.sh/docs/chart_template_guide/values_files/).

{% hint style="danger" %}
**NOTE**: This guide helps you deploy a simple "one-shot" "all-in-one" Toucan Stack, which might not be suitable for production.

We **heavily** recommend in using an external PostgreSQL database as the one embedded might not be suitable for production:

* Please follow the following guide to connect to your external database: [Toucan - External Database](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/external-database)
* If you still wish to deploy PostgreSQL inside Kubernetes, we recommend using [CloudNativePG](https://cloudnative-pg.io/):
  * Supports failover and multiple standbys replicas.
  * Supports backups and restores.
  * Supports migrating data from another PostgreSQL instance.
  * Supports audit log, monitoring...
    {% endhint %}

### Login to the Toucan Toco's Quay registry

{% hint style="info" %}
We are assuming you have a terminal open in `/work/` directory. You can open your terminal in any directory, but make sure you are in a directory reserved for this project.
{% endhint %}

To sign in to the Quay registry with Helm, run the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
helm registry login quay.io
```

{% endcode %}

{% hint style="info" %}
To fetch your Quay credentials, you can generate an encrypted password on Quay.io:

1. Go to **Account Settings**.
2. Go to the "Gear Menu" ![gear](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-6e55fb7e4deda003226c680ea4e10a177f84c825%2Fgear.png?alt=media) on the left side menu.
3. Click on "Generate Encrypted Password"

   ![Fetching Quay encrypted password](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-3e77abb521882dbd5a451d4734c5abc40175ac6b%2Fquaycreds.png?alt=media)
   {% endhint %}

### Install Toucan

After you have set up Helm, you can start to deploy Toucan on your Kubernetes cluster.

When you deploy the Toucan Stack Helm charts, use a separate namespace instead of relying on the default namespace. The default namespace might already have other applications running, which can lead to conflicts and other potential issues.

When you create a new namespace in Kubernetes, you can better organize, allocate, and manage cluster resources. For more information, refer to [Namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).

{% stepper %}
{% step %}
To create a namespace, run the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
kubectl create namespace toucan
```

{% endcode %}
{% endstep %}

{% step %}
Send your Quay credentials to Kubernetes by running the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
# docker-registry: The type of secret to create.
# --namespace: The namespace to create the secret in.
# dockerconfigjson: The name of the secret to create.
# --docker-server: The server address of the registry.
# --docker-username: The username for the registry.
# --docker-password: The password for the registry.
kubectl create secret docker-registry --namespace toucan dockerconfigjson --docker-server=quay.io --docker-username="<username>" --docker-password="<password>"
```

{% endcode %}

Replace `<username>` and `<password>` with your credentials.
{% endstep %}

{% step %}
Send your Curity credentials to Kubernetes by running the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
# --namespace: The namespace to create the secret in.
# curity-secret: The name of the secret to create.
# --from-literal: The key and value of the secret to create.
kubectl create secret generic --namespace toucan curity-secret --from-literal=CURITY_LICENSE_KEY="<License>"
```

{% endcode %}

Replace `<License>` with your Curity license, extracted from the json. It should start with `ey...`.
{% endstep %}

{% step %}
**Assuming the DNS is properly configured, and the URLs https//demo.toucantoco.test and <https://auth-demo.toucantoco.test> are accessible publicly, we'll use cert-manager to generate TLS certificates.**

{% code title="yaml: /work/values.override.yaml" %}

```yaml
global:
  # Configure the persistence of the stack.
  defaultStorageClass: standard
  # Configure the public endpoint of the stack.
  hostname: demo.toucantoco.test
  # Use the Quay credentials
  imagePullSecrets:
    - dockerconfigjson

canopee:
  ingress:
    enabled: true
    # Use the Nginx Ingress controller
    ingressClassName: nginx
    annotations:
      # Use the cert-manager cluster issuer
      cert-manager.io/cluster-issuer: http01
    tls: true

curity:
  config:
    # Use the deployed license
    license:
      secretName: curity-secret
      secretKey: CURITY_LICENSE_KEY

  runtime:
    ingress:
      enabled: true
      ingressClassName: nginx
      hostname: auth-demo.toucantoco.test
      annotations:
        cert-manager.io/cluster-issuer: http01
      path: /
      tls: true

  admin:
    ingress:
      enabled: true
      ingressClassName: nginx
      hostname: auth-demo.toucantoco.test
      path: /admin
      tls: true
```

{% endcode %}
{% endstep %}

{% step %}
Deploy Toucan by running the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
# upgrade: The command to upgrade the Toucan Stack Helm charts.
# --install: And install the Toucan Stack Helm charts if they are not already installed.
# --namespace: The namespace to deploy the Toucan Stack Helm charts in.
# toucan-stack: The name of the deployment.
# oci://quay.io/toucantoco/charts/toucan-stack: The Helm chart to deploy.
# --values: The path to the values file, which overrides the default configuration for the Toucan Stack Helm charts.
helm upgrade --install toucan-stack oci://quay.io/toucantoco/charts/toucan-stack \
   --namespace toucan \
   --values values.override.yaml
```

{% endcode %}

{% hint style="info" %}
If the installation fails with:

```shell
Error: INSTALLATION FAILED: failed post-install: 1 error occurred:
        * timed out waiting for the condition
```

You should check the health of the deployment. Use `kubectl get <deployments/statefulsets/pods> -n toucan` to check the status of the deployment. And use `kubectl logs <pod-name> -c <container-name> -n toucan` to check the logs of the deployment.

We **highly recommend** using a Kubernetes GUI for troubleshooting like for example [Headlamp](https://headlamp.dev).
{% endhint %}
{% endstep %}

{% step %}
To get the Admin password, run the following command:

{% code title="shell: /work/" overflow="wrap" %}

```shell
kubectl get secret --namespace toucan toucan-stack-auth -o jsonpath='{.data.toucan-admin-password}' | base64 --decode
```

{% endcode %}
{% endstep %}

{% step %}
Navigate to <https://demo.toucantoco.test> in your browser to access Toucan.
{% endstep %}

{% step %}
Login with the Admin credentials. Enter `admin@example.com` for the username. For the password, use the one you got from the previous step.
{% endstep %}
{% endstepper %}

## What's next?

Now that you have a working Toucan deployment, you might be interested in configuring this environment for production use. Feel free to check out:

{% content-ref url="configuration/email" %}
[email](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/email)
{% endcontent-ref %}

{% content-ref url="configuration/https" %}
[https](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/https)
{% endcontent-ref %}

{% content-ref url="configuration/authentication/oidc" %}
[oidc](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/authentication/oidc)
{% endcontent-ref %}

{% content-ref url="configuration/tuning" %}
[tuning](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/tuning)
{% endcontent-ref %}

{% content-ref url="configuration/persistence" %}
[persistence](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/persistence)
{% endcontent-ref %}