Amazon EC2

Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).

💡

This guide assumes your Mastra application has been created using the default npx create-mastra@latest command. For more information on how to create a new Mastra application, refer to our getting started guide

Setting up EC2

Log into your AWS console

Navigate to the AWS Management Console and sign in to your account.

Navigate to EC2

Head over to All services in the left side navigation. Under Compute, click on EC2.

Launch a virtual server instance

Click on Launch instance to create a new EC2 instance.

Configure your instance details

Add the following details for your instance:

Name: Give your instance a descriptive name
Application and OS Images: For this example, we’ll use the Amazon Linux environment
Instance type: Select t3.micro (eligible for free tier)
Key pair: Select an existing key pair or create a new one for secure login
Network settings: Ensure to allow HTTPS and HTTP traffic from the internet by checking the appropriate boxes

Launch your instance

Review your configuration and click Launch instance.

Connect to your instance

You’ll be redirected to a next steps page. You can connect to your instance either:

Through the browser: Click the Connect button for browser-based access
Via SSH: Use your key pair to SSH into the instance (instructions available when you click Connect)

Server Configuration

Once you have access to your EC2 instance (either via SSH or browser), follow these steps to set up your server environment:

Update the system

Update the system packages before installing any new packages.


sudo apt update && sudo apt upgrade -y

Install nginx


sudo apt install nginx -y

Ensure nginx.conf includes sites-enabled

Check if the main nginx configuration includes the sites-enabled directory. This is crucial for our site configuration to work.


sudo grep -q "include /etc/nginx/sites-enabled/" /etc/nginx/nginx.conf || sudo sed -i '/http {/a\\tinclude /etc/nginx/sites-enabled/*;' /etc/nginx/nginx.conf

💡

This command checks if the include /etc/nginx/sites-enabled/*; directive exists in the nginx.conf file. If it doesn’t exist, it adds it to the http block. This ensures that our site configuration files in sites-enabled will be loaded by nginx.

Remove nginx files if they exist

Let’s start by setting up an environment variable for the site name. In our example, we will use mastra as the site name.


export SITE_NAME="mastra"

Then we can remove the nginx files if they exist.


sudo rm -f /etc/nginx/sites-available/$SITE_NAME
sudo rm -f /etc/nginx/sites-enabled/$SITE_NAME

Set up certbot for SSL

To set up certbot for SSL, let’s start by stopping nginx temporarily.


sudo systemctl stop nginx

Now we can obtain a certificate for our domain name.

Let’s start by setting up an environment variable for the domain name and email. Replace <your-domain-name> with your domain name and <your-email> with your email.


export DOMAIN_NAME="<your-domain-name>"
export EMAIL="<your-email>"


sudo apt install certbot -y
sudo certbot certonly --standalone -d $DOMAIN_NAME --non-interactive --agree-tos -m $EMAIL

Finally, let’s ensure that the SSL files exists or we generate them.


if [ ! -f /etc/letsencrypt/options-ssl-nginx.conf ]; then
  sudo wget https://raw.githubusercontent.com/certbot/certbot/refs/heads/main/certbot-nginx/src/certbot_nginx/_internal/tls_configs/options-ssl-nginx.conf -P /etc/letsencrypt/
fi
 
if [ ! -f /etc/letsencrypt/ssl-dhparams.pem ]; then
  sudo openssl dhparam -out /etc/letsencrypt/ssl-dhparams.pem 2048
fi

Configure nginx


sudo cat > /etc/nginx/sites-available/$SITE_NAME <<EOL
limit_req_zone \$binary_remote_addr zone=mylimit:10m rate=10r/s;
 
server {
  listen 80;
  server_name $DOMAIN_NAME;
 
  # Redirect all HTTP requests to HTTPS
  return 301 https://\$host\$request_uri;
}
 
server {
  listen 443 ssl;
  server_name $DOMAIN_NAME;
 
  ssl_certificate /etc/letsencrypt/live/$DOMAIN_NAME/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/$DOMAIN_NAME/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
 
  # Enable rate limiting
  limit_req zone=mylimit burst=20 nodelay;
 
  location / {
      # Proxy to Mastra server running on port 4111
      proxy_pass http://localhost:4111;
      proxy_http_version 1.1;
      proxy_set_header Upgrade \$http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host \$host;
      proxy_cache_bypass \$http_upgrade;
 
      # Disable buffering for streaming support
      proxy_buffering off;
      proxy_set_header X-Accel-Buffering no;
  }
}
EOL

💡

To ensure there’s no issues with streaming, we need to disable buffering. That’s why we have proxy_buffering off; and proxy_set_header X-Accel-Buffering no;.

Create a symbolic link to the site in the sites-enabled directory.


sudo ln -s /etc/nginx/sites-available/$SITE_NAME /etc/nginx/sites-enabled/$SITE_NAME

Restart nginx.


sudo systemctl restart nginx

Install nodejs

We need to install nodejs to run the Mastra application. We will do this using nvm.


curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Once the installation is complete, you can verify the installation by running:


nvm --version

Now we can install the latest LTS version of nodejs.


nvm install --lts

Once the installation is complete, you can verify the installation by running:


node --version

Clone your Mastra application

Public Repository


git clone https://github.com/<your-username>/<your-repository>.git

Navigate to the repository directory.


cd "<your-repository>"

Install dependencies


npm install

Set up environment variables

Create a .env file and add your environment variables.


touch .env

Then edit .env and add your environment variables. Here’s an example:


OPENAI_API_KEY=<your-openai-api-key>

Build the application


npm run build

Run the application


node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs

Connect to your Mastra server

You can now connect to your Mastra server from your client application using a MastraClient from the @mastra/client-js package.

Refer to the MastraClient documentation for more information.


import { MastraClient } from "@mastra/client-js";
 
const mastraClient = new MastraClient({
  baseUrl: "https://<your-domain-name>",
});

Next steps

Mastra Client SDK