> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ale.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster & ale Setup

> Guide for configuring Kubernetes (k3s) on AWS EC2 and installing ale.

<Info>
  This guide demonstrates Kubernetes cluster configuration using k3s. However, `ale` can be used with clusters configured through other methods such as kubeadm, kubespray, etc.
</Info>

***

## K3s Setup & Agent Install

<Steps>
  <Step title="After SSH connecting to EC2, run the following command to install k3s.">
    ```bash theme={null}
    curl -sfL https://get.k3s.io | sh -s - server \
     --bind-address=0.0.0.0 \
     --advertise-address=[EC2 Public IP Address] \
     --tls-san=[EC2 Public IP Address] \
     --node-external-ip=[EC2 Public IP Address] \
     --disable=traefik \
     --docker
    ```
  </Step>

  <Step title="To use kubectl as a non-root user, run the following commands.">
    ```bash theme={null}
    mkdir -p ~/.kube && \
    sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config && \
    sudo chown $(whoami):$(whoami) ~/.kube/config && \
    chmod 600 ~/.kube/config && \
    echo "export KUBECONFIG=~/.kube/config" >> ~/.bashrc && \
    exec -l $SHELL
    ```
  </Step>

  <Step title="Verify that the cluster is functioning properly by running the following command.">
    ```bash theme={null}
    kubectl get nodes
    ```

    ```bash theme={null}
    # Verify that STATUS is Ready
    NAME              STATUS   ROLES                  AGE     VERSION
    ip-172-31-14-74   Ready    control-plane,master   6d21h   v1.31.3+k3s1
    ```
  </Step>

  <Step title="Run the following commands to install the ale agent.">
    ```
    kubectl apply -f https://raw.githubusercontent.com/ale-run/ale/refs/heads/main/k8s/dist/latest/agent.yaml
    ```
  </Step>
</Steps>

## Kubernetes Metrics Server

> The K3s installed according to this guide includes Metrics Server by default, so installation is not necessary. For clusters without Metrics Server, check the command below to install it.

<AccordionGroup>
  <Accordion title="Kubernetes Metrics Server Installation Command">
    ```bash theme={null}
    kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
    ```
  </Accordion>
</AccordionGroup>

<Info>
  Verify that resource usage is being displayed correctly through **Metrics Server** using the following command:

  ```bash theme={null}
  kubectl top nodes
  ```
</Info>

## Nginx Ingress Controller

<Steps>
  <Step title="Run the following commands to install Nginx Ingress Controller.">
    ```bash theme={null}
    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    ```

    ```bash theme={null}
    helm install ingress-nginx ingress-nginx/ingress-nginx \
     --version 4.11.2 \
     --namespace ingress-nginx --create-namespace \
     --set controller.service.type=LoadBalancer \
     --set controller.allowSnippetAnnotations=true \
     --set controller.admissionWebhooks.enabled=false
    ```
  </Step>

  <Step title="Run the following command to verify that the External IP of the Kubernetes service matches the Elastic IP attached to EC2.">
    ```bash theme={null}
    kubectl get svc -n ingress-nginx
    ```

    ```bash theme={null}
    NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
    ingress-nginx-controller   LoadBalancer   10.43.158.249   [External IP]    80:32119/TCP,443:31694/TCP   6d21h
    ```
  </Step>
</Steps>

## Install and Run ale

<Steps>
  <Step title="Enter the following commands to install the `ale-run` package.">
    ```bash theme={null}
    mkdir ale-run
    cd ale-run
    ```

    ```bash theme={null}
    npm i @ale-run/runtime@latest
    ```
  </Step>

  <Step title="Enter the following command to run `ale` in production mode.">
    ```bash theme={null}
    pm2 start "npx aled run -c [Kubernetes Cluster Name]" --name "ale-run" --watch
    ```

    <Tip>
      If no specific Kubernetes cluster name was specified, it is typically created with the name `default` and can be checked using the `kubectl config current-context` command.
    </Tip>
  </Step>

  <Step title="The setup is complete when the logs from pm2 display the following.">
    ```bash theme={null}
    pm2 log ale-run
    ```

    ```bash theme={null}
    ...
    [INFO] [plugin:loader] searching plugins at /home/ubuntu/ale-run/node_modules/@ale-run/runtime/dist
    [INFO] [plugin:loader] 2 plugin detected in /home/ubuntu/ale-run/node_modules/@ale-run/runtime/dist
    [INFO] [plugin:loader] plugin @ale-run/plugin-essentials has been added
    [INFO] [plugin:loader] plugin @ale-run/plugin-file-store has been added
    [INFO] [plugin:loader] searching plugins at /home/ubuntu/ale-run/node_modules
    [INFO] [plugin:loader] 1 plugin detected in /home/ubuntu/ale-run/node_modules
    [INFO] [plugin:loader] plugin @ale-run/plugin-ai-assistant has been added
    [INFO] [plugin:essentials] plugin @ale-run/plugin-essentials is installed {}
    [INFO] [plugin:essentials] plugin @ale-run/plugin-essentials is activate {}
    [INFO] [plugin:file-store] plugin @ale-run/plugin-file-store is activate {}
    [INFO] [plugin:file-store] working dir is /home/ubuntu/.ale
    [INFO] [plugin:file-store] storage type is direct
    [INFO] [plugin:file-store] upload dir is /home/ubuntu/.ale/files
    [INFO] [plugin:file-store] temp dir is /home/ubuntu/.ale/temp
    [INFO] [plugin:file-store] endpoint is (none)
    [INFO] [plugin:file-store] max file size is 10MB
    [INFO] [plugin:ai-assistant] plugin @ale-run/plugin-ai-assistant is activate {}
    [WARN] [plugin] [@ale-run/plugin-ai-assistant] activate failed: The OPENAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the OpenAI client with an apiKey option, like new OpenAI({ apiKey: 'My API Key' }).
    [INFO] [runtime:init] api server listening on 0.0.0.0:9009
    ```

    <Warning>
      If you encounter database conflicts during execution or want to reset settings, delete existing ale data using the following command and restart:

      ```bash theme={null}
      rm -r ~/.ale 
      ```
    </Warning>
  </Step>
</Steps>