1# App Service Bicep Patterns
2 
3## Linux vs Windows
4 
5> ⚠️ **Warning:** `linuxFxVersion` and `reserved: true` are **Linux-only** properties. Setting `linuxFxVersion` on a Windows App Service Plan causes a deployment error: `LinuxFxVersion cannot be set for non-Linux App Service plans`. Omit both for Windows plans.
6 
7| Property | Linux | Windows |
8|----------|-------|---------|
9| Plan `reserved` | `true` | omit (defaults to `false`) |
10| Site `kind` | `'app,linux'` | `'app'` |
11| Site `linuxFxVersion` | e.g. `'NODE\|20-lts'` | omit |
12| Site `WEBSITE_NODE_DEFAULT_VERSION` | omit | e.g. `'~20'` |
13 
14> 💡 **Tip:** When both frontend and API use Node.js, prefer a **single Linux App Service Plan** for both. This avoids mixed-platform complexity and keeps all services on one plan.
15 
16## Linux App Service (Recommended for Node.js)
17 
18> ⚠️ **REQUIRED: `azd-service-name` tag** — The `tags` property MUST include `union(tags, { 'azd-service-name': serviceName })` so that `azd deploy` can locate the resource. Without this tag, `azd deploy` fails with `resource not found: unable to find a resource tagged with 'azd-service-name: web'`.
19 
20```bicep
21resource appServicePlan 'Microsoft.Web/serverfarms@2022-09-01' = {
22  name: '${resourcePrefix}-plan-${uniqueHash}'
23  location: location
24  kind: 'linux'
25  sku: {
26    name: 'B1'
27    tier: 'Basic'
28  }
29  properties: {
30    reserved: true  // Required for Linux
31  }
32}
33 
34resource webApp 'Microsoft.Web/sites@2022-09-01' = {
35  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
36  location: location
37  kind: 'app,linux'
38  tags: union(tags, { 'azd-service-name': serviceName })  // REQUIRED for azd deploy
39  properties: {
40    serverFarmId: appServicePlan.id
41    siteConfig: {
42      linuxFxVersion: 'NODE|20-lts'
43      alwaysOn: true
44      healthCheckPath: '/health'
45      appSettings: [
46        {
47          name: 'SCM_DO_BUILD_DURING_DEPLOYMENT'
48          value: 'true'  // Required for source-based Node.js deploys (azd deploy)
49        }
50        {
51          name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
52          value: applicationInsights.properties.ConnectionString
53        }
54        {
55          name: 'ApplicationInsightsAgent_EXTENSION_VERSION'
56          value: '~3'
57        }
58      ]
59    }
60    httpsOnly: true
61  }
62  identity: {
63    type: 'SystemAssigned'
64  }
65}
66```
67 
68## Windows App Service
69 
70Use when the runtime requires Windows (e.g. .NET Framework) or when explicitly requested.
71 
72```bicep
73resource appServicePlan 'Microsoft.Web/serverfarms@2022-09-01' = {
74  name: '${resourcePrefix}-plan-${uniqueHash}'
75  location: location
76  sku: {
77    name: 'B1'
78    tier: 'Basic'
79  }
80  // Do NOT set reserved: true for Windows
81}
82 
83resource webApp 'Microsoft.Web/sites@2022-09-01' = {
84  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
85  location: location
86  kind: 'app'
87  tags: union(tags, { 'azd-service-name': serviceName })  // REQUIRED for azd deploy
88  properties: {
89    serverFarmId: appServicePlan.id
90    siteConfig: {
91      // Do NOT set linuxFxVersion for Windows plans
92      alwaysOn: true
93      healthCheckPath: '/health'
94      appSettings: [
95        {
96          name: 'SCM_DO_BUILD_DURING_DEPLOYMENT'
97          value: 'true'  // Required for source-based Node.js deploys (azd deploy)
98        }
99        {
100          name: 'WEBSITE_NODE_DEFAULT_VERSION'
101          value: '~20'
102        }
103        {
104          name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
105          value: applicationInsights.properties.ConnectionString
106        }
107        {
108          name: 'ApplicationInsightsAgent_EXTENSION_VERSION'
109          value: '~3'
110        }
111      ]
112    }
113    httpsOnly: true
114  }
115  identity: {
116    type: 'SystemAssigned'
117  }
118}
119```
120 
121## Node.js Build Configuration
122 
123> ⚠️ **Warning:** For source-based Node.js deployments to App Service (e.g. `azd deploy`), you **must** set `SCM_DO_BUILD_DURING_DEPLOYMENT=true` so App Service runs `npm install` during deployment. Without this, the app fails at runtime with `Cannot find module` errors.
124 
125This setting is already included in both the Linux and Windows examples above.
126 
127## Key Vault Integration
128 
129Reference secrets from Key Vault:
130 
131```bicep
132appSettings: [
133  {
134    name: 'DATABASE_URL'
135    value: '@Microsoft.KeyVault(VaultName=${keyVault.name};SecretName=database-url)'
136  }
137]
138```
139