ContextQMD
Back to Mastra

Deploy Mastra to Azure App Services | Deployment

docs/src/content/en/guides/deployment/azure-app-services.mdx

2025-12-186.0 KB
Original Source

import Steps from "@site/src/components/Steps"; import StepItem from "@site/src/components/StepItem";

Deploy Mastra to Azure App Services

Deploy your Mastra applications to Azure App Services.

:::info This guide covers deploying the Mastra server. If you're using a server adapter or web framework, deploy the way you normally would for that framework. :::

Before you begin

You'll need:

:::warning On Azure App Services, the filesystem is ephemeral for some pricing tiers, so any local database file will be lost between deployments. If you're using LibSQLStore with a local file, configure it to use a remote LibSQL-compatible database (for example, Turso) instead. :::

Create a new app service

In these steps you'll learn how to create a new Azure App Service for hosting your Mastra application. This will set up the necessary infrastructure and environment for your application to run.

<Steps> <StepItem> Log in to the [Azure Portal](https://portal.azure.com) and navigate to **[App Services](https://docs.microsoft.com/en-us/azure/app-service/)** or search for it in the top search bar. Select **Create** to create a new App Service, and in the drop-down, select **Web App**. </StepItem> <StepItem> Configure the app service settings: 
- **Subscription**: Select your Azure subscription
- **Resource Group**: Create a new resource group or select an existing one
- **Instance name**: Enter a unique name for your app (this will be part of your URL)
- **Publish**: Select **Code**
- **Runtime stack**: Select **Node 22 LTS**
- **Operating System**: Select **Linux**
- **Region**: Choose a region close to your users
- **Linux Plan**: You may have the option of choosing a plan depending on the region you chose, pick an appropriate one for your needs.
- Select **Review + Create** and wait for validation to complete, then select **Create**.
</StepItem> <StepItem> A new deployment has been triggered. Wait for the deployment to complete, then select **Go to resource** under the next steps section. </StepItem> <StepItem> Before setting up GitHub deployment, configure your environment variables. Navigate to **Settings** > **Environment variables** in the left sidebar. Add your required environment variables, such as: 
- Model provider API keys (e.g., `OPENAI_API_KEY`)
- Database connection strings
- Any other configuration values your Mastra application requires

Select **Apply** to save the changes.
</StepItem> </Steps>

GitHub deployment

In these steps, you'll connect your Azure App Service to your GitHub repository to enable continuous deployment. This means that every time you push changes to your repository, Azure will automatically build and deploy your application.

<Steps> <StepItem> Navigate to **Deployment Center** in the left sidebar and select **GitHub** as your source. Sign in to GitHub if you're not already authenticated with Azure. 
In this example, you'll keep [GitHub Actions](https://docs.github.com/en/actions) as your provider. Select your organization, repository, and branch.

Azure will generate a GitHub workflow file and you can preview it before proceeding. Select **Save** (the save button is located at the top of the page).
</StepItem> <StepItem> After Azure creates the workflow, it will trigger a GitHub Actions run and merge the workflow file into your branch. **Cancel this initial run** as it will fail without the necessary modifications. 
:::warning
The default workflow generated by Azure will fail for Mastra applications and needs to be modified.
:::

Pull the latest changes to your local repository and modify the generated workflow file (`.github/workflows/main_<your-app-name>.yml`):
</StepItem> <StepItem> Find the step named "npm install, build, and test" and: 
- Change the step name to "npm install and build"
- If you haven't set up proper tests in your Mastra application, remove the `npm test` command from the run section as the default test script will fail and disrupt deployment. If you have working tests, you can keep the test command.
</StepItem> <StepItem> Find the "Zip artifact for deployment" step and replace the zip command with: 
```yaml
run: (cd .mastra/output && zip ../../release.zip -r .)
```

This ensures only the build outputs from `.mastra/output` are included in the deployment package.
</StepItem> <StepItem> Commit and push your workflow modifications. The build will be automatically triggered in the **Deployment Center** in your Azure dashboard. Monitor the deployment progress until it completes successfully. </StepItem> </Steps>

Verify your deployment

Once the build is successful, wait a few moments for the application to start. You can access your deployed application using the default URL provided in the Overview tab in the Azure portal. Your application will be available at https://<your-app-name>.azurewebsites.net.

Copy the URL from the Azure portal and visit https://<your-app-name>.azurewebsites.net/api/agents in your browser. You should see a JSON list of your agents.

You can now call your Mastra endpoints over HTTP.

:::warning Set up authentication before exposing your endpoints publicly. :::

Next steps