1# Node.js/Express Production Configuration for Azure
2 
3Configure Express/Node.js applications for production deployment on Azure Container Apps and App Service.
4 
5## Required Production Settings
6 
7### 1. Trust Proxy (CRITICAL)
8 
9Azure load balancers and reverse proxies sit in front of your app. Without trust proxy, you'll get wrong client IPs, HTTPS detection failures, and cookie issues.
10 
11```javascript
12const app = express();
13 
14// REQUIRED for Azure - trust the Azure load balancer
15app.set('trust proxy', 1);  // Trust first proxy
16 
17// Or trust all proxies (less secure but simpler)
18app.set('trust proxy', true);
19```
20 
21### 2. Cookie Configuration
22 
23Azure's infrastructure requires specific cookie settings:
24 
25```javascript
26app.use(session({
27  secret: process.env.SESSION_SECRET,
28  resave: false,
29  saveUninitialized: false,
30  cookie: {
31    secure: process.env.NODE_ENV === 'production',  // HTTPS only in prod
32    sameSite: 'lax',  // Required for Azure
33    httpOnly: true,
34    maxAge: 24 * 60 * 60 * 1000  // 24 hours
35  }
36}));
37```
38 
39**Key settings:**
40- `sameSite: 'lax'` — Required for cookies through Azure's proxy
41- `secure: true` — Only in production (HTTPS)
42- `httpOnly: true` — Prevent XSS attacks
43 
44### 3. Health Check Endpoint
45 
46Azure Container Apps and App Service check your app's health:
47 
48```javascript
49app.get('/health', (req, res) => {
50  res.status(200).json({ status: 'healthy', timestamp: new Date().toISOString() });
51});
52```
53 
54**Configure in Container Apps:**
55```bash
56az containerapp update \
57  --name APP \
58  --resource-group RG \
59  --health-probe-path /health \
60  --health-probe-interval 30
61```
62 
63### 4. Port Configuration
64 
65Azure sets the port via environment variable:
66 
67```javascript
68const port = process.env.PORT || process.env.WEBSITES_PORT || 3000;
69app.listen(port, '0.0.0.0', () => {
70  console.log(`Server running on port ${port}`);
71});
72```
73 
74**Important:** Bind to `0.0.0.0`, not `localhost` or `127.0.0.1`.
75 
76### 5. Environment Detection
77 
78```javascript
79const isProduction = process.env.NODE_ENV === 'production';
80const isAzure = process.env.WEBSITE_SITE_NAME || process.env.CONTAINER_APP_NAME;
81 
82if (isProduction || isAzure) {
83  app.set('trust proxy', 1);
84}
85```
86 
87---
88 
89## Complete Production Configuration
90 
91```javascript
92// app.js - Production-ready Express configuration for Azure
93const express = require('express');
94const session = require('express-session');
95 
96const app = express();
97const isProduction = process.env.NODE_ENV === 'production';
98 
99// Trust Azure load balancer
100if (isProduction) {
101  app.set('trust proxy', 1);
102}
103 
104// Security headers
105app.use((req, res, next) => {
106  res.setHeader('X-Content-Type-Options', 'nosniff');
107  res.setHeader('X-Frame-Options', 'DENY');
108  next();
109});
110 
111// JSON parsing
112app.use(express.json());
113app.use(express.urlencoded({ extended: true }));
114 
115// Session (if using)
116app.use(session({
117  secret: process.env.SESSION_SECRET || 'dev-secret-change-in-prod',
118  resave: false,
119  saveUninitialized: false,
120  cookie: {
121    secure: isProduction,
122    sameSite: 'lax',
123    httpOnly: true,
124    maxAge: 24 * 60 * 60 * 1000
125  }
126}));
127 
128// Health check
129app.get('/health', (req, res) => {
130  res.status(200).json({ status: 'ok' });
131});
132 
133// Your routes here
134app.get('/', (req, res) => {
135  res.json({ message: 'Hello from Azure!' });
136});
137 
138// Error handler
139app.use((err, req, res, next) => {
140  console.error(err.stack);
141  res.status(500).json({ error: isProduction ? 'Internal error' : err.message });
142});
143 
144// Start server
145const port = process.env.PORT || 3000;
146app.listen(port, '0.0.0.0', () => {
147  console.log(`Server running on port ${port}`);
148});
149```
150 
151---
152 
153## Dockerfile for Azure
154 
155```dockerfile
156FROM node:20-alpine
157 
158WORKDIR /app
159 
160# Install dependencies first (better caching)
161COPY package*.json ./
162RUN npm ci --only=production
163 
164# Copy app
165COPY . .
166 
167# Set production environment
168ENV NODE_ENV=production
169 
170# Expose port (Azure uses PORT env var)
171EXPOSE 3000
172 
173# Health check
174HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
175  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
176 
177# Start app
178CMD ["node", "app.js"]
179```
180 
181---
182 
183## Common Issues
184 
185### Cookies Not Setting
186 
187**Symptom:** Session lost between requests
188 
189**Fix:**
1901. Add `app.set('trust proxy', 1)`
1912. Set `sameSite: 'lax'` in cookie config
1923. Set `secure: true` only if using HTTPS
193 
194### Wrong Client IP
195 
196**Symptom:** `req.ip` returns Azure internal IP
197 
198**Fix:** `app.set('trust proxy', 1);`
199 
200### HTTPS Redirect Loop
201 
202**Symptom:** Infinite redirects when forcing HTTPS
203 
204**Fix:**
205```javascript
206const TRUSTED_HOST = process.env.APP_PUBLIC_HOSTNAME;
207 
208app.use((req, res, next) => {
209  if (req.get('x-forwarded-proto') !== 'https' && process.env.NODE_ENV === 'production') {
210    if (!TRUSTED_HOST) return next();
211    return res.redirect(`https://${TRUSTED_HOST}${req.originalUrl}`);
212  }
213  next();
214});
215```
216 
217### Health Check Failing
218 
219**Symptom:** Container restarts repeatedly
220 
221**Fix:**
2221. Ensure `/health` endpoint returns 200
2232. Check app starts within startup probe timeout
2243. Verify port matches container configuration
225 
226---
227 
228## Environment Variables
229 
230> ⚠️ **Important distinction**: `azd env set` vs Application Environment Variables
231>
232> **`azd env set`** sets variables for the **azd provisioning process**, NOT application runtime. These are used by azd and Bicep during deployment.
233>
234> **Application environment variables** must be configured via:
235> 1. **Bicep templates** — Define in the resource's `env` property
236> 2. **Azure CLI** — Use `az containerapp update --set-env-vars`
237> 3. **azure.yaml** — Use the `env` section in service configuration
238 
239**Azure CLI:**
240```bash
241az containerapp update \
242  --name APP \
243  --resource-group RG \
244  --set-env-vars \
245    NODE_ENV=production \
246    SESSION_SECRET=your-secret-here \
247    PORT=3000
248```
249 
250**azure.yaml:**
251```yaml
252services:
253  api:
254    host: containerapp
255    env:
256      NODE_ENV: production
257      PORT: "3000"
258```
259 
260**Bicep:**
261```bicep
262env: [
263  { name: 'NODE_ENV', value: 'production' }
264  { name: 'SESSION_SECRET', secretRef: 'session-secret' }
265]
266```
267