README.md

Introduction

This script sets up a "quick start" installation of Field Papers using the Amazon Web Services Elastic Beanstalk service.

Prerequisites

This script requires Python 3 (specifically, it has been tested against Python 3.4).

Package prerequisites can be installed by doing:

pip install -r requirements.txt

(This will install the boto3 AWS client library and the paramiko SSH client library.)

Usage

First, you need to set up AWS credentials that will be used to create the resources used by the Field Papers application. The Field Papers application itself does not run with these credentials -- it uses an AWS instance profile with a very restricted set of permissions (see the json/eb-policy.json.template file) -- but credentials are required to create the AWS resources needed to run the application. You can specify these AWS credentials in one of three ways:

1. Create a credential profile (using the aws configure CLI command) and run the aws-quick-start.py script as: aws-quick-start.py --profile <profile-name>.

2. Create a credential profile, set the AWS_PROFILE environment variable to the name of the profile and run the aws-quick-start.py script without arguments.

3. Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to the AWS access key and secret key you want to use and run the aws-quick-start.py script without arguments.

Then supply the following information to the script:

Name prefix

This prefix is used to generate names for all the AWS entities to be created. For example, if the prefix is CadastaTest, then the main IAM role for running the Field Papers instances will be called CadastaTestRole, and so on. Must be alphanumeric.

Main endpoint host

This is the host part of URL used to access the "front page" of Field Papers. The default value is the public-facing URL of the web server Elastic Beanstalk instance the script will launch. If you want to use a custom URL instead in a domain that you control, you will need to set up a DNS CNAME record to point from the name you want to use to the Elastic Beanstalk URL. (Once everything is set up, the script will remind you to do this, and will tell you exactly what should go in the CNAME record.)

Originating email address

This is the email address that will be used by Field Papers to send new account, password reset and similar emails. This should be an email address that has been verified for use by AWS's Simple Email Service. See here for details and note that you will only be able to send email to verified email addresses until you request lifting of Amazon's email sending sandbox restrictions.

AWS region

The AWS region in which to create all resources.

EC2 instance type for Field Papers processes

The instance type to use for creating the Elastic Beanstalk environment in which the Field Papers application runs. This script runs all of the Field Papers application components in a single EC2 instance, so the instance must be large enough to accommodate this (a t2.small instance is large enough for a test deployment).

RDS instance type for MySQL database

The MySQL database used by the Field Papers application is set up in a seperate RDS instance. In this case, a db.t2.micro instance is large enough for a test deployment.

S3 bucket name

Field Papers stores PDFs for atlas pages, uploaded snapshots and georeferenced processed snapshots in an AWS S3 bucket. These names must be globally unique.

Setup process

Once the above information is supplied, the script will ask for confirmation before proceeding to create AWS resources. (An existing setup generated by the script can be deleted by answering "DELETE" to the confirmation question.)

Once confirmation is given, the script sets up the following AWS resources:

• A key pair for accessing the EC2 instance;
• IAM policies and roles for managing the permitted actions of the Field Papers application;
• An S3 bucket;
• An Elastic Beanstalk application;
• An Elastic Beanstalk environment with associated RDS database instance.

Creating the Elastic Beanstalk environment can take quite a long time (sometimes 20 minutes or more) since AWS needs to create the RDS database instance as well as all the other infrastructure supporting the Elastic Beanstalk environment. You can watch the individual resources being created by logging into the AWS Console in your browser and going to the Elastic Beanstalk page.

The setup script waits for the Elastic Beanstalk environment to become ready (do NOT interrupt the script at this point!) then performs some post-setup tasks: initialisation of the Field Papers Rails web application, opening up port 8080 on the EC2 instance for the Field Papers tiler, and setting up the SES email identity policy that allows the Field Papers application to send email from AWS.

Once all the setup is done, the script displays the URL at which the Field Papers instance can be accessed (along with any necessary DNS CNAME record setup required to make that work) and shows how to SSH to the EC2 instance running the Field Papers application (using the SSH keys generated during the setup process).

Some details

• The Elastic Beanstalk environment is set up using the "Multi-container Docker" application type.
• Memory allocation to the individual Docker containers is done on a heuristic basis, starting from the total amount of memory available on the selected EC2 instance type.
• Docker images for Field Papers components (fp-web, fp-tasks and fp-tiler) are taken by default from the cadasta repository on the Docker Hub. These images are configured differently to the default fieldpapers images in order to work on AWS. The repository can be modified if required by setting the FP_DOCKER_REPO environment variable.
• The Elastic Beanstalk "application version" ZIP file is left in fieldpapers-ev-app-v1.zip after setup. This can be useful for subsequeny redeployment to Elastic Beanstalk (using the Elastic Beanstalk console) if required (if Docker images are changed, for instance).