[Old] Single Server AMI

This is a deprecated platform for hosting the Beiwe-Backend.

The AMIs are out of date and have been deleted. This page is present only for legacy documentation for existing users of the AMI.

---

Note: if you're looking for instructions on how to update a Beiwe cluster from Python 2.7 to 3.6, read the page Upgrading from Python 2 to 3.

These instructions assume that your computer runs Linux, MacOS, the Windows Subsystem for Linux, or the Cygwin posix environment on Windows. If you are have the expertise to run the Beiwe Backend directly on Windows and encounter an issue that may be a compatibility please report it as a bug with the proper caveat, we will try and assist you.

Beiwe AWS setup and deployment instructions

There are two ways to set up Beiwe: the easy way (single-server Amazon Machine Image, or "AMI"), and the robust, scalable way (setting up a server cluster).

Quick setup (single-server AMI)

The AMIs Below are configured for the legacy Python 2 version of the Beiwe Backend. Updating to the newer Python 3 codebase is non-trivial and untested. There is an open issue (#119) for this.

This sets up a Beiwe deployment on a single Amazon EC2 server. The setup process is comparatively simple, but the deployment doesn't scale well and may not run reliably for an extended time without maintenance. This is a good way to evaluate the Beiwe platform, but if you're using a single-server Beiwe deployment, we don't recommend supporting more than 20 total study participants or running the server for more than a month. For a more robust and scalable deployment, see the more involved option: setting up a Beiwe server cluster.

AMI ID	Region
Beiwe_v0.2 (ami-d97ddea6)	us-east-1 (Virginia)
Beiwe_v0.2_Europe (ami-2b606452)	eu-west-1 (Ireland)
Beiwe_v0.2_Australia (ami-8d4f9def)	ap-southeast-2 (Sydney)

Launch your server from the public Beiwe AMI

1. Log in to your Amazon Web Services account, or create one by going to https://aws.amazon.com and clicking "Create an AWS account".

2. Launch the most recent Beiwe AMI by clicking one of the AMI links above. This will take you through a series of screens to launch an AWS EC2 server in an Amazon data center in Virginia or Ireland:

   1. This should take you to a screen in the AWS web console titled "Step 2: Choose an Instance Type". Deploypments handling live studies will experience the most consistent performance on C5/C5a and M5/M5a servers, low-load deployments can use T3-series servers. A C5.large is able to handle quite a lot of traffic, and should cost about $62/month according to ec2instances.info. If you require anything greater than this consider using a cluster deployment.

   2. On step 3, "Configure Instance Details", set "Auto-assign Public IP" to "Enable".

   3. On steps 4 and 5 ("Add Storage" and "Add Tags"), you don't need to make any changes from the defaults, but you can if you wish.

   4. On step 6, "Configure Security Group", add two rules: allow HTTP from all IP addresses, and allow HTTPS from all IP addresses.

   5. Launch your instance- this will take a few minutes.

3. At this point, you should be able to see and log in to the web interface on your new Beiwe server. In the AWS web console, go to the table of EC2 instances in the us-east-1 region, find the instance you just started, and copy the IPv4 Public IP- this is your server's IP address. Enter that IP address into your browser's address bar, and you should see a login page. You can log in with the username default_admin and password abc123. You can test all the features in the Beiwe web interface, but it's not secure yet, you can't create study participants, study participants can't upload data, and you can't download data. To fix those issues, follow the next steps.

Configure security and data storage on your server

1. SSH into your instance from your local computer, using the key you selected during the launch process. You should store the key somewhere on your computer; on Linux and Mac OS, a good default location is the ~/.ssh directory. On Linux, you'll also need to chmod 600 the key file. Once you've done that, SSH into your instance like this:

   $ ssh ubuntu@[Your server's IPv4 address] -i [Filepath of your SSH key]
   

2. Replace Flask's secret key with a random string. On the server, run this command:

   $ sed -i -r 's/replace_with_random_string/'$(cat /dev/random | tr -dc \"a-zA-Z0-9\" | fold -w 32 | head -n 1)'/g' ~/beiwe-backend/config/remote_db_env.py
   

   Then reload the Flask app:

   $ touch $HOME/beiwe-backend/wsgi.py
   

3. Point your domain name to this server. (This is a prerequisite for adding an SSL certificate). In your DNS provider, point an A record to the IPv4 address (labeled "IPv4 Public IP" in the AWS web console's EC2 instances table), or point a CNAME record to the address labeled "Public DNS (IPv4)" in the EC2 instances table.

   • Once you've set up a domain name, open the Apache config file. Here's how to edit it with nano, a command-line text editor:

     $ sudo nano /etc/apache2/sites-enabled/000-default.conf
     

     In the Apache config file, find the line beginning with ServerName, and replace beiwe.org with your domain name. Then restart Apache from the command line like this:

     $ sudo service apache2 restart
     

4. Add an SSL Certificate. We recommend using Certbot (follow the documentation here).

5. Reset the password for the user with username admin. Once you've logged in on your server's web interface, click "Manage Credentials" in the top navigation bar, and reset your password to something secure.

6. Attach an S3 bucket:

   1. Create an S3 bucket in the AWS web console.

   2. Also in the AWS web console, create an IAM user with "Programmatic access" and with this policy attached (but replace "[Your S3 bucket name]" with the name of your S3 bucket):

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": "s3:*",
                  "Resource": "arn:aws:s3:::[Your S3 bucket name]*"
              }
          ]
      }
      

   3. On your server, in the file ~/beiwe-backend/config/remote_db_env.py, update these three values:

      os.environ['S3_BUCKET'] = ''                   # Replace with your S3 bucket's name
      os.environ['S3_ACCESS_CREDENTIALS_KEY'] = ''   # Replace with your IAM user's Secret Key
      os.environ['S3_ACCESS_CREDENTIALS_USER'] = ''  # Replace with your IAM user's Access Key
      

   4. Run $ sudo service apache2 restart

7. Remove any SSH keys you don't recognize from the file ~/.ssh/authorized_keys (there may be an authorized SSH key left in that file as part of the AMI generation process). But don't delete the key you do use to SSH into your server, or you won't be able to get back in!

8. Create a study on your new server, and test it by downloading the Beiwe2 Android app from Google Play or the Beiwe2 iOS app from the App Store and registering as a participant. The Beiwe2 app allows you to specify a custom domain name during registration/enrollment; the Beiwe app at studies.beiwe.org/download doesn't allow you to use a custom domain (it only connects to studies.beiwe.org.

Updating your single-server deployment

After you've set up your deployment, you need to update it with new commits from GitHub. To do this:

1. Update the code: SSH into your server, cd into $HOME/beiwe-backend, and run $ git pull.

2. Update requirements: Run $ pip install -r requirements.txt. If that fails, try it again with sudo.

3. Update environment variables: Now that you've updated the code, check if there are any new variables defined in config/remote_db_env.py.dummy that aren't defined in config/remote_db_env.py, and if there are any, copy them to config/remote_db_env.py, and define them if necessary.

4. Update cron: Look at the file services/ami_cron_target.py, which has several predefined frequencies: FIVE_MINUTES (intended to be run every 5 minutes), HOURLY, FOUR_HOURLY, DAILY, AND WEEKLY. Some predefined frequencies have lists of tasks to run; others are blank.

   Now edit the crontab file with the command $ crontab -e. Don't use sudo, because you want to edit the crontab file for the ubuntu user, not for the root user. If services/ami_cron_target.py has any predefined frequencies with tasks to run, make sure those frequencies are also scheduled in the crontab file. If they aren't in the crontab file, add them at the appropriate schedules.

5. Update the database schema by running $ python3 manage.py migrate.

6. Restart Apache: $ sudo service apache2 restart.