Beiwe deployment extra information for non IT users

This page is intended as an extra help guide for users who are not familiar with direct system administration. It is meant to be read alongside Beiwe main deployment guide.

Note that the Beiwe Cluster setup only supports Linux, MacOS, and Windows Subsystem for Linux. There are no plans to support running directly on Windows. To install linux subsystem on a Windows 10 OS, click here for a guide.

Robust, scalable setup (configuring a server cluster)

Create an Amazon Web Services (AWS) account

Obtain a domain name

You can obtain a domain name from several domain registrars, such as godaddy.com, name.com, namecheap.com, Amazon Route 53, etc.

Set up an IAM user with sufficient permissions

1. If you are using us-east-1 servers, click on the following to go straight to the AWS IAM page. If you are using other regions, simply replace region=us-east-1 in the link with your AWS region.

2. Add a new user:
   
   Attach existing policies directly and choose 'AdministratorAccess':
   

3. Download or copy the generated credentials:
   

Generate a deployment key

1. This is a similar process as Step 2, Part 5 in the Quick setup process, click here for a AWS guide on what key pairs are and how to create them.

Create a Sentry account

Your sentry account will help you monitor for any errors in your server.

3. Finding 'Project Settings' and 'DSN':
   

Configure your application

1. git clone is a command for copying a repository on GitHub to your local computer. You will need to have Git terminal installed. (For more information on cloning, read this guide on GitHub.

2. Make sure you have Python 3.6 (or later) installed. Python 2 has been "end-of-life'd" as of Jan 1, 2020. The Beiwe code base now requires Python 3. To test your machine's configuration you will need to check the versions of python you have access to. In a terminal type python --version, if you have a version of python 2 you should check if you have Python 3 installed by entering python3 --version. If you have python3 then you may need to enter python3 and pip3 in place of python and pip wherever they appear in this guide. The Devs: we use pyenv to handle multiple (many and arbitrary) versions of python on one machine, you can install it here.

3. You may want to set up a Python 3 virtual environment specifically for your beiwe directory using virtualenv. Click here for a tutorial on creating virtual environments. If you are using pyenv you should probably use pyenv-virtualenv as it integrates / tends to override virtualenv (it is installed automatically if you used the install link above).

4. Example screenshot, insert your own key ID and key instead of the red letters:
   Be sure to change the file name to aws_credentials.json.

5. Example screenshot, insert your own information instead of the red letters:
   
   Be sure to change the file name to global_configuration.json.

6. You can check if you have pip by typing pip into the bash terminal and press enter. If you do not have pip, the system will return The program 'pip' is currently not installed. You can install it easily via the directions here. (The Devs: remember, you may need to use pip3.) You should see the following first few lines of output after running the code:
   

7. Give your environment a name, such as beiwe-env, and press enter.
   If you encounter Permission: denied, try running the following code:

$ pip install -r launch_requirements.txt --user

6. Designate a name for your environment, such as beiwe-env.

You should see the following first few lines of output:

7. Example screenshot for [YOUR-ENV-NAME]_beiwe_environment_variables.json, insert your own information instead of the red letters:
   

8. Follow the rest of the instructions to finish robust deployment.
   When you have successfully set up the environment, you should receive an email from Amazon notifying you of your subscription to the environment.

If you are using Windows subsystem for linux, ensure that all the files in cluster_management/pushed_files are in UNIX format. You can change these files to UNIX format with Notepad++ application (Edit >> EOL Conversion >> Unix).

You should see the following first few lines of output when you create your environment:

*Please note that in the event you wish to terminate the environment, ensure on the AWS console that you have terminated the environment, RDS, and S3 buckets, otherwise your AWS will continue to incur charge. Also note that You may need to delete the security groups as well before you can successfully terminate the environment and RDS. These components can all be found using the search bar at the top of the page in AWS console.

Set up the AWS Elastic Beanstalk Command-Line Interface (EB CLI)

1. For more information and help on installing EB CLI, use this link.

2. The supported platforms are listed here, scroll down to find the one for Python 2.7. Use the highlighted platform name as default_platform in the config.yml code. The platform names are constantly changing/updating, so be sure you use the most current and supported platform on this page.
   The most current platform at time of writing this wiki:

Example screenshot for .elasticbeanstalk/config.yml, insert your own information instead of the red letters:

Follow the rest of the instructions, and you should now be able to update your deployment anytime using the command line.

3. Example output from eb init:
   

4. You may encounter an ERROR: This branch does not have a dfault environment. In which case, use the following code:

$ eb deploy [YOUR-ENV-NAME]

Configuring DNS

Finding load balancer on AWS console:

Add load balancer URL to DNS subdomain, for example, subdomain beiwe:

---

This concludes the extra information page. For any further IT aid, please contact: