01. Local Run¶

Time estimate: 10 minutes

Run the application locally with App Service-safe defaults before deploying to Azure.

flowchart TD
    INET[Internet] -->|HTTPS| WA["Web App\nApp Service S1\nLinux Node 20 LTS"]

    subgraph VNET["VNet 10.0.0.0/16"]
        subgraph INT_SUB["Integration Subnet 10.0.1.0/24\nDelegation: Microsoft.Web/serverFarms"]
            WA
        end
        subgraph PE_SUB["Private Endpoint Subnet 10.0.2.0/24"]
            PE_KV[PE: Key Vault]
            PE_SQL[PE: Azure SQL]
            PE_ST[PE: Storage]
        end
    end

    PE_KV --> KV[Key Vault]
    PE_SQL --> SQL[Azure SQL]
    PE_ST --> ST[Storage Account]

    subgraph DNS[Private DNS Zones]
        DNS_KV[privatelink.vaultcore.azure.net]
        DNS_SQL[privatelink.database.windows.net]
        DNS_ST[privatelink.blob.core.windows.net]
    end

    PE_KV -.-> DNS_KV
    PE_SQL -.-> DNS_SQL
    PE_ST -.-> DNS_ST

    WA -.->|System-Assigned MI| ENTRA[Microsoft Entra ID]
    WA --> AI[Application Insights]

    style WA fill:#0078d4,color:#fff
    style VNET fill:#E8F5E9,stroke:#4CAF50
    style DNS fill:#E3F2FD

Overview¶

flowchart TD
    A[Clone Repo] --> B[npm install]
    B --> C[npm start]
    C --> D[localhost:3000]
    D --> E{Test Endpoints}
    E --> F[/health]
    E --> G[/info]
    E --> H[/api/*]

Prerequisites¶

• Node.js v20+ (LTS recommended)
• npm or yarn
• Basic terminal familiarity

What you'll learn¶

• How to run an Express app locally
• Why the PORT environment variable is critical for Azure
• How to test production-like behavior on your machine

Quick Start¶

cd apps/nodejs
npm install
npm start

Visit http://localhost:3000

App Service-Safe Defaults¶

This application follows App Service conventions out of the box:

1. Port Binding¶

CRITICAL: The app binds to process.env.PORT, which App Service sets automatically. While many apps default to 3000 locally, Azure App Service uses a random port and routes traffic to it via a reverse proxy (IIS/Nginx).

// apps/nodejs/src/server.js
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

For more details on how the runtime handles your code, see Node.js Runtime Concepts.

2. Environment Variables¶

Default configuration works without any environment variables:

3. Production Mode Testing¶

Test production mode locally:

NODE_ENV=production npm start

This enables: - JSON log format (instead of colored dev logs) - Production error messages (no stack traces in responses)

Verify Local Setup¶

Health Check¶

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2026-04-01T13:59:14.151Z"
}

App Info¶

curl http://localhost:3000/info

Expected response:

{
  "name": "azure-app-service-practical-guide",
  "version": "1.0.0",
  "node": "v20.20.0",
  "environment": "development",
  "telemetryMode": "basic"
}

Generate Sample Logs¶

curl "http://localhost:3000/api/requests/log-levels?userId=local-user"

Example output:

{"timestamp":"2026-05-01T08:30:53.856Z","level":"info","message":"Info level log - normal operational message","service":"azure-appservice-reference","environment":"development","userId":"local-user","action":"log-levels-demo"}
{"timestamp":"2026-05-01T08:30:53.857Z","level":"warn","message":"Warn level log - potential issue detected","service":"azure-appservice-reference","environment":"development","userId":"local-user","warning":"Demo warning: userId parameter not provided","recommendation":"Include userId query parameter for tracking"}
{"timestamp":"2026-05-01T08:30:53.857Z","level":"error","message":"Error level log - application error","service":"azure-appservice-reference","environment":"development","userId":"local-user","error":"Demo error: simulating error condition","errorCode":"DEMO_ERROR","severity":"high"}

Check terminal output for structured logs at all severity levels.

Troubleshooting¶

Port Already in Use¶

# Find and kill process using port 3000
lsof -i :3000
kill -9 <PID>

Module Not Found¶

cd apps/nodejs
rm -rf node_modules package-lock.json
npm install

Next Steps¶

Once local development works, proceed to: - 02. First Deploy - Deploy Azure resources

Advanced Options¶

• Contribute

Run It in the Portal¶

Portal view: App Service plan (Linux) - the deployment target this tutorial emulates locally¶

Your local Express setup in this tutorial is meant to mirror the runtime shape of a Linux App Service app, not every plan-level limit shown on this blade. The visible Operating system: Linux confirms the worker OS, and the hosted-app list on the right shows that an App Service plan is the shared deployment target used by later tutorials. The CPU Percentage and Memory Percentage charts are the Portal-side signals you compare against when local npm start tests suggest the app is using too much CPU or memory under load. Use this blade to verify that the target app runs on a Linux App Service plan before moving from local validation to Azure deployment.

See Also¶

• 02. First Deploy
• Node.js Runtime Concepts

Sources¶

• Configure Node.js app on Azure App Service (Microsoft Learn)
• App Service local development setup (Microsoft Learn)