Instant GraphQL on AWS RDS

Let’s deploy Hasura GraphQL Engine on Amazon RDS, to get instant, blazing-fast GraphQL APIs on a RDS Postgres database.

TL;DR

• Create an RDS instance or use an existing one
• Deploy Hasura GraphQL on Heroku or EC2+docker
• Instant GraphQL APIs on your RDS

Create an RDS instance

If you already have an RDS instance, skip this section and go to the next section.

Log into your AWS Console, click the EC2 link to go to the RDS Console, and click the blue “Create Database” button:

Make sure to choose the “PostgreSQL” engine when creating an instance:

Note: As of writing this article Postgres 10.3 and below work. Postgres 10.4 does not work.

Click “Next” and choose “Production” or “Dev/Test” based on your use-case.

Choose a suitable instance for your RDS database:

Scroll down and setup the credentials. Keep note of the credentials (master username and password, database name etc.), which will be required later.

Choose a VPC and security group:

If you are going to deploy GraphQL engine on AWS, then make sure the VPC used here is same as the VPC used with your EC2/ECS instances.

Note: If you are planning to deploy Hasura outside AWS (e.g. Heroku), then you have to make this DB instance publicly accessible.

Note: Make sure, the security group you choose has appropriate rules for inbound connections from wherever you deploy the GraphQL engine.

Finally, click on “Create Database” button.

Use an existing RDS instance

If you already have an RDS instance with existing data, you can deploy Hasura GraphQL Engine following the below steps.

Note: If you are planning to deploy Hasura outside AWS, then you have to make this DB instance publicly accessible.

Note: Make sure, the security group associated with your RDS instance has appropriate rules for inbound connections from the GraphQL engine.

You also need to setup appropriate permissions for the Postgres user. See our docs for details about Postgres user permissions.

Deploy Hasura GraphQL on Heroku

Follow the steps outlined in our docs to deploy Hasura GraphQL on Heroku.

You would have to configure the HASURA_GRAPHQL_DATABASE_URL environment variable to point to your RDS instance. That’s all!

Deploy Hasura GraphQL on AWS

To deploy Docker containers on AWS, there are two possible ways:

1. Use EC2 instances and install docker on them
2. Use AWS ECS

If you are aiming for a production setup you should use ECS.

We will be using Docker on EC2 to deploy in this post.

Launch an EC2 instance

Log into your AWS Console, click the EC2 link to go to the EC2 Console, and click the blue “Launch Instance” button:

On the next page, you need to pick an Amazon Machine Image (AMI) to run on your EC2 Instance. For this tutorial, just pick the top option, which is the Ubuntu Server 16.04 LTS :

Next, you need to pick the Instance Type, which determines what kind of CPU, memory, storage, and network capacity your server will have. Stick with the default option, t2.micro, and click the gray “Next: Configure Instance Details” button:

In the Instance Details configuration, make sure to choose the same VPC that is used by your RDS instance.

Then keep clicking “Next” until you get to the “Configure Security Group” page. A Security Group is a set of firewall rules that control network traffic for your instance. By default, all incoming ports are blocked, so use this page to add rules that allow incoming SSH (TCP, port 22), HTTP (TCP, port 80) and HTTPS (TCP, port 443) requests from any source (0.0.0.0/0). Give the Security Group a name such as graphql-engine-test-sg, and click the blue “Review and Launch” button:

On the “Review Instance Launch” page, click the blue “Launch” button. This will pop up a modal that asks you to pick a Key Pair. This used to connect to your EC2 instance over SSH. Select “create a new key pair” from the drop-down, give the Key Pair a name like my-ec2-key-pair, and click “Download Key Pair”:

NOTE: Save the Key Pair .pem file to a safe and accessible location on your computer (once you close this modal, you will never be able to download this .pem file again, so make sure to save it!).

Now if you go to your EC2 dashboard, you should see your EC2 instances running.

Installing Docker

The next step is to install Docker on your EC2 Instance. Open a terminal, cd over to the folder where you saved your Key Pair, and run the following commands:

$ cd ~/my-aws-key-pairs
$ chmod 400 my-ec2-key-pair.pem
$ ssh -i my-ec2-key-pair.pem ubuntu@<EC2-INSTANCE-PUBLIC-IP-ADDRESS>

Once you are logged in, install Docker:

$ sudo apt-get update
$ sudo apt-get -y install docker docker-compose

Then let’s add this user to the docker group, so we can run docker commands without sudo:

$ sudo usermod -a -G docker ubuntu

Exit the shell and login again. Check if docker works:

$ exit
$ ssh -i my-ec2-key-pair.pem ubuntu@<EC2-INSTANCE-PUBLIC-IP-ADDRESS>
$ docker info

Deploying Hasura GraphQL Engine

Save the following docker-compose snippet into file docker-compose.yaml

Change the HASURA_GRAPHQL_DATABASE_URL to point to your RDS instance, and HASURA_GRAPHQL_ACCESS_KEY to a long random string.

Then run:

$ docker-compose up -d

Check if the container is running:

$ docker ps

CONTAINER ID IMAGE ... CREATED STATUS PORTS ...
097f58433a2b hasura/graphql-engine ... 1m ago Up 1m 8080->8080/tcp ...

The status should be "Up". If the status is not up, check logs with docker logs <container-id>

Access GraphQL engine console

Now go to the public IP address of the EC2 instance on your browser and it should open up the Hasura console.

It should prompt for the access key, enter the access key you used in the above steps. Access the console and make GraphQL queries!

Troubleshooting

If you can't access the console, check the GraphQL Engine docker logs. By running docker logs <container-id>.

Postgres connection failed / Connection refused

If the public IP is not accessible, check the docker logs. If the logs say postgres connection failed or something along those lines, it is most likely a security group issue. You would have to edit the security-group associated with the RDS instance.

Go to the security-group of the RDS instance, and then to the "Inbound" rules. Click on "Edit", and then click on "Add Rule". Select "PostgreSQL" from the type dropdown and add the Private IP of your EC2 instance. You have to add it in a CIDR format, so it should be x.x.x.x/32. Then click "Save". Now check the logs again if graphql-engine sucessfully connects to the RDS instance.