Wallaroo Community Install Guide for AWS EC2 VMs

How to set up Wallaroo Community in an AWS EC2 VM

This guide is targeted towards system administrators and data scientists who want to work with the easiest, fastest, and free method of running your own machine learning models.

A typical installation of Wallaroo Community follows this process:

Step	Description	Average Setup Time
Download License	Create an environment that meets the Wallaroo prerequisites	5 minutes
Set Up Environment	Set up the cloud environment hosting the Wallaroo instance.	30 minutes
Install Wallaroo	Install Wallaroo into a prepared environment	15 minutes

Register Your Wallaroo Community Account

Completion Time

General completion time:  5 minutes

The first step to installing Wallaroo CE is to set up your Wallaroo Community Account at the web site https://portal.wallaroo.community. This process typically takes about 5 minutes.

Once you’ve submitted your credentials, you’ll be sent an email with a link to your license file.

Follow the link and download your license file. Store it in a secure location.

Redownload License

If your license is misplaced or otherwise lost, it can be downloaded again later from the same link, or by following the registration steps again to be provided with a link to your license file.

Wallaroo Community AWS EC2 Setup Instructions

The following instructions are made to assist users set up their Amazon Web Services (AWS) environment for running Wallaroo using AWS virtual servers with EC2. This allows organizations to stand a single virtual machine and used a pre-made Amazon Machine Images (AMIs) to quickly stand up an environment that can be used to install Wallaroo.

AWS Prerequisites

To install Wallaroo in your AWS environment based on these instructions, the following prerequisites must be met:

Register an AWS account: https://aws.amazon.com/ and assign the proper permissions according to your organization’s needs. This must be a paid AWS account - Wallaroo will not operate on the free tier level of virtual machines.

Steps

Create the EC2 VM

To create your Wallaroo instance using a pre-made AMI:

Log into AWS cloud console.
Set the region to N. Virginia. Other regions will be added over time.
Select Services -> EC2.
Select Instances, then from the upper right hand section Launch Instances->Launch Instances.
Set the Name and any additional tags.
In Application and OS Images, enter Wallaroo Install and press Enter.
From the search results, select Community AMIs and select Wallaroo Installer 3a.
Set the Instance Type as c6i.8xlarge or c6a.8xlarge as the minimum machine type. This provides 32 cores with 60 GB memory.
For Key pair (login) select one of the following:
1. Select an existing Key pair name
2. Select Create new key pair and set the following:
  1. Name: The name of the new key pair.
  2. Key pair type: Select either RSA or ED25519.
  3. Private key file format: Select either .pem or .ppk. These instructions are based on the .pem file.
  4. Select Create key pair when complete.
Set the following for Network settings:
1. Firewall: Select Create security group or select from an existing one that best fits your organization.
2. Allow SSH traffic from: Set to Enabled and Anywhere 0.0.0.0/0.
3. Allow HTTPs traffic from the internet: Set to Enabled.
Set the following for Configure Storage:
1. Set Root volume to at least 400 GiB, type standard.
Review the Summary and verify the following:
1. Number of instances: 1
2. Virtual server type: Matches the minimum requirement listed above.
3. Verify the other settings are accurate.
Select Launch Instance.

It is recommended to give the instance time to complete its setup process. This typically takes 20 minutes.

Verify the Setup

To verify the environment is setup for Wallaroo:

From the EC2 Dashboard, select the virtual machine created for your Wallaroo instance.
Note the Public IPv4 DNS address.
From a terminal, run ssh to connect to your virtual machine. The installation requires access to port 8800 and the private key selected or created in the instructions above.
The ssh command format for connecting to your virtual machine uses the following format, replacing the $keyfile, $VM_DNS with your private key file and the DNS address to your Amazon VM:
```
ssh -i "$keyfile" ubuntu@$VM_DNS -L8800:localhost:8800
```
For example, a $keyfile of Doc Sample Key.pem and $VM_DNS of ec2-54-160-227-100.compute-1.amazonaws.com would be as follows:
```
ssh -i "Doc Sample Key.pem" ubuntu@ec2-54-160-227-100.compute-1.amazonaws.com -L8800:localhost:8800
```
If the Kubernetes setup is still installing, wait until complete and when prompted select EXIT to complete the process. This process may take up to 20 to 30 minutes.

Cost Saving Tips

The following tips can be used to save costs on your AWS EC2 instance.

Stop Instances When Not In Use

One cost saving measure is to stop instances when not in use. If you intend to stop an instance, register it with static IP address so when it is turned back on your services will continue to function without interruption.

Reference: How do I associate a static public IP address with my EC2 Windows or Linux instance?.

Troubleshooting

I keep seeing the errors such as connect failed. Is this a problem?
- Sometimes you may see an error such as channel 3: open failed: connect failed: Connection refused. This is the ssh port forwarding attempting to connect to port 8800 during the installation, and can be ignored.
When Launching JupyterHub, I get a Server 500 error.
- If you shut down and restart a Wallaroo instance in a new environment or change the IP address, some settings may not be updated. Run the following command to restart the deployment process and update the settings to match the current environment:
```
kubectl rollout restart deployment hub
```
Install Wallaroo Community

Wallaroo Community can be installed into a Kubernetes cloud environment, or into a Kubernetes environment that meets the Wallaroo Prerequisites Guide. Organizations that use the Wallaroo Community AWS EC2 Setup procedure do not have to set up a Kubernetes environment, as it is already configured for them.

If the prerequisites are already configured, jump to Install Wallaroo to start installing.

This video demonstrates that procedure:

The procedure assumes at least a basic knowledge of Kubernetes and how to use the kubectl and kots version 1.91.3 applications.

The procedure involves the following major steps:

Install Wallaroo Community

Prerequisites

Local Software Requirements

Before starting, verify that all local system requirements are complete as detailed in the Wallaroo Community Local System Prerequisites guide:

kubectl: This interfaces with the Kubernetes server created in the Wallaroo environment.
For Kots based installs:
- kots Version 1.91.3

Cloud Kubernetes environment has been prepared.
You have downloaded your Wallaroo Community License file.

Install Wallaroo

The environment is ready, the tools are installed - let’s install Wallaroo! The following will use kubectl and kots through the following procedure:

Install the Wallaroo Community Edition using kots install wallaroo/ce, specifying the namespace to install. For example, if wallaroo is the namespace, then the command is:
```
kubectl kots install wallaroo/ce --namespace wallaroo
```

Wallaroo Community Edition will be downloaded and installed into your Kubernetes environment in the namespace specified. When prompted, set the default password for the Wallaroo environment. When complete, Wallaroo Community Edition will display the URL for the Admin Console, and how to end the Admin Console from running.

• Deploying Admin Console
• Creating namespace ✓
• Waiting for datastore to be ready ✓
    Enter a new password to be used for the Admin Console: •••••••••••••
  • Waiting for Admin Console to be ready ✓

• Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console

Wallaroo Community edition will continue to run until terminated. To relaunch in the future, use the following command:

kubectl-kots admin-console --namespace wallaroo

Initial Configuration and License Upload Procedure

Once Wallaroo Community edition has been installed for the first time, we can perform initial configuration and load our Wallaroo Community license file through the following process:

If Wallaroo Community Edition has not started, launch it with the following command:

❯ kubectl-kots admin-console --namespace wallaroo
  • Press Ctrl+C to exit
  • Go to http://localhost:8800 to access the Admin Console

Enter the Wallaroo Community Admin Console address into a browser. You will be prompted for the default password as set in the step above. Enter it and select Log in.

<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-admin-console-initial-login.png"
         alt="Wallaroo Admin Console Initial Login" width="800"/> 
</figure>

Upload your license file.

<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-upload-license-file.png"
         alt="Wallaroo Admin Upload License" width="800"/> 
</figure>

The Configure Wallaroo Community page will be displayed which allows you to customize your Wallaroo environment. For now, scroll to the bottom and select Continue. These settings can be customized at a later date.
The Wallaroo Community Admin Console will run the preflight checks to verify that all of the minimum requirements are not met. This may take a few minutes. If there are any issues, Wallaroo can still be launched but may not function properly. When ready, select Continue.
```
<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-preflight-successful.png"
         alt="Wallaroo Admin Preflight Successful" width="800"/> 
</figure>
```
The Wallaroo Community Dashboard will be displayed. There may be additional background processes that are completing their setup procedures, so there may be a few minute wait until those are complete. If everything is ready, then the Wallaroo Dashboard will show a green Ready.
```
<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-admin-console-ready.png"
         alt="Wallaroo Admin Admin Ready" width="800"/> 
</figure>
```
Under the license information is the DNS entry for your Wallaroo instance. This is where you and other users of your Wallaroo instance can log in. In this example, the URL will be https://beautiful-horse-9537.wallaroo.community. Note that it may take a few minutes for the DNS entries to propagate and this URL to be available.
```
<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-instance-url.png"
         alt="Wallaroo Instance URL" width="800"/> 
</figure>
```
You will receive an email invitation for the email address connected to this URL with a temporary password and a link to this Wallaroo instance’s URL. Either enter the URL for your Wallaroo instance or use the link in the email.

To login to your new Wallaroo instance, enter the email address and temporary password associated with the license.

<figure>
    <img src="/images/2023.4.1/wallaroo-community/wallaroo-community-initial-login.png"
         alt="Wallaroo Initial Login" width="800"/> 
</figure>

With that, Wallaroo Community edition is launched and ready for use! You can end the Admin Console from your terminal session above. From this point on you can just use the Wallaroo instance URL.

Now that your Wallaroo Community edition has been installed, let’s work with some sample models to show off what you can do. Check out either the Wallaroo 101 if this is your first time using Wallaroo, or for more examples of how to use Wallaroo see the Wallaroo Tutorials.

Troubleshooting

Issue

<p>If you see an error similar to <code>failed to deploy admin console: failed to wait for {some node}: timeout waiting for {some node}</code>, it may be because the connection between your local system and the cloud service is slow, or related issues.</p>

If this occurs, adding the option --wait-duration 5m give enough time for nodes to finish starting.