| page_type | sample | |||||||
|---|---|---|---|---|---|---|---|---|
| languages |
|
|||||||
| products |
|
|||||||
| urlFragment | todo-java-mongo-aca | |||||||
| name | Containerized React Web App with Java API and MongoDB on Azure | |||||||
| description | A complete ToDo app on Azure Container Apps with Java API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor |
A blueprint for getting a React web app with a Java API and a MongoDB database running on Azure. The blueprint includes sample application code (a ToDo web app) which can be removed and replaced with your own application code. Add your own source code and leverage the Infrastructure as Code assets (written in Bicep) to get up and running quickly. This architecture is for running containerized apps or microservices on a serverless platform.
Let's jump in and get this up and running in Azure. When you are finished, you will have a fully functional web app deployed to the cloud. In later steps, you'll see how to setup a pipeline and monitor the application.
Screenshot of the deployed ToDo app
This template will create infrastructure and deploy code to Azure. If you don't have an Azure Subscription, you can sign up for a free account here. Make sure you have contributor role to the Azure subscription.
The following prerequisites are required to use this application. Please ensure that you have them all installed locally.
- Azure Developer CLI - for Azure deployment
- Java 17 or later - for API backend
- Node.js with npm (16.13.1+) - for the Web frontend
- Docker - for local development and Azure deployment
You can run this application locally using Docker without any Azure dependencies. This is perfect for quick demos, development, or offline work.
-
Clone the repository
git clone https://github.com/Azure-Samples/todo-java-mongo-aca.git cd todo-java-mongo-aca -
Start the application
docker-compose up --build
This will:
- Start a local MongoDB instance
- Build and start the Java API (available at http://localhost:3100)
- No Azure Key Vault or credentials required!
-
Verify the API is running
# Check API health curl http://localhost:3100/lists # Or open Swagger UI in your browser open http://localhost:3100
-
Stop the application
docker-compose down
The application supports the following environment variables (see .env.example for a complete list):
| Variable | Description | Default (Local) |
|---|---|---|
MONGODB_URI |
MongoDB connection string | mongodb://localhost:27017 |
MONGODB_DATABASE |
Database name | todo |
AZURE_KEY_VAULT_ENABLED |
Enable/disable Key Vault integration | false |
To customize these values:
- Copy
.env.exampleto.env - Edit the values in
.env - Docker Compose will automatically use them
If you already have MongoDB running elsewhere:
# Build the Docker image
cd src/api
docker build -t todo-api .
# Run the container
docker run -p 3100:3100 \
-e MONGODB_URI=mongodb://your-mongodb-host:27017 \
-e MONGODB_DATABASE=todo \
-e AZURE_KEY_VAULT_ENABLED=false \
todo-apiMongoDB Connection Issues
- Ensure MongoDB is running:
docker-compose ps - Check MongoDB logs:
docker-compose logs mongodb - Verify port 27017 is not in use by another service
API Won't Start
- Check API logs:
docker-compose logs api - Ensure port 3100 is available
- Verify Java 17+ is being used in the Docker image
Key Vault Errors (even though disabled)
- Make sure
AZURE_KEY_VAULT_ENABLED=falseis set - Check that
AZURE_KEY_VAULT_ENDPOINTis empty or not set
To learn how to get started with any template, follow the steps in this quickstart with this template(Azure-Samples/todo-java-mongo-aca).
This quickstart will show you how to authenticate on Azure, initialize using a template, provision infrastructure and deploy code on Azure via the following commands:
# Log in to azd. Only required once per-install.
azd auth login
# First-time project setup. Initialize a project in the current directory, using this template.
azd init --template Azure-Samples/todo-java-mongo-aca
# Provision and deploy to Azure
azd upNOTE: This template may only be used with the following Azure locations:
- Australia East
- Brazil South
- Canada Central
- Central US
- East Asia
- East US
- East US 2
- Germany West Central
- Japan East
- Korea Central
- North Central US
- North Europe
- South Central US
- UK South
- West Europe
- West US
If you attempt to use the template with an unsupported region, the provision step will fail.
This application utilizes the following Azure resources:
- Azure Container Apps to host the Web frontend and API backend
- Azure Cosmos DB API for MongoDB for storage
- Azure Monitor for monitoring and logging
- Azure Key Vault for securing secrets
Here's a high level architecture diagram that illustrates these components. Notice that these are all contained within a single resource group, that will be created for you when you create the resources.
This template provisions resources to an Azure subscription that you will select upon provisioning them. Please refer to the Pricing calculator for Microsoft Azure and, if needed, update the included Azure resource definitions found in
infra/main.bicepto suit your needs.
This template is structured to follow the Azure Developer CLI. You can learn more about azd architecture in the official documentation.
At this point, you have a complete application deployed on Azure. But there is much more that the Azure Developer CLI can do. These next steps will introduce you to additional commands that will make creating applications on Azure much easier. Using the Azure Developer CLI, you can setup your pipelines, monitor your application, test and debug locally.
-
azd pipeline config- to configure a CI/CD pipeline (using GitHub Actions or Azure Dev 9633 Ops) to deploy your application whenever code is pushed to the main branch. -
azd monitor- to monitor the application and quickly navigate to the various Application Insights dashboards (e.g. overview, live metrics, logs) -
Run and Debug Locally - using Visual Studio Code and the Azure Developer CLI extension
-
azd down- to delete all the Azure resources created with this template -
Enable optional features, like APIM - for enhanced backend API protection and observability
The Azure Developer CLI includes many other commands to help with your Azure development experience. You can view these commands at the terminal by running azd help. You can also view the full list of commands on our Azure Developer CLI command page.
This template creates a managed identity for your app inside your Azure Active Directory tenant, and it is used to authenticate your app with Azure and other services that support Azure AD authentication like Key Vault via access policies. You will see principalId referenced in the infrastructure as code files, that refers to the id of the currently logged in Azure Developer CLI user, which will be granted access policies and permissions to run the application locally. To view your managed identity in the Azure Portal, follow these steps.
This template uses Azure Key Vault to securely store your Cosmos DB connection string for the provisioned Cosmos DB account when deployed to Azure. Key Vault is a cloud service for securely storing and accessing secrets (API keys, passwords, certificates, cryptographic keys) and makes it simple to give other Azure services access to them. As you continue developing your solution, you may add as many secrets to your Key Vault as you require.
Note for Local Development: Key Vault is optional when running locally with Docker. The application automatically falls back to using environment variables (see the "Running Locally" section above) when AZURE_KEY_VAULT_ENABLED is set to false or not set.
If you have any feature requests, issues, or areas for improvement, please file an issue. To keep up-to-date, ask questions, or share suggestions, join our GitHub Discussions. You may also contact us via AzDevTeam@microsoft.com.