# Set up your environment

This topic describes how to set up your environment to get started with the Replicated Platform. It includes information about installing the required tools on your local workstation as well as creating development environments for testing installation and upgrade scenarios for your application.

## Set up your local workstation {#local}

This section lists the tools that you need to install on your local workstation to manage applications, releases, customers, and more with the Replicated Platform.

### Install kubectl

kubectl is the Kubernetes command line tool. You will use kubectl to communicate with the clusters that you create with the Replicated Compatibility Matrix, and when testing and troubleshooting installations in existing clusters. For more information about kubectl, see [Command line tool (kubectl)](https://kubernetes.io/docs/reference/kubectl/) in the Kubernetes documentation.

#### Mac

To install kubectl on Mac, do one of the following:

* Install with Homebrew:
    ```bash
    brew install kubectl
    ```
* Install using curl:

    ```bash
    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
    chmod +x ./kubectl
    sudo mv ./kubectl /usr/local/bin/kubectl
    ```

#### Linux

To install kubectl on Linux, do one of the following:

* Install using curl:

    ```bash
    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    chmod +x ./kubectl
    sudo mv ./kubectl /usr/local/bin/kubectl
    ```

* Install with a package manager (Ubuntu/Debain):

    ```bash
    sudo apt-get update
    sudo apt-get install -y kubectl
    ```

* Install with a package manager (CentOS/RHEL/Fedora):

    ```bash
    sudo yum install -y kubectl
    ```

### Install Helm

The Helm CLI is the tool for interacting with Helm and managing charts. Replicated recommends that all applications distributed with the Replicated Platform are packaged with Helm. Helm charts distributed with Replicated can also be installed in customer environments using Helm. Installing the Helm CLI on your workstation is important for being able to test and troubleshoot installations with Helm.

For more information, see [Installing Helm](https://helm.sh/docs/intro/install/) in the Helm documentation.

#### Mac

To install the Helm CLI on Mac, do one of the following:

* Install with Homebrew:

    ```bash
    brew install helm
    ```

* Install using curl:

    ```bash
    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4 | bash
    ```

#### Linux

To install the Helm CLI on Linux:

```bash
curl -LO https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz
tar -zxvf helm-v3.12.0-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/helm
```

### Install and authorize the Replicated CLI

The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix.

After installing, authorize the Replicated CLI using your Replicated credentials.

For more information about installing and authorizing the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing).

#### Mac

To install and run the latest Replicated CLI on MacOS:

1. <InstallMac/>

      :::note
      If you do not have root access to the `/usr/local/bin` directory, you can install with sudo by running `sudo mv replicated /usr/local/bin/replicated` instead of `mv replicated /usr/local/bin/replicated`.
      :::

1. <Verify/>

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](/reference/replicated-cli-installing#auth).

#### Linux / windows subsystem for linux (wsl2) {#linux-wsl2}

To install and run the latest Replicated CLI on Linux or Windows Subsystem for Linux (WSL2):

1. For Windows users, first install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

1. <InstallLinux/>

    :::note
    If you do not have root access to the `/usr/local/bin` directory, you can install with sudo by running `sudo mv replicated /usr/local/bin/replicated` instead of `mv replicated /usr/local/bin/replicated`.
    :::

1. <Verify/>

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](/reference/replicated-cli-installing#auth).

#### Docker / windows

:::note
For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See [Linux / Windows Subsystem for Linux (WSL2)](#linux-wsl2).
:::

To install and run the latest Replicated CLI in Docker environments:

1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have `Read/Write` access. See [Generating API Tokens](/vendor/replicated-api-tokens).

1. Get the latest Replicated CLI installation files from the [replicatedhq/replicated repository](https://github.com/replicatedhq/replicated/releases) on GitHub.

    Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop.

1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](/reference/replicated-cli-installing#auth).

   :::note
   Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [Set Environment Variables](/reference/replicated-cli-installing#env-var).
   ::: 

### Install the preflight and support bundle plugins

The preflight and support-bundle plugins available through the open source Troubleshoot project provide important troubleshooting tools for your customers, allowing them to run preflight checks and collect support bundles. For more information, see [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about).

For more information about installing the preflight and support-bundle plugins, including other installation options, see [Getting Started](https://troubleshoot.sh/docs/) in the Troubleshoot documentation.

#### Mac

For Mac users, Replicated recommends using Homebrew to install the preflight and support-bundle plugins:

```bash
brew install preflight
brew install support-bundle
```

#### Windows / linux

For Windows and Linux users, use Krew to install the preflight and support-bundle plugins:

1. Install Krew:

    ```bash
    (
      set -x; cd "$(mktemp -d)" &&
      OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
      ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')" &&
      KREW="krew-${OS}_${ARCH}" &&
      curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&
      tar zxvf "${KREW}.tar.gz" &&
      ./"${KREW}" install krew
    )
    ```

1. After installing, add the krew binary directory to your PATH:

    ```bash
    echo 'export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```

1. Run the following commands:

   ```bash
   kubectl krew install preflight
   kubectl krew install support-bundle
   ```

### Install sbctl

sbctl is a command-line tool that makes it easier to troubleshoot an installation using a support bundle. With sbctl, you provide a support bundle that was collected in a cluster. sbctl then generates a kubeconfig file based on the contents of the support bundle an opens an interactive shell. In the sbctl shell, you can run kubectl commands to interact with a representation of the state of the cluster when the support bundle was collected.

For more information, see the [sbctl](https://github.com/replicatedhq/sbctl) repository in GitHub.

To install sbctl, run one of the following commands:

* macOS Apple Silicon:
    ```bash
    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_darwin_arm64.tar.gz
    tar -xzf sbctl_darwin_arm64.tar.gz -C /tmp sbctl
    rm -f sbctl_darwin_arm64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/
    ```
* macOS Intel systems:

    ```bash
    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_darwin_amd64.tar.gz
    tar -xzf sbctl_darwin_amd64.tar.gz -C /tmp sbctl
    rm -f sbctl_darwin_amd64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/
    ```

* Linux x86_64:
    ```bash
    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_linux_amd64.tar.gz
    tar -xzf sbctl_linux_amd64.tar.gz -C /tmp sbctl
    rm -f sbctl_linux_amd64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/
    ```

* Linux ARM64:
    ```bash
    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_linux_arm64.tar.gz
    tar -xzf sbctl_linux_arm64.tar.gz -C /tmp sbctl
    rm -f sbctl_linux_arm64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/
    ```

### (Recommended) Install data processing tools

Replicated recommends that you install the following tools for parsing and manipulating JSON and YAML data:
* [jq](https://jqlang.org/) for JSON processing
* [yq](https://mikefarah.gitbook.io/yq/) for YAML manipulation

These tools are useful when working with Kubernetes and Replicated configurations to reduce complex data manipulation tasks from multi-step processes into single commands, simplifying your development workflow.

* To install jq, run one of the following commands:

    * macOS:
      ```bash
      brew install jq
      ```
    * Ubuntu/Debian:
      ```bash
      sudo apt-get install jq
      ```
    * CentOS/RHEL/Fedora"   
      ```bash
      sudo yum install jq
      ```
    * Direct download:  
      ```bash
      curl -LO https://github.com/stedolan/jq/releases/latest/download/jq-linux64
      chmod +x jq-linux64
      sudo mv jq-linux64 /usr/local/bin/jq
      ```

* To install yq, run one of the following commands:
    * macOS:
      ```bash
      brew install yq
      ```
    * Linux:
      ```bash
      curl -LO https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
      chmod +x yq_linux_amd64
      sudo mv yq_linux_amd64 /usr/local/bin/yq
      ```
    * Go install:
      ```bash
      go install github.com/mikefarah/yq/v4@latest
      ```

## Set up development environments for testing {#dev}

Testing your releases is an important part of the commercial software distribution lifecycle. Replicated recommends that you have access to a virtual machine (VM) and a cluster where you can install your application releases for testing.

### About creating a VM

You need access to a VM to test installations and updates with the [Replicated Embedded Cluster](/vendor/embedded-overview) installer:

* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create and SSH onto Linux VMs. For more information, see [Create and Manage Environments with CMX](/vendor/testing-how-to).

* **Option 2: Bring your own VM.** Your VM must meet the following requirements to install with Embedded Cluster:

   * Linux operating system

   * x86-64 architecture

   * systemd

   * At least 2GB of memory and 2 CPU cores

   * The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation.

   * The user performing the installation must have root access to the machine, such as with `sudo`.

   * The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/reference/embedded-cluster-install).

      Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations:

         - `/etc/cni`
         - `/etc/k0s`
         - `/opt/cni`
         - `/opt/containerd`
         - `/run/calico`
         - `/run/containerd`
         - `/run/k0s`
         - `/sys/fs/cgroup/kubepods`
         - `/sys/fs/cgroup/system.slice/containerd.service`
         - `/sys/fs/cgroup/system.slice/k0scontroller.service`
         - `/usr/libexec/k0s`
         - `/var/lib/calico`
         - `/var/lib/cni`
         - `/var/lib/containers`
         - `/var/lib/kubelet`
         - `/var/log/calico`
         - `/var/log/containers`
         - `/var/log/embedded-cluster`
         - `/var/log/pods`
         - `/usr/local/bin/k0s`

   * (Online installations only) Access to replicated.app and proxy.replicated.com or your custom domain for each

   * Embedded Cluster is based on k0s, so all k0s system requirements and external runtime dependencies apply. See [System requirements](https://docs.k0sproject.io/stable/system-requirements/) and [External runtime dependencies](https://docs.k0sproject.io/stable/external-runtime-deps/) in the k0s documentation.

### About creating a cluster

To test installations with Helm, you need kubectl access to a cluster.

* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create clusters. For more information, see [Create and Manage Environments with CMX](/vendor/testing-how-to).

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