Running on AWS

Follow these steps to create a Cloud Formation template:

• Copy the config/samples/cf-template.properties file to another location and change the name to, for instance, my-cf.properties. Edit the copied file as desired, and check it into source control.

Note that, by default, the CloudFormation properties only allow you to access the transactor from other EC2 machines.

You can enable access from anywhere if desired, simply uncomment the line:

aws-ingress-cidrs=0.0.0.0/0

Communication with the transactor is protected with a randomly generated username/password that are communicated to peers via the Storage Service (access to which is secured).

You can modify this setting later, but it is easier to do it now!

• Export your AWS account's credentials as environment variables so that they're accessible to scripts:

export AWS_ACCESS_KEY_ID=<aws-access-key-id>

export AWS_SECRET_KEY=<aws-secret-key>

• Run the ensure-cf command, specifying your properties file as the input and another file name as the output (the file names can be the same):

bin/datomic ensure-cf my-cf.properties my-cf.properties

The ensure-cf command will create the necessary AWS constructs, and emit an updated properties file containing information about what it created. If errors are reported, fix them, then repeat the process.

• Run the create-cf-template command, specifying both your transactor properties file and your CloudFormation properties file as input, and redirect the output to a JSON file:

bin/datomic create-cf-template my-transactor.properties my-cf.properties cf-template.json

Use the create-cf-stack command to run the configuration you have defined on AWS, passing the name of the stack and the template you previously created:

bin/datomic create-cf-stack us-east-1 MyTransactor cf-template.json

That's it! In a few minutes, you will have a transactor running on AWS. You can monitor the status of the stack you created via the AWS CloudFormation Console.

You can now run EC2-based peer applications against the transactor AMI.

Use the delete-cf-stack command to tear down the stack and stop all associated running instances with cf-delete-stack:

bin/datomic delete-cf-stack us-east-1 MyTransactor

If you've enabled access to your transactor from anywhere, then, after your CloudFormation stack launches, you can connect to it as described in setting up storage services. If you do not enable access, you can only connect to it from another EC2 instance in the same security group.

To enable log copying, uncomment this line in your transactor properties file:

#aws-s3-log-bucket-id=

If you leave the values blank, an S3 bucket will be created for you. Alternatively, you can specify an existing bucket. The IAM role specified by the aws-transactor-role property will be assigned a policy granting write access to the bucket.

To enable CloudWatch metrics, uncomment these lines in your transactor properties file:

#aws-cloudwatch-dimension-value=your-system=name
#aws-cloudwatch-region=

Specify a unique name for aws-cloudwatch-dimension-value and the desired AWS region for aws-cloudwatch-region. The IAM role specified by the aws-transactor-role property will be assigned a policy granting write access to CloudWatch.

Once your property file is edited, run the ensure-transactor command, specifying your properties file and another filename as the output (the file names can be the same).

bin/datomic ensure-transactor my-transactor.properties my-transactor.properties.

The ensure-transactor command will create the necessary AWS constructs, and emit an updated properties file containing information about what it created. If errors are reported, fix them, then repeat the process. Check the final file into source control.

Start your transactor with the properties file output by the ensure-transactor command and one or both features will be enabled.

To enable log copying, uncomment this line in your transactor properties file:

#aws-s3-log-bucket-id=

Set its value to the name of an existing S3 bucket.

To enable CloudWatch metrics, uncomment these lines in your transactor properties file:

#aws-cloudwatch-dimension-value=your-system=name
#aws-cloudwatch-region=

Specify a unique name for aws-cloudwatch-dimension-value and the desired AWS region for aws-cloudwatch-region.

To enable the transactor to access the AWS resources you specify, you must attach the following policies to the transactor role:

{"Statement":
 [{"Effect":"Allow",
   "Action":["s3:PutObject"],
   "Resource":
   ["arn:aws:s3:::{bucket-name}", "arn:aws:s3:::{bucket-name}/*"]}]}

{"Statement":
 [{"Resource":"*",
   "Effect":"Allow",
   "Action":
   ["cloudwatch:PutMetricData", "cloudwatch:PutMetricDataBatch"],
   "Condition":{"Bool":{"aws:SecureTransport":"true"}}}]}