# Install SlackerNews with the Helm CLI

This tutorial demonstrates how to install an application distributed with Replicated using the Helm CLI.

## Introduction

In this tutorial, you will:

* Download the sample Helm chart (SlackerNews)

* Create a release for SlackerNews in the Replicated Platform

* Get the Helm CLI installation instructions for SlackerNews from the [Replicated Enterprise Portal](/vendor/enterprise-portal-about) 

* Install SlackerNews using the Helm CLI in a Kubernetes cluster

## Set up your environment

Before you begin, do the following to set up your environment:

* Install the Helm CLI, which is the tool for interacting with Helm and managing Helm charts. See [Install Helm](/vendor/environment-setup#install-helm) in _Set Up Your Environment_.

* Ensure that you have access to a Kubernetes cluster where you can test the installation using the Helm CLI:

   * **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix (CMX) to create a cluster for this tutorial, first request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/testing-about#billing-and-credits).

          :::note
          If you are new to the Replicated platform, you might be eligible for $100 in free CMX credits. To request your free credits, reach out to our sales team at https://www.replicated.com/contact and note in the comments that you are completing a Replicated tutorial.
          :::

      After you complete the prerequisites described above, continue to the [Tutorial](#tutorial). You will create the cluster with CMX as part of the tutorial.

   * **Option 2: Bring your own Cluster.** You can use any cloud provider or tool that you prefer to create a cluster, such as Google Kubernetes Engine (GKE) or minikube.

   For more information, see [Set Up Development Environments for Testing](/vendor/environment-setup#dev).

## Tutorial

### Create an application

Create a SlackerNews application in the Replicated Platform:

1. On your local machine, install the Replicated CLI:

    * MacOS

      ```bash
      brew install replicatedhq/replicated/cli
      ```
    * Linux / Windows Subsystem for Linux (WSL)

      ```bash
      version=$(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
         | grep -m1 -Po '"tag_name":\s*"v\K[^"]+')
      curl -Ls \
         "https://github.com/replicatedhq/replicated/releases/download/v${version}/replicated_${version}_linux_amd64.tar.gz" \
         -o replicated.tar.gz
      tar xf replicated.tar.gz replicated && rm replicated.tar.gz
      mv replicated /usr/local/bin/replicated
      ``` 
   For more information and additional installation options, see [Install the Replicated CLI](/reference/replicated-cli-installing).

1. Authorize the Replicated CLI:

   ```bash
   replicated login
   ```
   In the browser window that opens, follow the prompt to log in to your Vendor Portal account and authorize the CLI.

1. Create an application named SlackerNews:

   ```bash
   replicated app create "SlackerNews"
   ```
   :::note
   If you already have an application named SlackerNews in your Vendor Portal team, you can add a qualifier to the name. For example, "SlackerNews Tutorial" or "SlackerNews YOUR_NAME".
   :::

1. Set the `REPLICATED_APP` environment variable to the slug of the application that you created:

   ```bash
   export REPLICATED_APP=APP_SLUG
   ```
   Where `APP_SLUG` is the unique application slug provided in the output of the `replicated app create` or `replicated app ls` commands.

   Setting the `REPLICATED_APP` environment variable allows you to interact with the application using the Replicated CLI without needing to use the `--app` flag with every command.

### Get the chart archive and create a release

Download the chart archive for SlackerNews version 1.0.1, then add the archive to a new release in the Replicated Platform:

1. Run the following command to download the SlackerNews Helm chart archive to a new `tutorial-helm-install` directory: 

    ```bash
    curl -O --create-dirs --output-dir tutorial-helm-install https://docs.replicated.com/slackernews-1.0.1.tgz
    ```

1. Add the chart archive to a new release:

   ```bash
   replicated release create --yaml-dir tutorial-helm-install --promote Unstable
   ```
   **Example output:**
   ```
   • Reading manifests from . ✓
   • Creating Release ✓
    • SEQUENCE: 1
   • Promoting ✓
    • Channel 32q8tKLfRFbHYPGJ1Q2E2vcDQ9j successfully set to release 1
   ```

### Customize the Enterprise Portal

Customize the look and feel of the Enterprise Portal for the SlackerNews application:

1. Log in to the [Vendor Portal](https://vendor.replicated.com).

1. Under the application drop down, select the SlackerNews application that you created.

    <img alt="App drop down" src="/images/quick-start-app-dropdown-slackernews.png" width="250px"/>

    [View a larger version of this image](/images/quick-start-app-dropdown-slackernews.png)

1. In the left navigation panel, click **Enterprise Portal**.

1. On the **Enterprise Portal > Settings** tab, for **Title** enter `SlackerNews Enterprise Portal`.

1. Scroll down to the **Colors** section.

1. For **Primary**, enter `#fd9431`. For **Secondary**, enter `#297372`. Click **Save**.

    ![Enterprise Portal color settings](/images/enterprise-portal-settings-colors.png)

    [View a larger version of this image](/images/enterprise-portal-settings-colors.png)

1. Go to the **Knowledge base** tab. For **Helm Post-Install Instructions**, enter the following markdown:

     ```mdx
     Congratulations! For more information about getting started with SlackerNews, see the docs at [https://docs.slackernews.io/](https://docs.slackernews.io/).
     ```

     ![Enterprise Portal install instructions settings](/images/enterprise-portal-settings-post-install.png)

     [View a larger version of this image](/images/enterprise-portal-settings-post-install.png)

1. Click **Save Changes**.    

### Create a customer

Create a test customer:

1. In the Vendor Portal, go to **Customers > Create customer**.

     The **Create a new customer** page opens:

     ![Customer a new customer page in the Vendor Portal](/images/create-customer.png)

     [View a larger version of this image](/images/create-customer.png)

1. For **Customer name**, enter a name for the customer. For example, `Example Customer`.

1. For **Customer email**, enter an email address. This email address is only used as a username for authenticating with the Replicated registry and is never contacted. A customer email address is required for Helm CLI installations.

1. For **Assigned Channel**, select **Unstable**. This allows the customer to install releases promoted to the Unstable channel.

1. For **Customer type**, select **Development**.

1. For **Install types**, enable **Existing Cluster (Helm CLI)**.

1. Click **Save Changes**.

### Access the customer's Enterprise Portal

Log in to the Enterprise Portal for the customer to get the Helm CLI installation instructions:

1. On the customer's page, go to the **Enterprise Portal Access** tab.

1. Enable the **Enable Enterprise Portal for this customer** toggle.

    ![enterprise portal toggle enabled](/images/customer-enterprise-portal-access-toggle.png)

    [View a larger version of this image](/images/customer-enterprise-portal-access-toggle.png)

    :::note
    The Enterprise Portal is beta. By default, customers have access to the Replicated Download Portal. For more information, see [Comparison to the Download Portal](/vendor/enterprise-portal-about#comparison-to-the-download-portal) in _About the Enterprise Portal_.
    :::

1. In the **Invite users** dialog that opens automatically, click **Cancel** to close the dialog.

   For your production application, this is where you could send initations to customers so they can access the Enterprise Portal.

1. Click **Login to portal** to generate a one-time login and open the Enterprise Portal for the customer.

   ![Login to portal button](/images/enterprise-portal-one-time-login.png)

   [View a larger version of this image](/images/enterprise-portal-one-time-login.png)

   The Enterprise Portal dashboard opens.   

1. Go to the Enterprise Portal **Install** tab. 

    ![install tab](/images/enterprise-portal-install-tab.png)

    [View a larger version of this image](/images/enterprise-portal-install-tab.png)

1. On the **Installation Guide** page, if multiple installation options are displayed, select **Helm**.

    :::note
    The installation options that are displayed in the Enterprise Portal depend on the **Install types** enabled for the customer. 
    :::

1. For **Instance Name**, enter a nickname for the instance.

1. For **Kubernetes Distribution**, select the distribution of the cluster where you will install SlackerNews. If you are going to use CMX to create the cluster, select **Vanilla Kubernetes**.

1. For **Cluster Network Availability**, select **Outbound requests allowed**.

1. For **Registry Access**, select **My workstation can access the internet, the registry AND the cluster**.

1. Click **Next**.

### Install

Install SlackerNews in a cluster:

1. If you brought your own cluster, set kubectl context to the cluster where you want to install. If you are using CMX, do the following:

   1. Create a kind cluster with version 1.34.0 of Kubernetes:

      ```bash
      replicated cluster create --distribution kind --instance-type r1.small --disk 50 --version 1.34.0
      ```

   1. Watch for the cluster to have a `running` status:

      ```bash
      replicated cluster ls --watch
      ```    

   1. After the cluster status is `running`, run the following command to set your kubectl context to the cluster:

      ```bash
      replicated cluster shell CLUSTER_ID
      ```
      Where `CLUSTER_ID` is the ID of the cluster provided in the output of `replicated cluster ls`.

      :::note
      You can also copy the shell command for the cluster from the **Compatibility Matrix** page in the Vendor Portal.
      :::

1. Go back to the install wizard in the Enterprise Portal.

    ![Helm online install wizard](/images/enterprise-portal-helm-online-install-slackernews.png)

    [View a larger version of this image](/images/enterprise-portal-helm-online-install-slackernews.png)

1. On the **Helm Online Install**, for **Select a version**, ensure that the version you promoted (`1.0.1`) is selected.

1. For **Export credential and log in**, run the command to log in to the Replicated registry.

1. Run the next command to install the preflight plugin.

1. Run preflight checks against the cluster.

1. Skip the **Create values override file** step. This is not necessary for the purpose of this tutorial because you do not need to pass a local values file to the chart.

1. Copy the install command provided and make the following changes:
   * Remove the `--values my-values.yaml` flag.
   * Add `--namespace slackernews --create-namespace` to install the application in the slackernews namespace.

   **Example:**

   ```bash
   helm install slackernews oci://registry.replicated.com/slackernews/unstable/slackernews --version 1.0.1 --namespace slackernews --create-namespace 
   ```

1. Watch the SlackerNews deployment: 

    ```bash
    kubectl get all --namespace slackernews --watch
    ```

1. When the installation is complete and the `slackernews-nginx` service is running, run the following command to port forward the service to local port 8080:

   ```bash
   kubectl port-forward --namespace slackernews svc/slackernews-nginx 8080:8080
   ``` 

1. In a browser, go to `localhost:8080`. The SlackerNews application landing page opens.

    ![SlackerNews landing page page](/images/slackernews-landing-page.png)

    [View a larger version of this image](/images/slackernews-landing-page.png)

1. Go back to the **Helm Online Install** wizard in the Enterprise Portal and click **Continue**. On the **Installation Complete** page, you can see the post-installation message that you set.

    ![Installation Complete page](/images/enterprise-portal-post-installation.png)

    [View a larger version of this image](/images/enterprise-portal-post-installation.png)

1. Return to the Vendor Portal, select the SlackerNews application, and go to **Customers**. Under the name of the customer, confirm that you can see an active instance.

1. (Optional) Under Instance ID, click on the ID to view additional insights including the versions of Kubernetes and the Replicated SDK running in the cluster where you installed the application.

## Summary

Congratulations! You created a release using a Helm chart, then followed the Helm CLI installation steps provided in the Enterprise Portal to install the release in a cluster.

For more information about Helm CLI installations for applications distributed with Replicated, see [About Helm Installations with Replicated](/vendor/helm-install-overview).