April 05, 2018

How to deploy a Prisma server to AWS Fargate using Docker & CloudFormation

Learn how to use the new AWS ECS container service Fargate to deploy a Prisma server with a connected database (Tutorial)

⚠️ This article is outdated as it relates to Prisma 1 which is currently in maintenance mode. To learn more about the most recent version of Prisma, read the documentation. ⚠️

Note: This article only applies to Prisma versions lower than 1.7 and will be updated soon.

Prisma servers provide the runtime environment for your Prisma services. In this tutorial, you’re going to learn how to deploy a Prisma server to AWS Fargate. The server will be backed by a MySQL database which you’re going deploy to AWS RDS first.

AWS Fargate is a new tool for Amazon ECS and EKS that allows you to run containers without having to manage servers.

Overview

When building GraphQL servers with Prisma, there are three backend components that need to be deployed:

  • Your GraphQL server (commonly implemented with graphql-yoga)
  • Your Prisma server & services
  • Your database

Here is a high-level diagram indicating the architecture of your backend:

In previous tutorial on this blog, you learned how to deploy the GraphQL server using ZEIT Now and Apex Up. Today, you’re going to learn how to deploy a Prisma server using AWS Fargate. Since every Prisma server is backed by a database, you’ll also learn how to deploy a database along with it.

You can deploy to Fargate in several ways. For this tutorial, you’re going to use preconfigured CloudFormation templates and the AWS Console GUI.

1. Deploying a MySQL database to RDS

While there are many ways to deploy databases with RDS (e.g. using the AWS GUI), you’re going to use a CloudFormattion template for this tutorial.

1.1. Getting the CloudFormation template

You can obtain the CloudFormation template for the MySQL database from our database-templates GitHub repository. Simply clone or download the entire repo. It currently contains templates for MySQL (aws/mysql.yml) and AWS Aurora (aws/aurora.yml).

1.2. Creating your CloudFormation stack

Next, you’re going to create the CloudFormation stack for the MySQL database based on the template you just downloaded. Navigate to https://console.aws.amazon.com/cloudformation/ and login (if necessary).

Attention: Fargate is currently only available in the US East (N. Virginia) region. So be sure to select this region in the top-right corner of the AWS console!

Once you have the US East (N. Virginia) region selected, click the Create Stack button. On the next screen, you then need to provide your CloudFormation template.

Click the Choose File button and select the mysql.yml file from the location where you previously downloaded the database-templates repo. Then click Next.

Note: If you’d like the aurora.yml template instead, you’ll need to create a service linked tole in IAM using this CLI command: aws iam create-service-linked-roleaws-service-name ecs.amazonaws.com. You can find more info about this here. Thanks to John Walsh for figuring that out!

On the next screen, you need to provide the Stack name as well as a Database Password. You can choose anything you like for that — note that the Database Password needs to be at least 8 characters long.

For this tutorial, we’re choosing the following values:

  • Stack name: my-mysql-db

  • Database Password: Prisma123 (be sure to pick a secure password and note it down, you’ll need in the next section)

You can leave the remaining parameters as they are and click Next.

On the next screen, you don’t need to configure anything and can directly click Next again.

On the last screen, go ahead and click the Create button to launch the stack.

1.3. Wait ️️️️☕️

That’s it for the DB setup — you can now go and grab a coffee, it usually takes around 15 minutes until the stack is available.

While you’re waiting, here are a few articles you might find interesting 😏

1.4. Save database details

When setting up the Prisma server in the next section, you’ll need to connect it to the database which you just deployed. You will do so by providing a host and port.

Both pieces of information can be retrieved from the Outputs tab that you can navigate to once you selected the my-mysql-db in the stack list.

Save the DatabasePort and DatabaseEndpoint as you’ll need them in the next section.

2. Deploying a Prisma server to Fargate

2.1. Getting the CloudFormation template

The Prisma server is deployed via a CloudFormation template as well. So, just like before you first need to get access to that template.

You can find it in the prisma-templates GitHub repository. Clone or download that repo so you can use provide the template in the next step.

2.2. Creating your CloudFormation stack

Like in the previous section, navigate your browser to https://console.aws.amazon.com/cloudformation and click the Create Stack button (be sure to have the US East (N. Virginia) region selected in the top-right corner).

Next, select the fargate.yml template you downloaded in the previous step. Then move on to the following screen by clicking Next.

Here you need to provide some additional information about your Prisma server, e.g. which database it should connect to. Again, for the Stack name you can choose anything you like, for this tutorial we’re using my-prisma-cluster.

2.2.1. Generate key-pair and set the ClusterPublicKey parameter

The ClusterPublicKey is used to ensure only authorized people can deploy services to your Prisma server. The private counterpart of this key will be used by the CLI when running prisma deploy (and any other commands that are targeting your server).

There are several ways to generate a public/private-key-pair. In this tutorial, you’re going to use the Prisma Cloud API. This is purely for convenience, feel free to choose any other tool to generate your key-pair (such as openssl).

Navigate your browser to https://api.cloud.prisma.sh and run the following query in the Playground:

query {
  generateKeypair {
    private
    public
  }
}

The response to this query will be a JSON object that carries a private as well as a public key. Store the private key securely, you’ll need it in a bit.

Then copy the entire public key and paste it into the ClusterPublicKey field in the AWS Console.

2.2.2. Provide database connection details

Next, you need to ensure that the Prisma server knows which database it can use to store the data belonging to the Prisma services. This will of course be the database that you deployed in the previous section.

Now it’s time to reuse the data from step 1.4.: Copy the DatabaseEndpoint from before and paste it into the DbHost field. It should look somewhat similar to this: prisma.cvg9pd7kwxj1.us-east-1.rds.amazonaws.com.

The DbPassword is the Database Password you specified in step 1.2.. Assuming you haven’t changed anything, that’s Prisma123.

If you previously haven’t changed anything about the port, the DbPort is already correctly set to 3306.

Finally, the DbUser is just called prisma (unless you specified a different value for Database Username value in step 1.2.).

2.2.3. Specifying the PrismaVersion parameter (must be at least 1.6.)

Lastly, you need to provide the PrismaVersion which refers to the version of the Prisma Docker image you want to use.

Attention: Fargate deploys only work with Prisma 1.6. and greater. At the time of writing this tutorial Prisma 1.6. is still in beta — this doesn’t affect the deploy.

Select the 1.6-beta (or some later) version from the dropdown.

With all that information in place, go ahead and click Next to move on.

2.2.4. Launch the stack

You don’t need any configurations on the next screen, so you can just skip it by clicking Next again.

On the last screen, you only need to check the checkbox at the bottom of the screen, confirming the following statement: I acknowledge that AWS CloudFormation might create IAM resources.

Finally, click the Create button to launch the stack.

2.3. Wait ☕️

2.4. Save the server endpoint

Once the stack has been launched, you need to save the endpoint of the server.

Similar to what you did with the database stack before, first select the my-prisma-cluster stack from the list and then open the Outputs tab for it. Then, go ahead and save the value for the ExternalUrl field, you will need it in the next step.

3. Configuring the deployed server in the Prisma CLI

To be able to deploy Prisma services to your new server, the Prisma CLI that’s installed on your machine needs to be aware of it.

You can use the prisma cluster add command to provide the information the CLI needs to work with the new server in the future.

ATTENTION: This tutorial is based on Prisma 1.6.3. Note that the Prisma 1.7release introduced a few major changes which are not yet applied in this tutorial. Thus, please make sure to install the 1.6.3 version of the Prisma CLI with the following command: npm install -g prisma@1.6.3

Run the prisma cluster add to tell the CLI about your new server! The CLI will prompt you to provide three pieces of information:

The CLI now added a new entry with that information to your server registry (.prisma/config.yml). This file is located in your home directory and contains a list of servers you can deploy your services to.

With the new cluster entry, it looks similar to this:

cloudSessionKey: >-
  eyJhbGciOiJIUzI1NiisInR5cCI6IkpXVCJ9.eyJ1c1VySWQiOiJjamNndWpuZGJxMXMxMDEwMmh5ODUwamFxIiwiaWF0IjoxNTE5MzgzNDQ3LCJleHAiOjE1MjE5NzU0NDd9.-bi4FKpC43EcYsaO0q1-dU7i3dJXW7NQm8DJEs__3lw
clusters:
  fargate-cluster:
    host: 'http://my-pr-Publi-1GXX8QUZU3T89-433344553.us-east-1.elb.amazonaws.com'
    clusterSecret: "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEpAIBAAKCAQEA0K+J5Mv2gY2xhAfqjc1U1OgLtG58YkkKRQVdE9ETz9gxD1ER\r\nODJmFIc7DgLKlvIVnDCcL+pbbjG3CA3V1WOk95YqcH0BJCye3VluGkZjnLfXlxRd\r\n13QbWteLEHogOuW53cv9i8APLBd5DBy7YCOi27c8NxUT42/JIafIiQIaQz9pC/80\r\nd4O2h+eKpNvq3mGAudn9DoLy0WYSuIB4mQrF1fl7VExnm+qwyoIysVrxwCvWDWvV\r\nHyxMjJkctcHuIdu9lVqEykw4uWXjasoYlMMWQWw7qQ537agQVPMH72phlzvJdCUN\r\n1ANkyrTA9EyZUcWP+phw89LEzn4gHPMyRUBRXwIDAQABAoIBAQC0tk4DA10D81+1\r\npeVHxq8Lb6YzKTotInLyMiLX9kXhxqU1Tk5LC9m6DSDmkSQ+coSkLLQUCi4Czqph\r\nHxn9H7zLag52OsmyObGYnMjrl+jK3aij+88HtFO75stWCWu/lQ/PMcbuLfL1i54X\r\nDwpzxmhRO+u5B1ehrDvQGSte+aMkd0NJFE5oPq/PuT36vATSOrFFPXun6z/vga6l\r\nToL4itKmzEvmrbb0OI7n1tO/HKJpFTS/evSvf2uaaNMi51yGspMmtpYM0ApODzU7\r\nQ+2/qe7KMbmQtLnz3PSEexNADGjaqxhLO838ihAlOFx2HM0YxyQzsMi3OQZHcAAg\r\nIMQtTuCBAoGBAPngY+Zw8ie6ssuJ0veW9M+9VRmELWKRIGimKOBtegj8lmLcFPR8\r\n/Ezdp6glwni8ZJRZyb2U0y60NCeWpySncbj6SY6Re84bY+6xWrb36CHvdTQkkdaA\r\nbTB5h2XBULJBR7w6xLT7A+nkiBnyCbq2y/C+ms27dOXkqhn8wMhMndMdAoGBANXM\r\nvHiNL4J3kTYaH6/gb1iS70TOXOPHlyggpTdIAwKiQEuzESLa36cd+mPC4QAZG347\r\n+HcNG7gJPGgvg0wMkeK24aFnDMsxtEhBFIvRb2wumPhZn5Yzdbr4Sq/8vC4KcR2B\r\nv4CmXi/XfBul+0JAhbmHY8ePQYSMxJ3oCrLyjvGrAoGAESZXdO93j0Z/Ev0on5ma\r\nv89M0e2Cd+tiAAy3bX/WClvbrnlQbt9NKbFk2mOND2BOvufSstJOFDyF/9mVKyza\r\n30k+VyyhBKpYl39QrJIjOoEG2EdSQxiZZeRRaKh182YLmF2oNour3xeyR6WXCVuW\r\nb7WFRm2BPm4NRq9UQ+sOQfkCgYB3dGoFjRTzd2zZ5qS3ttVfjtFDB24dEmJhWEQX\r\nbBPKf+8enJFBgTse+3/wB22BiYWz9TvxAJDxNa/bolhgwFEuc/IDJTmfuki5aitZ\r\np43yyuJLOIATAvOPoLTSOYrGyqzCyMC/17SeVG6SYB3PuY89xui4ElGQBrrAY2q+\r\n6wl0+wKBgQD05e5DfzeIWP9nF5B/MEB2ndPV8PIlf4lHetO8MUpmb7nk/G0s2zQL\r\nmZQDh2HGucUXRbBjERFrLa3V7e/mdAoY9phPmttbfz4N38noNpIORiqmygMCErRj\r\nASi5i1pJI5LyTfEgg/3lbv/55ArAivNrf3fPxCcsFcOJmIXnbdr+7w==\r\n-----END RSA PRIVATE KEY-----\r\n"

4. Deploy a Prisma service to the new server

It’s time to put your new server in use and deploy a service to it. In a location of your choice, run the following command in the terminal:

prisma init my-prisma-service

This prompts you to select a template for the Prisma service. You’re only interested in deploying a Prisma service right now (as opposed to an entire GraphQL server or a fullstack app), so just choose Minimal setup: database-only.

After that selection, the CLI created a new directory called my-prisma-service with your project files. Navigate into it and run prisma deploy:

cd my-prisma-service
prisma deploy

The CLI now prompts you with a list of available servers, among them the new fargate-cluster. Select it from the list and hit Enter.

After you selected the server, the Prisma service is deployed to it. Notice also that the CLI added the server: fargate-cluster entry to your prisma.yml file. For all future deploys, the CLI will target this server by default. To bring up the prompt again, simply remove the entry from prisma.yml.

After the command has finished running, the CLI outputs the URL of your Prisma service. You can now test the Prisma services which is running on your very own Prisma server on AWS Fargate 🎉

Summary

In this tutorial, you learned how to deploy a Prisma server with a backing database to AWS Fargate. In both cases, you were using preconfigured CloudFormation templates for the deployment process.

Join the discussion

Follow @prisma on Twitter

Don’t miss the next post!

Sign up for the Prisma newsletter