1# Code Migration Phase
2 
3Migrate source platform web application code to Azure App Service.
4 
5## Prerequisites
6 
7- Assessment report completed
8- Best practices loaded via `mcp_azure_mcp_get_azure_bestpractices` tool
9 
10## Rules
11 
12- Create all output in `<source-folder>-azure/` — never modify the source directory
13- Use latest GA runtime stack for the target language
14- Prefer managed identity over connection strings or API keys
15- Use App Configuration for shared settings, Key Vault for secrets
16- Always configure health check endpoint
17 
18## Steps
19 
201. **Load Best Practices** — Use `mcp_azure_mcp_get_azure_bestpractices` tool for App Service guidance
212. **Create Project Structure** — Set up the project inside the output directory
223. **Migrate Application Code** — Adapt source code for App Service runtime
234. **Update Dependencies** — Replace platform-specific SDKs with Azure equivalents
245. **Configure Startup** — Set startup command or create Dockerfile
256. **Migrate Environment Variables** — Map to App Settings / App Configuration / Key Vault
267. **Configure Database Connections** — Switch to Azure database services with managed identity
278. **Add Health Check** — Implement `/healthz` endpoint for App Service health monitoring
289. **Set Up Logging** — Integrate Application Insights SDK
29 
30## Key Configuration Files
31 
32### Startup Command
33 
34For non-Docker deployments, configure the startup command in App Service:
35 
36| Runtime | Default Start | Custom Start |
37|---------|--------------|--------------|
38| Node.js | `npm start` | Set in Configuration → General Settings |
39| Python | `gunicorn app:app` | `gunicorn --bind=0.0.0.0 --timeout 600 app:app` |
40| Java | Auto-detected | `-Dserver.port=80` |
41| .NET | Auto-detected | `dotnet myapp.dll` |
42 
43### Dockerfile (When Needed)
44 
45Use a Dockerfile when the app requires custom system dependencies or multi-process setups:
46 
47```dockerfile
48FROM node:20-slim
49WORKDIR /app
50COPY package*.json ./
51RUN npm ci --omit=dev
52COPY . .
53EXPOSE 8080
54CMD ["node", "server.js"]
55```
56 
57> ⚠️ **Port**: App Service injects `PORT` env var. Always bind to `process.env.PORT || 8080`.
58 
59### Application Insights Integration
60 
61```javascript
62// Add as FIRST import in entry point
63const appInsights = require('applicationinsights');
64appInsights.setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING)
65  .setAutoCollectRequests(true)
66  .setAutoCollectExceptions(true)
67  .start();
68```
69 
70## Database Migration Patterns
71 
72| Source | Azure Target | Connection Pattern |
73|--------|--------------|--------------------|
74| RDS PostgreSQL | Azure Database for PostgreSQL Flexible Server | Managed identity + `@azure/identity` |
75| RDS MySQL | Azure Database for MySQL Flexible Server | Managed identity + `@azure/identity` |
76| RDS SQL Server | Azure SQL Database | Managed identity + `@azure/identity` |
77| Heroku Postgres | Azure Database for PostgreSQL Flexible Server | Managed identity |
78| Cloud SQL | Azure SQL / PostgreSQL Flexible Server | Managed identity |
79| MongoDB Atlas | Azure Cosmos DB for MongoDB | Connection string → managed identity |
80 
81### Managed Identity Database Connection (Node.js)
82 
83```javascript
84const { DefaultAzureCredential } = require('@azure/identity');
85const { Client } = require('pg');
86 
87async function main() {
88  const credential = new DefaultAzureCredential({
89    managedIdentityClientId: process.env.AZURE_CLIENT_ID
90  });
91  const token = await credential.getToken('https://ossrdbms-aad.database.windows.net/.default');
92 
93  const client = new Client({
94    host: process.env.PGHOST,
95    database: process.env.PGDATABASE,
96    user: process.env.PGUSER,
97    password: token.token,
98    ssl: { rejectUnauthorized: true },
99    port: 5432
100  });
101  await client.connect();
102  // ... use client
103}
104 
105main().catch(console.error);
106```
107 
108> ⚠️ Wrap in `async function main()` — top-level `await` is not supported in CommonJS or many Node.js entrypoints. For ESM, top-level await works only with `"type": "module"` in `package.json`.
109 
110## Static Assets & CDN
111 
112If the source app serves static assets, consider:
1131. **Azure Blob Storage + CDN** for static files
1142. **Azure Front Door** for global distribution
1153. **App Service built-in static file serving** for simple cases
116 
117## Background Workers
118 
119| Source Pattern | Azure Equivalent |
120|---------------|------------------|
121| Heroku Worker dyno | WebJobs (continuous) or separate Container App |
122| Beanstalk Worker tier | WebJobs or Azure Functions |
123| App Engine service (worker) | WebJobs or Azure Functions |
124| Cron jobs | WebJobs (triggered) or Azure Functions Timer trigger |
125 
126## Handoff to azure-prepare
127 
128After code migration is complete:
129 
1301. Update `migration-status.md` — mark Code Migration as ✅ Complete
1312. Invoke **azure-prepare** — pass the assessment report context so it can:
132   - Use the service mapping as requirements input
133   - Generate IaC (Bicep/Terraform) for the mapped Azure services
134   - Create `azure.yaml` and `.azure/preparation-manifest.md`
135   - Apply security hardening
1363. azure-prepare will then chain to **azure-validate** → **azure-deploy**
137