Introduction
This tutorial is currently broken. Please reach out to us if you want to help updating it.
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 other tutorials, you can learn 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.
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.
Getting the CloudFormation template
You can obtain the CloudFormation template for the MySQL database from our database-templates GitHub repository.
Go ahead and clone or download the entire repo. It currently contains templates for MySQL (aws/mysql.yml) and AWS Aurora (aws/aurora.yml).
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), US East (Ohio), US West (Oregon), and EU (Ireland) regions. So be sure to select one of these regions in the top-right corner of the AWS console!
Once you have a fargate-supporting 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.ymltemplate instead, you’ll need to create a service linked role in IAM using this CLI command:aws iam create-service-linked-role --aws-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.
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 blog articles you might find interesting 😏
- How to wrap a REST API with GraphQL
- Reusing & Composing GraphQL APIs with GraphQL Bindings
- GraphQL Server Basics: GraphQL Schemas, TypeDefs & Resolvers Explained
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.
Deploying a Prisma server to Fargate
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.
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), US East (Ohio), US West (Oregon), or EU (Ireland) 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-server.
2.2.1. Set the ManagementApiSecret parameter
The ManagementApiSecret is used to ensure only authorized people can deploy services to your Prisma server. The CLI needs to provide a JWT that was generated based on this secret when accessing the Prisma server (e.g. when you're running prisma deploy).
For the purpose of this tutorial we're choosing protecting-my-prisma-server as the value for ManagementApiSecret.
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 its 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.
Select 1.6 (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.
Wait ☕️
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-server 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.
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 to create the file structure for a new Prisma service:
prisma init my-prisma-service
This command prompts first prompts you to select the Prisma server to which the new service should be deployed.
From the provided option, select Use other server and hit Enter.
The "other server" will be the one that you just deployed to AWS Fargate - so you need to provide the connection details to the CLI.
Next, the CLI prompts you to specify the endpoint of the Prisma server. Here, you need to provide the ExternalURL from step 2.4.. It should look similar to this: http://my-pr-Publi-1GXX8QUZU3T89-433349553.us-east-1.elb.amazonaws.com
For the following prompts, you can simply hit Enter to choose the suggested values.
After those selections, the CLI creates a new directory called my-prisma-service with your project files.
Before deploying your service with prisma deploy, you need to ensure the Prisma CLI is authorized to access your Prisma server. To do so, you need to set the PRISMA_MANAGEMENT_API_SECRET environment variable in your shell. The CLI will read this environment variable and generate a JWT based on it which it uses to authenticate against the server.
Set the PRISMA_MANAGEMENT_API_SECRET environment variable in your terminal:
export PRISMA_MANAGEMENT_API_SECRET="protecting-my-prisma-server"
Note: Depending on which shell you're using, the command for setting environment variables might look different.
Next, navigate into it and run prisma deploy:
cd my-prisma-service
prisma deploy
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 🎉
Manage your AWS Fargate server through Prisma Cloud (optional)
You can also manage your Fargate server by connecting it to Prisma Cloud. This gives you additional visibility into your usage and a data browser for another view of your data.
There are several steps necessary to connect:
Add your AWS Fargate server to Prisma Cloud. You can access Prisma Cloud via the Prisma console. After logging in, click on servers in the navigation bar, and then select the green "Add Server" button.
From there, name and describe your server. For the sake of this tutorial, we'll go ahead and call it, "fargate"
On the next page, add in your Server endpoint— which is the same URL highlighted in Step 23 and used again in Step 26. It should look something like this:
http://my-pr-Publi-1GXX8QUZU3T89-433349553.us-east-1.elb.amazonaws.com
Additionally, fill in your Connection secret. If you are using the example from the tutorial, that would be: protecting-my-prisma-server; otherwise, enter in your own.
When the connection has been established, you will see a message that says, "Done creating server" and a button: Back to Servers.
After adding your server, the associated service should be added to the services page. From there you can explore your data via the data browser, review your deployment history, and find a shortcut to the GraphQL Playground.
For a visual walkthrough, you can also watch this 4min-video for more information.
Deleting your CloudFormation Infrastructure (optional)
After you've spun up all of your infrastructure, you are eligible to be billed by Amazon. If you decide that you want to delete your CloudFormation stacks, you can do that through the Amazon interface.
Go to the CloudFormation dashboard on AWS.
In order to access your CloudFormation setup, you need to ensure that you are in the right AWS region.
Double check that the region in the top navigation bar matches where your CloudFormation stack is located. If you are looking at a different region, you will not be able to see your CloudFormation details.
Once you are in the correct region, you can delete the CloudFormation instances by clicking on each stack. For each stack, select the righthand dropdown: Other Actions. From there, you can choose to delete the stack. Once you've done that for one, don't forget to the delete the other as well.
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.