Genie for Cloud Environments

This repository is the cloud-native version of Genie, the open virtual-assistant. It includes the web frontend, the Genie backend, the embedded skill library, and the NLP model servers.

Genie is a research project led by prof. Monica Lam, from Stanford University. You can find more information at https://oval.cs.stanford.edu.

Development

1. You need Git.

   Mac:

   1. Install Homebrew

   2. Install Git:

      brew install git
      

2. Clone this repository.

   You can clone it wherever you want, but if you don't know where to put it I recommend:

   mkdir -p "${HOME}/src/github.com/stanford-oval" && cd "${HOME}/src/github.com/stanford-oval"
   

   to create a directory and change into it.

   Then

   git clone --branch wip/nrser/k8s-dev-setup https://github.com/stanford-oval/almond-cloud.git
   

   and change into the cloned repository with

   cd almond-cloud
   

3. You need Kubernetes running locally. For Windows and Mac we recommend Docker Desktop. After installation, follow the instructions to enabled Kubernetes.

   On Linux, there are (of course) several options. Minikube, MicroK8s and Kind are the ones I've heard of. These instructions will follow a Docker Desktop installation, so adjust as needed.

4. Build the Almond Cloud Docker image

   docker build -f docker/Dockerfile -t localhost/almond-cloud .
   

5. Install the latest kustomize.

   Mac:

   brew install kustomize
   

   Windows and Linux: Follow their installation instructions.

   If you're on the Mac, I recommend the Homebrew option.

   NOTE

   Kustomize does come bundled with the kubectl utility that Kubernetes installations ship with, but some or all will be too out-of-date for our needs.

6. Deploy the Kubernetes Dashboard

   kustomize build k8s/dashboard/dev | kubectl apply -f -
   

   In a separate terminal, run

   kubectl proxy
   

   and keep that terminal open.

   Visit

   http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

   and use the Skip button to login and view the dashboard (there shouldn't be much there yet!).

7. Deploy the Nginx Ingress Controller

   kustomize build k8s/ingress-nginx/dev | kubectl apply -f -
   

8. Create a Mailgun account (if you don't already have one) and get the SMTP username and password for the domain you want to use to send emails.

   If you use the "sandbox" domain, make sure you add your email address to the Authorized Recipients and click the confirmation link they mail to you.

9. Create a local dev environment file

   1. Create a text file in the dev directory named .env

   2. Add these lines to the file, replacing the stuff between the ' quotes with the SMTP credentials from the last step and your email address.

      MAILGUN_SMTP_USERNAME='[email protected]'
      MAILGUN_SMTP_PASSWORD='your-smtp-password'
      DEVELOPER_EMAIL='[email protected]'
      

   3. Save the file.

10. Generate your kustomize secret file

    ./dev/bin/almond-dev.configure.bash
    

    The secret file is written to k8s/config/dev/secret.yaml.

11. Check your config files build successfully with kustomize

    kustomize build ./k8s/dev
    

    You should see a big dump of YAML to the screen. If there is an error, try to figure it out or ask for help.

12. Deploy Genie

    kustomize build ./k8s/dev | kubectl apply -f -
    

13. Go back to the dashboard and switch to the almond-dev namespace.

    You should see the Genie components booting up. It can take a few minutes for everything to "go green", but after that you can use Almond Cloud at

    http://localhost:8080