# 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 . 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. * . {% 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](/files/ADOc00zAbqo0FQRXd09X) 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](/self-hosted-toucan/configuration/external-database.md) * 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](/files/o6LSCejrY4VNN5Gd1w8U) on the left side menu. 3. Click on "Generate Encrypted Password" ![Fetching Quay encrypted password](/files/G5dXRUTiIf1ihVH6J9TT) {% 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="" --docker-password="" ``` {% endcode %} Replace `` and `` 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="" ``` {% endcode %} Replace `` 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 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 -n toucan` to check the status of the deployment. And use `kubectl logs -c -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 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="/pages/qo9TBvwFFUGTf0Jyxdpi" %} [Configure email notifications](/self-hosted-toucan/configuration/email.md) {% endcontent-ref %} {% content-ref url="/pages/F2Eul1ThsidlfcZAesR4" %} [Configure HTTPS](/self-hosted-toucan/configuration/https.md) {% endcontent-ref %} {% content-ref url="/pages/wxwU7b2JCgkkV9eytRzH" %} [Configure OIDC authentication](/self-hosted-toucan/configuration/authentication/oidc.md) {% endcontent-ref %} {% content-ref url="/pages/vKpwAMzcJ674J18ghLc5" %} [Tuning resources](/self-hosted-toucan/configuration/tuning.md) {% endcontent-ref %} {% content-ref url="/pages/AFTa98pEcnRzDoGXERRM" %} [Configure persistence](/self-hosted-toucan/configuration/persistence.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-v3.toucantoco.com/self-hosted-toucan/try-it.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.