Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure App Service provides a highly scalable, self-patching web hosting service using the Linux operating system. This tutorial shows how to create a secure Node.js app in Azure App Service that's connected to a Azure Cosmos DB for MongoDB database. When you're finished, you'll have an Express.js app running on Azure App Service on Linux.
In this tutorial, you learn how to:
You can quickly deploy the sample app in this tutorial and see it running in Azure. Just run the following commands in the Azure Cloud Shell, and follow the prompt:
mkdir msdocs-nodejs-mongodb-azure-sample-app
cd msdocs-nodejs-mongodb-azure-sample-app
azd init --template msdocs-nodejs-mongodb-azure-sample-app
azd up
First, you set up a sample data-driven app as a starting point. For your convenience, the sample repository, includes a dev container configuration. The dev container has everything you need to develop an application, including the database, cache, and all environment variables needed by the sample application. The dev container can run in a GitHub codespace, which means you can run the sample on any computer with a web browser.
Step 1: In a new browser window:
Step 2: In the GitHub fork:
Step 3: In the codespace terminal:
npm install && npm start
.Your application running on port 3000 is available.
, select Open in Browser.
You should see the sample application in a new browser tab.
To stop the Express.js application, type Ctrl
+C
.Tip
You can ask GitHub Copilot about this repository. For example:
Having issues? Check the Troubleshooting section.
In this step, you create the Azure resources. The steps used in this tutorial create a set of secure-by-default resources that include App Service and Azure Cosmos DB for MongoDB. For the creation process, you'll specify:
https://<app-name>-<hash>.<region>.azurewebsites.net
.Sign in to the Azure portal and follow these steps to create your Azure App Service resources.
Step 1: In the Azure portal:
Step 2: In the Create Web App + Database page, fill out the form as follows.
Step 3: The deployment takes a few minutes to complete. Once deployment completes, select the Go to resource button. You're taken directly to the App Service app, but the following resources are created:
Having issues? Check the Troubleshooting section.
The creation wizard generated the connectivity string for you already as an app setting. However, the security best practice is to keep secrets out of App Service completely. You'll move your secrets to a key vault and change your app setting to a Key Vault reference with the help of Service Connectors.
Step 1: In the App Service page:
Step 2: Create a key vault for secure management of secrets.
Step 3:
Step 4:
Step 5: In the Create connection dialog for the Key Vault connection:
Step 6: You're back in the edit dialog for defaultConnector.
Step 7: To verify your changes:
@Microsoft.KeyVault(...)
, which means that it's a key vault reference because the secret is now managed in the key vault.Having issues? Check the Troubleshooting section.
In this step, you configure GitHub deployment using GitHub Actions. It's just one of many ways to deploy to App Service, but also a great way to have continuous integration in your deployment process. By default, every git push
to your GitHub repository kicks off the build and deploy action.
Step 1: In the left menu, select Deployment > Deployment Center.
Step 2: In the Deployment Center page:
.github/workflows
directory.
By default, the deployment center creates a user-assigned identity for the workflow to authenticate using Microsoft Entra (OIDC authentication). For alternative authentication options, see Deploy to App Service using GitHub Actions.Step 3: Back in the GitHub codespace of your sample fork, run git pull origin starter-no-infra
.
This pulls the newly committed workflow file into your codespace.
Step 4 (Option 1: with GitHub Copilot):
mongoose.connect
call.getApp
method.
GitHub Copilot doesn't give you the same response every time, you might need to ask more questions to fine-tune its response. For tips, see What can I do with GitHub Copilot in my codespace?.Step 4 (Option 2: without GitHub Copilot):
mongoose.connect
is called (Line 16) and change process.env.MONGODB_URI
to process.env.AZURE_COSMOS_CONNECTIONSTRING || process.env.MONGODB_URI
.Step 5:
Update environment variable
. Or, select Step 6: Back in the Deployment Center page in the Azure portal:
Step 7: You're taken to your GitHub repository and see that the GitHub action is running. The workflow file defines two separate stages, build and deploy. Wait for the GitHub run to show a status of Complete.
Having issues? Check the Troubleshooting section.
Step 1: In the App Service page:
https://<app-name>.azurewebsites.net
.Step 2: Add a few tasks to the list. Congratulations, you're running a secure data-driven Node.js app in Azure App Service.
Azure App Service captures all messages logged to the console to assist you in diagnosing issues with your application. The sample app outputs console log messages in each of its endpoints to demonstrate this capability. For example, the get
endpoint outputs a message about the number of tasks retrieved from the database and an error message appears if something goes wrong.
router.get('/', function(req, res, next) {
Task.find()
.then((tasks) => {
const currentTasks = tasks.filter(task => !task.completed);
const completedTasks = tasks.filter(task => task.completed === true);
console.log(`Total tasks: ${tasks.length} Current tasks: ${currentTasks.length} Completed tasks: ${completedTasks.length}`)
res.render('index', { currentTasks: currentTasks, completedTasks: completedTasks });
})
.catch((err) => {
console.log(err);
res.send('Sorry! Something went wrong.');
});
});
Step 1: In the App Service page:
Step 2: From the left menu, select Log stream. You see the logs for your app, including platform logs and logs from inside the container.
Azure App Service provides a web-based diagnostics console named Kudu that lets you examine the server hosting environment for your web app. Using Kudu, you can view the files deployed to Azure, review the deployment history of the application, and even open an SSH session into the hosting environment.
Step 1: In the App Service page:
https://<app-name>.scm.azurewebsites.net
.Step 2: In the Kudu page, select Deployments.
If you deploy code to App Service using Git or zip deploy, you see a history of deployments of your web app.
Step 3: Go back to the Kudu homepage and select Site wwwroot.
You can see the deployed folder structure and select to browse and view the files.
When you're finished, you can delete all of the resources from your Azure subscription by deleting the resource group.
Step 1: In the search bar at the top of the Azure portal:
Step 2: In the resource group page, select Delete resource group.
Step 3:
In this step, you create the Azure resources and deploy a sample app to App Service on Linux. The steps used in this tutorial create a set of secure-by-default resources that include App Service and Azure Cosmos DB.
The dev container already has the Azure Developer CLI (AZD).
From the repository root, run azd init
.
azd init --template nodejs-app-service-cosmos-redis-infra
When prompted, give the following answers:
Question | Answer |
---|---|
The current directory is not empty. Would you like to initialize a project here in '<your-directory>'? | Y |
What would you like to do with these files? | Keep my existing files unchanged |
Enter a new environment name | Type a unique name. The AZD template uses this name as part of the DNS name of your web app in Azure (<app-name>-<hash>.azurewebsites.net ). Alphanumeric characters and hyphens are allowed. |
Sign into Azure by running the azd auth login
command and following the prompt:
azd auth login
Create the necessary Azure resources and deploy the app code with the azd up
command. Follow the prompt to select the desired subscription and location for the Azure resources.
azd up
The azd up
command takes about 15 minutes to complete (the Redis cache takes the most time). It also compiles and deploys your application code, but you'll modify your code later to work with App Service. While it's running, the command provides messages about the provisioning and deployment process, including a link to the deployment in Azure. When it finishes, the command also displays a link to the deploy application.
This AZD template contains files (azure.yaml and the infra directory) that generate a secure-by-default architecture with the following Azure resources:
Once the command finishes creating resources and deploying the application code the first time, the deployed sample app doesn't work yet because you must make small changes to make it connect to the database in Azure.
The AZD template you use generated the connectivity variables for you already as app settings and outputs the them to the terminal for your convenience. App settings are one way to keep connection secrets out of your code repository.
In the AZD output, find the app setting AZURE_COSMOS_CONNECTIONSTRING
. Only the setting names are displayed. They look like this in the AZD output:
App Service app has the following app settings: - AZURE_COSMOS_CONNECTIONSTRING - AZURE_REDIS_CONNECTIONSTRING - AZURE_KEYVAULT_RESOURCEENDPOINT - AZURE_KEYVAULT_SCOPE
AZURE_COSMOS_CONNECTIONSTRING
contains the connection string to the Cosmos DB database in Azure. You need to use it in your code later.
For your convenience, the AZD template shows you the direct link to the app's app settings page. Find the link and open it in a new browser tab.
Having issues? Check the Troubleshooting section.
In the GitHub codespace, start a new chat session by clicking the Chat view, then clicking +.
Ask, "@workspace How does the app connect to the database?" Copilot might point you to the app.js file and the mongoose.connect
call.
Say, "I have a connection string variable in Azure called AZURE_COSMOS_CONNECTIONSTRING.". Copilot might give you a code suggestion similar to the one in the Option 2: without GitHub Copilot steps below and even tell you to make the change in app.js.
Open app.js in the explorer and add the code suggestion in the getApp
method.
GitHub Copilot doesn't give you the same response every time, you might need to ask more questions to fine-tune its response. For tips, see What can I do with GitHub Copilot in my codespace?.
Back in the codespace terminal, run azd deploy
.
azd deploy
Tip
You can also just use azd up
always, which does all of azd package
, azd provision
, and azd deploy
.
Having issues? Check the Troubleshooting section.
In the AZD output, find the URL of your app and navigate to it in the browser. The URL looks like this in the AZD output:
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: https://<app-name>-<hash>.azurewebsites.net/
Add a few tasks to the list.
Congratulations, you're running a web app in Azure App Service, with secure connectivity to Azure Cosmos DB.
Having issues? Check the Troubleshooting section.
Azure App Service captures all messages logged to the console to assist you in diagnosing issues with your application. The sample app outputs console log messages in each of its endpoints to demonstrate this capability. For example, the get
endpoint outputs a message about the number of tasks retrieved from the database and an error message appears if something goes wrong.
router.get('/', function(req, res, next) {
Task.find()
.then((tasks) => {
const currentTasks = tasks.filter(task => !task.completed);
const completedTasks = tasks.filter(task => task.completed === true);
console.log(`Total tasks: ${tasks.length} Current tasks: ${currentTasks.length} Completed tasks: ${completedTasks.length}`)
res.render('index', { currentTasks: currentTasks, completedTasks: completedTasks });
})
.catch((err) => {
console.log(err);
res.send('Sorry! Something went wrong.');
});
});
In the AZD output, find the link to stream App Service logs and navigate to it in the browser. The link looks like this in the AZD output:
Stream App Service logs at: https://portal.azure.com/#@/resource/subscriptions/<subscription-guid>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name>/logStream
Learn more about logging in Java apps in the series on Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications.
Having issues? Check the Troubleshooting section.
To delete all Azure resources in the current deployment environment, run azd down
and follow the prompts.
azd down
Depending on your subscription and the region you select, you might see the deployment status for Azure Cosmos DB to be Conflict
, with the following message in Operation details:
Sorry, we are currently experiencing high demand in <region> region, and cannot fulfill your request at this time.
The error is most likely caused by a limit on your subscription for the region you select. Try choosing a different region for your deployment.
You probably still need to make the connection string changes in your application code. See 4. Deploy sample code.
Pricing for the created resources is as follows:
mongosh
from the app's SSH terminal. The app's container doesn't come with mongosh
, so you must install it manually. Remember that the installed client doesn't persist across app restarts.Take the autogenerated workflow file from App Service as an example, each git push
kicks off a new build and deployment run. From a local clone of the GitHub repository, you make the desired updates push it to GitHub. For example:
git add .
git commit -m "<some-message>"
git push origin main
The autogenerated workflow file from App Service defines build-then-deploy, two-job run. Because each job runs in its own clean environment, the workflow file ensures that the deploy
job has access to the files from the build
job:
build
job, upload files as artifacts.deploy
job, download the artifacts.Most of the time taken by the two-job process is spent uploading and download artifacts. If you want, you can simplify the workflow file by combining the two jobs into one, which eliminates the need for the upload and download steps.
See Set up GitHub Actions deployment from the Deployment Center.
You might notice that the GitHub Copilot chat view was already there for you when you created the codespace. For your convenience, we include the GitHub Copilot chat extension in the container definition (see .devcontainer/devcontainer.json). However, you need a GitHub Copilot account (30-day free trial available).
A few tips for you when you talk to GitHub Copilot:
@workspace
. For more information, see Use the @workspace agent.@workspace
) even where to make the changes, but it's not allowed to make the changes for you. It's up to you to add the suggested changes and test it.Here are some other things you can say to fine-tune the answer you get:
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Guided project: Build and Deploy your own AI Copilot - Training
Build an AI copilot for Contoso Bike Shop. Integrate Azure OpenAI and Cosmos DB to enable advanced data searches, use GPT-3.5 for enhanced results, and deploy the solution on Azure Kubernetes Service.
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.