Installing on Amazon Web Services¶
Warning
ODK Aggregate is no longer being updated. Please use ODK Central instead.
Warning
To use this setup, you must able to link a domain name to the machine's IP address. If you don’t own a domain, services such as FreeDNS offer free sub-domains under a range of domains.
Tip
Make sure you have selected the availability zone where you want to perform your actions. You can choose the availability zone using the dropdown menu at the top-right corner of the AWS console website. Choose a region that's close to the location where data is going to be collected.
Create a VPC¶
Go to the VPC Dashboard.
Click on Launch VPC Wizard.
Follow the wizard for the VPC with a Single Public Subnet configuration.
Enter aggregate-vpc (or your desired name) in the VPC Name field.
Click on Create VPC.
Create a security group¶
Go to the VPC - Security Groups tab.
Click on Create security group.
Follow the wizard for the VPC with a Single Public Subnet configuration.
Enter aggregate-sg (or your desired name) as the name and description.
Select the VPC you previously created.
Click on Create.
Click on the newly created security group from the list, click on the Inbound rules tab, the Edit rules.
Add the following rules to allow SSH, HTTP, and HTTPS traffic.
Type
Source
SSH
Anywhere
HTTP
Anywhere
HTTPS
Anywhere
Click on Save rules.
Create an IAM role¶
The EC2 machine needs an IAM role to query its tags.
Go to the IAM - Roles tab.
Click on Create role.
Select the AWS service box, and click on the EC2 link.
Click on Next: Permissions.
Search for AmazonEC2ReadOnlyAccess, and select it.
Click on Next: Tags and do nothing.
Click on Next: Review.
Enter aggregate-role (or your desired name) as the name.
Click on Create role.
Create an EC2 machine¶
Go to the EC2 Dashboard.
Click on Launch instance.
Search for the Ubuntu Server 18.04 LTS AMI.
Select the 64-bit (x86) option and click on Select.
Select the instance type you want to use.
A minimum setup is a t2.small instance type (1 vCPU, 2 GB RAM), but you should review your requirements and choose a bigger instance type according to your needs.
Click on Next: Configure Instance Details.
Select the VPC you previously created in the Network dropdown.
Select Enable in the Auto-assign Public IP dropdown.
Select the IAM role you previously created in the IAM role dropdown.
Toggle the Advanced Details section and copy and paste the contents of this Cloud-Config script.
Click on Next: Add Storage and edit the storage settings.
A minimum setup is 30 GiB of storage, but you should review your requirements and adjust the value of the Size (GiB) field according to your needs.
Click on Next: Add Tags.
Add a aggregate.hostname key with the domain name as the value (e.g., your.domain). This hostname will be used by the Cloud-Config script to configure your machine's HTTPS support.
Click on Next: Configure Security Group.
Select an existing security group and select the security group you previously created.
Click on Review and Launch and after review, click on Launch.
You will be offered the option of using an existing key pair or creating one. It's very important that you follow the dialog's instructions carefully to be able to access your machine once it's created.
When you're ready, click on Launch instances.
Set up your domain¶
Tip
EC2 machines use IP addresses which can change if you stop and start (but not reboot) the machine. To ensure your Aggregate install will always be reachable using the same IP address, use an Elastic IP by following these instructions.
Go to the EC2 - Instances tab and find your machine.
Take note of the IPv4 Public IP address (e.g., 12.34.56.78) and set a DNS A record pointing to it.
After clicking on the instance from the list, look for under the Description tab at the bottom of the window. The IPv4 Public IP field is in the right column.
If you own a domain, check your domain registrar's instructions. If you don't own a domain, we recommend using FreeDNS to get a free sub-domain.
Your domain's TTL setting will affect to how much time you will have to wait until you can proceed to the next step. If your provider gives you the option of setting a TTL, use the lowest value you can.
Open a web browser, and periodically check the domain until you see the Aggregate website. You won't be able to continue the install until you see the website load.
Enable HTTPS¶
Connect to your machine via SSH using ssh -i /path/to/the/key.pem ubuntu@your.domain.
Make sure your PEM key pair file has the correct file permissions.
Once you are logged in, run sudo certbot run --nginx --non-interactive --agree-tos -m YOUR_EMAIL --redirect -d YOUR_DOMAIN.
Be sure to replace YOUR_EMAIL and YOUR_DOMAIN with your email address and your domain.
Lets Encrypt uses the email you provide to send notifications about expiration of certificates.
Log into Aggregate¶
Go to https://your.domain and check that Aggregate is running.
Click Sign in with Aggregate password to login with the default username and password.
username:administratorpassword:aggregateChange the administrator account's password!