AWS setup

For your convenience, Geopoiesis provides Terraform templates to set up all the dependencies for the application. In this article, we will walk you through using vanilla terraform binary, but feel free to use some other system (eg.terragrunt, or another installation of Geopoiesis) as long as you're comfortable with its API.

Terraform config

First, let's create a root Terraform file in a new directory:

root.tf
terraform {
backend "s3" {
bucket = "geopoiesis-backend"
key = "state.json"
region = "us-east-1"
}
}
provider "aws" {
region = "us-east-1"
}
module "geopoiesis-backend" {
source = "github.com/geopoiesis/terraform//aws?ref=0.6.0"
}
module "geopoiesis-user" {
source = "github.com/geopoiesis/terraform//aws/iam_user?ref=0.6.0"
policy_arn = "${module.geopoiesis-backend.policy_arn}"
}

Before we move further, a few notes on the above example. First, we're using remote Terraform state with S3 backend (without locking). The bucket name in this example is geopoiesis-backend - this is completely arbitrary but you will need to make sure that the bucket you're referring to here exists and that you have access to it.

Second, we are setting up the resources it in AWS us-east-1 region. Depending on where you are it may or may not be a good idea. Always try to keep your storage and your compute as close as possible to each other.

We assume that you have access credentials to the AWS account in your environment, and that these are strong enough to be able to create a bunch of resources across multiple services. You can read more about all possible ways of setting up AWS Terraform provider here, but if AWS CLI works fine on your machine then chances are you can run this example without any further setup.

Setup process

Running the setup is a very standard Terraform operation. First, you initialize your new Terraform workspace:

$ terraform init

This should download Terraform providers and remote modules from GitHub to your local .terraform folder. Then, you run:

$ terraform apply

Terraform will show you the list of resources that would be created. If the list looks good, apply the changes. You can also perform a dry-run:

$ terraform plan

This is especially useful further down the road when you're changing your Geopoiesis setup using this little Terraform project.

While AWS offers a very generous free tier and most created resources will easily fall into that, there may be some charges for CloudWatch rules related to DynamoDB autoscaling. From our experience, this should not exceed $6 per month.

User credentials

Now that your Geopoiesis backend resources are created, you will want to retrieve user credentials from the state file. Technically you could give Geopoiesis strong admin credentials you used to run the above example, but this is not advised, especially in production.

If you used S3 remote state as suggested above, use AWS CLI or go to the web console to retrieve state.json file from your S3 bucket. In there, search for aws_iam_access_key.geopoiesis. The relevant section should look like this:

"aws_iam_access_key.geopoiesis": {
"type": "aws_iam_access_key",
"depends_on": [
"aws_iam_user.geopoiesis"
],
"primary": {
"id": "AWS_ACCESS_KEY_ID",
"attributes": {
"id": "AWS_ACCESS_KEY_ID",
"secret": "KEY_SECRET",
"ses_smtp_password": "irrelevant",
"status": "Active",
"user": "geopoiesis"
},
"meta": {},
"tainted": false
},
"deposed": [],
"provider": "provider.aws"
}

Make note of the value of id and secret - you will want to pass those to your Geopoiesis app environment as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables, respectively.

Other settings

Two other dynamically defined settings your new Geopoiesis installation will need to know are KMS key ID and full S3 bucket name. These can also be found in the state file. The KMS state entry will look something like that (with irrelevant bits removed for brevity):

"aws_kms_key.geopoiesis": {
"type": "aws_kms_key",
"primary": {
"id": "d24fdb53-a0d7-435c-b409-9cc2f1f656b0"
},
"provider": "provider.aws"
}

Make note of the id bit to use it as the value of AWS_KMS_KEY_ID environment variable in the configuration step.

S3 bucket will be represented roughly this way, again with irrelevant bits removed:

"aws_s3_bucket.geopoiesis": {
"type": "aws_s3_bucket",
"primary": {
"id": "geopoiesis-arpe8ik4jskar1s8"
},
"provider": "provider.aws"
}

Again, you will just need the id bit to be used in the configuration step later on.

Make note of the id bit to use it as the value of AWS_S3_BUCKET environment variable in the configuration step.

The Geopoiesis bootstrap templates library has more knobs to tweak, and more modules available. After you're comfortable with your initial Geopoiesis installation, we kindly invite you to take a deeper look at its API.