initial commit

Author: erikschlegel

README.md

@@ -1,33 +1,110 @@
-# Project
+This repository includes a simple Python Flask API with a single route that returns JSON.
+You can use this project as a starting point for your own APIs.
 
-> This repo has been populated by an initial template to help get you started. Please
-> make sure to update the content to build a great experience for community-building.
+The repository is designed for use with [Docker containers](https://www.docker.com/), both for local development and deployment, and includes infrastructure files for deployment to [Azure Container Apps](https://learn.microsoft.com/azure/container-apps/overview). 🐳
 
-As the maintainer of this project, please make a few updates:
+The code is organized using [Flask Blueprints](https://flask.palletsprojects.com/en/2.2.x/blueprints/),
+tested with [pytest](https://docs.pytest.org/en/7.2.x/),
+linted with [ruff](https://github.com/charliermarsh/ruff), and formatted with [black](https://black.readthedocs.io/en/stable/).
+Code quality issues are all checked with both [pre-commit](https://pre-commit.com/) and Github actions.
 
-- Improving this README.MD file to provide a great experience
-- Updating SUPPORT.MD with content about this project's support experience
-- Understanding the security reporting process in SECURITY.MD
-- Remove this section from the README
+## Opening the project
 
-## Contributing
+This project has [Dev Container support](https://code.visualstudio.com/docs/devcontainers/containers), so it will be be setup automatically if you open it in Github Codespaces or in local VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+If you're not using one of those options for opening the project, then you'll need to:
 
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+1. Create a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) and activate it.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+2. Install the requirements:
 
-## Trademarks
+    ```shell
+    python3 -m pip install -r src/requirements-dev.txt
+    ```
 
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
-trademarks or logos is subject to and must follow 
-[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
-Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
-Any use of third-party trademarks or logos are subject to those third-party's policies.
+3. Install the pre-commit hooks:
+
+    ```shell
+    pre-commit install
+    ```
+
+## Local development
+
+1. Run the local server:
+
+    ```shell
+    python3 -m flask --debug --app src/app:app run --port 5000
+    ```
+
+3. Click 'http://127.0.0.1:5000' in the terminal, which should open a new tab in the browser.
+
+4. Try the API at '/generate_name' and try passing in a parameter at the end of the URL, like '/generate_name?start_with=N'.
+
+### Local development with Docker
+
+You can also run this app with Docker, thanks to the `Dockerfile`.
+You need to either have Docker Desktop installed or have this open in Github Codespaces for these commands to work.
+
+1. Build the image:
+
+    ```
+    docker build --tag flask-app src/
+    ```
+
+2. Run the image:
+
+    ```
+    docker run --publish 5000:5000 flask-app
+    ```
+
+### Deployment
+
+This repo is set up for deployment on Azure Container Apps using the configuration files in the `infra` folder.
+
+This diagram shows the architecture of the deployment:
+
+![Diagram of app architecture: Azure Container Apps environment, Azure Container App, Azure Container Registry, Container, and Key Vault](readme_diagram.png)
+
+Steps for deployment:
+
+1. Sign up for a [free Azure account](https://azure.microsoft.com/free/) and create an Azure Subscription.
+2. Install the [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd). (If you open this repository in Codespaces or with the VS Code Dev Containers extension, that part will be done for you.)
+3. Login to Azure:
+
+    ```shell
+    azd auth login
+    ```
+
+4. Provision and deploy all the resources:
+
+    ```shell
+    azd up
+    ```
+    It will prompt you to provide an `azd` environment name (like "flask-app"), select a subscription from your Azure account, and select a location (like "eastus"). Then it will provision the resources in your account and deploy the latest code. If you get an error with deployment, changing the location can help, as there may be availability constraints for some of the resources.
+
+5. When `azd` has finished deploying, you'll see an endpoint URI in the command output. Visit that URI, and you should see the API output! 🎉
+6. When you've made any changes to the app code, you can just run:
+
+    ```shell
+    azd deploy
+    ```
+
+### Costs
+
+Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.
+The majority of the Azure resources used in this infrastructure are on usage-based pricing tiers.
+However, Azure Container Registry has a fixed cost per registry per day.
+
+You can try the [Azure pricing calculator](https://azure.com/e/9f8185b239d240b398e201078d0c4e7a) for the resources:
+
+- Azure Container App: Consumption tier with 0.5 CPU, 1GiB memory/storage. Pricing is based on resource allocation, and each month allows for a certain amount of free usage. [Pricing](https://azure.microsoft.com/pricing/details/container-apps/)
+- Azure Container Registry: Basic tier. [Pricing](https://azure.microsoft.com/pricing/details/container-registry/)
+- Log analytics: Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
+
+⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use,
+either by deleting the resource group in the Portal or running `azd down`.
+
+
+## Getting help
+
+If you're working with this project and running into issues, please post in **Discussions**.

azure.yaml

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
+
+name: simple-flask-container-app
+metadata:
+  template: [email protected]
+services:
+  api:
+    project: ./src
+    language: py
+    host: containerapp

infra/api.bicep

@@ -0,0 +1,33 @@
+param name string
+param location string = resourceGroup().location
+param tags object = {}
+
+param identityName string
+param containerAppsEnvironmentName string
+param containerRegistryName string
+param serviceName string = 'api'
+param exists bool
+
+resource apiIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
+  name: identityName
+  location: location
+}
+
+module app 'core/host/container-app-upsert.bicep' = {
+  name: '${serviceName}-container-app-module'
+  params: {
+    name: name
+    location: location
+    tags: union(tags, { 'azd-service-name': serviceName })
+    identityName: apiIdentity.name
+    exists: exists
+    containerAppsEnvironmentName: containerAppsEnvironmentName
+    containerRegistryName: containerRegistryName
+    targetPort: 5000
+  }
+}
+
+output SERVICE_API_IDENTITY_PRINCIPAL_ID string = apiIdentity.properties.principalId
+output SERVICE_API_NAME string = app.outputs.name
+output SERVICE_API_URI string = app.outputs.uri
+output SERVICE_API_IMAGE_NAME string = app.outputs.imageName

infra/core/ai/cognitiveservices.bicep

@@ -0,0 +1,38 @@
+param name string
+param location string = resourceGroup().location
+param tags object = {}
+@description('The custom subdomain name used to access the API. Defaults to the value of the name parameter.')
+param customSubDomainName string = name
+param deployments array = []
+param kind string = 'OpenAI'
+param publicNetworkAccess string = 'Enabled'
+param sku object = {
+  name: 'S0'
+}
+
+resource account 'Microsoft.CognitiveServices/accounts@2022-10-01' = {
+  name: name
+  location: location
+  tags: tags
+  kind: kind
+  properties: {
+    customSubDomainName: customSubDomainName
+    publicNetworkAccess: publicNetworkAccess
+  }
+  sku: sku
+}
+
+@batchSize(1)
+resource deployment 'Microsoft.CognitiveServices/accounts/deployments@2022-10-01' = [for deployment in deployments: {
+  parent: account
+  name: deployment.name
+  properties: {
+    model: deployment.model
+    raiPolicyName: contains(deployment, 'raiPolicyName') ? deployment.raiPolicyName : null
+    scaleSettings: deployment.scaleSettings
+  }
+}]
+
+output endpoint string = account.properties.endpoint
+output id string = account.id
+output name string = account.name

infra/core/database/cosmos/cosmos-account.bicep

@@ -0,0 +1,48 @@
+param name string
+param location string = resourceGroup().location
+param tags object = {}
+
+param connectionStringKey string = 'AZURE-COSMOS-CONNECTION-STRING'
+param keyVaultName string
+
+@allowed([ 'GlobalDocumentDB', 'MongoDB', 'Parse' ])
+param kind string
+
+resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
+  name: name
+  kind: kind
+  location: location
+  tags: tags
+  properties: {
+    consistencyPolicy: { defaultConsistencyLevel: 'Session' }
+    locations: [
+      {
+        locationName: location
+        failoverPriority: 0
+        isZoneRedundant: false
+      }
+    ]
+    databaseAccountOfferType: 'Standard'
+    enableAutomaticFailover: false
+    enableMultipleWriteLocations: false
+    apiProperties: (kind == 'MongoDB') ? { serverVersion: '4.0' } : {}
+    capabilities: [ { name: 'EnableServerless' } ]
+  }
+}
+
+resource cosmosConnectionString 'Microsoft.KeyVault/vaults/secrets@2022-07-01' = {
+  parent: keyVault
+  name: connectionStringKey
+  properties: {
+    value: cosmos.listConnectionStrings().connectionStrings[0].connectionString
+  }
+}
+
+resource keyVault 'Microsoft.KeyVault/vaults@2022-07-01' existing = {
+  name: keyVaultName
+}
+
+output connectionStringKey string = connectionStringKey
+output endpoint string = cosmos.properties.documentEndpoint
+output id string = cosmos.id
+output name string = cosmos.name

infra/core/database/cosmos/mongo/cosmos-mongo-account.bicep

@@ -0,0 +1,22 @@
+param name string
+param location string = resourceGroup().location
+param tags object = {}
+
+param keyVaultName string
+param connectionStringKey string = 'AZURE-COSMOS-CONNECTION-STRING'
+
+module cosmos '../../cosmos/cosmos-account.bicep' = {
+  name: 'cosmos-account'
+  params: {
+    name: name
+    location: location
+    connectionStringKey: connectionStringKey
+    keyVaultName: keyVaultName
+    kind: 'MongoDB'
+    tags: tags
+  }
+}
+
+output connectionStringKey string = cosmos.outputs.connectionStringKey
+output endpoint string = cosmos.outputs.endpoint
+output id string = cosmos.outputs.id

infra/core/database/cosmos/mongo/cosmos-mongo-db.bicep

@@ -0,0 +1,46 @@
+param accountName string
+param databaseName string
+param location string = resourceGroup().location
+param tags object = {}
+
+param collections array = []
+param connectionStringKey string = 'AZURE-COSMOS-CONNECTION-STRING'
+param keyVaultName string
+
+module cosmos 'cosmos-mongo-account.bicep' = {
+  name: 'cosmos-mongo-account'
+  params: {
+    name: accountName
+    location: location
+    keyVaultName: keyVaultName
+    tags: tags
+    connectionStringKey: connectionStringKey
+  }
+}
+
+resource database 'Microsoft.DocumentDB/databaseAccounts/mongodbDatabases@2022-08-15' = {
+  name: '${accountName}/${databaseName}'
+  tags: tags
+  properties: {
+    resource: { id: databaseName }
+  }
+
+  resource list 'collections' = [for collection in collections: {
+    name: collection.name
+    properties: {
+      resource: {
+        id: collection.id
+        shardKey: { _id: collection.shardKey }
+        indexes: [ { key: { keys: [ collection.indexKey ] } } ]
+      }
+    }
+  }]
+
+  dependsOn: [
+    cosmos
+  ]
+}
+
+output connectionStringKey string = connectionStringKey
+output databaseName string = databaseName
+output endpoint string = cosmos.outputs.endpoint

infra/core/database/cosmos/sql/cosmos-sql-account.bicep

@@ -0,0 +1,21 @@
+param name string
+param location string = resourceGroup().location
+param tags object = {}
+
+param keyVaultName string
+
+module cosmos '../../cosmos/cosmos-account.bicep' = {
+  name: 'cosmos-account'
+  params: {
+    name: name
+    location: location
+    tags: tags
+    keyVaultName: keyVaultName
+    kind: 'GlobalDocumentDB'
+  }
+}
+
+output connectionStringKey string = cosmos.outputs.connectionStringKey
+output endpoint string = cosmos.outputs.endpoint
+output id string = cosmos.outputs.id
+output name string = cosmos.outputs.name