Package & Deploy to Azure Gov

Why deployment is different on Azure Gov

Vercel is not an option. Netlify is not an option. The DS platform runs on Azure Government App Service, and the deployment process is specific: build a standalone Next.js bundle, copy the static assets that standalone mode intentionally excludes, configure environment variables for gov cloud endpoints, set up health checks, and zip-deploy to the App Service instance.

Every team that deploys Next.js to Azure App Service hits the same problem the first time: the application starts, the API routes work, but every page loads without CSS, images, or client-side JavaScript. The static files are missing. This lesson makes sure that does not happen to you.

Standalone output mode

Next.js standalone mode produces a self-contained server that includes only the files needed to run in production — no node_modules directory (it bundles dependencies), no dev tooling, no test files. The output is a minimal folder that can be zipped and deployed.

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
  // Required for Azure App Service — it expects the app on 8080
  serverExternalPackages: ['applicationinsights'],
};

export default nextConfig;

What standalone mode produces

After npm run build, the output looks like this:

.next/
  standalone/
    server.js           # The production server entry point
    package.json
    node_modules/       # Bundled dependencies (much smaller than full)
    .next/
      server/           # Server-side rendered pages and API routes
      BUILD_ID
      # NOTE: .next/static/ is NOT here
  static/               # Client-side JS, CSS, images
    chunks/
    css/
    media/
public/                 # Your public/ assets (favicons, manifests, etc.)

Notice the gap: .next/standalone/.next/static/ does not exist. The static assets are in .next/static/, one level up from the standalone folder. The public/ directory is also not inside standalone.

This is intentional. The Next.js team assumes you will serve static files from a CDN in production. Azure App Service does not have a built-in CDN separation — it serves everything from the same process. So you copy the files manually.

The critical copy step

This is the step that every team misses the first time. It is two commands:

cp -r .next/static .next/standalone/.next/static
cp -r public .next/standalone/public

Without these, your deployed application returns HTML with references to /_next/static/chunks/main-abc123.js and /_next/static/css/styles-def456.css, but those files do not exist on the server. The browser shows a blank page or unstyled HTML with no interactivity.

The deployment script

The prompt

Generate a deployment script called deploy.sh for our Next.js 15.5 platform
targeting Azure Government App Service.

Requirements:
1. Build step: npm ci && npm run build
2. Static file copy:
   - cp -r .next/static .next/standalone/.next/static
   - cp -r public .next/standalone/public
3. Create a zip of the .next/standalone directory
4. Deploy using az webapp deploy:
   - Resource group and app name from environment variables
   - Use --type zip
   - Azure Gov cloud (az cloud set --name AzureUSGovernment)
5. Health check: after deploy, curl the /api/health endpoint and verify
   200 response within 60 seconds (retry every 5 seconds)
6. Environment variables to set on the App Service:
   - NODE_ENV=production
   - PORT=8080 (Azure App Service requirement)
   - WEBSITES_PORT=8080
   - KEY_VAULT_NAME (from env)
   - AZURE_AUTHORITY_HOST=https://login.microsoftonline.us
   - APPLICATIONINSIGHTS_CONNECTION_STRING (from Key Vault, not hardcoded)
7. Include a --dry-run flag that builds and packages but does not deploy
8. Exit with error code if any step fails (set -euo pipefail)

What the script produces

The AI generates a script with these key sections:

#!/usr/bin/env bash
set -euo pipefail

# Configuration from environment
RESOURCE_GROUP="${AZURE_RESOURCE_GROUP:?Set AZURE_RESOURCE_GROUP}"
APP_NAME="${AZURE_APP_NAME:?Set AZURE_APP_NAME}"
DRY_RUN="${1:-}"

echo "=== Building Next.js standalone ==="
npm ci --ignore-scripts=false
npm run build

echo "=== Copying static assets ==="
cp -r .next/static .next/standalone/.next/static
cp -r public .next/standalone/public

echo "=== Creating deployment package ==="
cd .next/standalone
zip -r ../../deploy.zip . -x "*.map"
cd ../..

PACKAGE_SIZE=$(du -sh deploy.zip | cut -f1)
echo "Package size: ${PACKAGE_SIZE}"

if [ "$DRY_RUN" = "--dry-run" ]; then
  echo "=== Dry run — skipping deployment ==="
  echo "Package ready: deploy.zip"
  exit 0
fi

echo "=== Deploying to Azure Gov ==="
az cloud set --name AzureUSGovernment
az webapp deploy \
  --resource-group "$RESOURCE_GROUP" \
  --name "$APP_NAME" \
  --type zip \
  --src-path deploy.zip

echo "=== Health check ==="
HEALTH_URL="https://${APP_NAME}.azurewebsites.us/api/health"
for i in {1..12}; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL" || echo "000")
  if [ "$STATUS" = "200" ]; then
    echo "Health check passed (attempt ${i})"
    exit 0
  fi
  echo "Waiting for health check... (attempt ${i}/12, status: ${STATUS})"
  sleep 5
done

echo "ERROR: Health check failed after 60 seconds"
exit 1

Environment variables for Azure Gov

Azure App Service environment variables are configured through the Azure portal or the az CLI. These are the variables the DS platform requires in production:

az webapp config appsettings set \
  --resource-group "$RESOURCE_GROUP" \
  --name "$APP_NAME" \
  --settings \
    NODE_ENV=production \
    PORT=8080 \
    WEBSITES_PORT=8080 \
    KEY_VAULT_NAME=ds-platform-kv \
    AZURE_AUTHORITY_HOST=https://login.microsoftonline.us \
    NEXTAUTH_URL=https://ds-platform.azurewebsites.us

Health check endpoint

Azure App Service pings a health check endpoint to determine if your app is ready to receive traffic. If the health check fails, App Service restarts the container.

import { NextResponse } from 'next/server';

export async function GET() {
  // Basic health: server is running and can respond
  const health = {
    status: 'healthy',
    timestamp: new Date().toISOString(),
    version: process.env.BUILD_ID ?? 'unknown',
    environment: process.env.NODE_ENV,
  };

  // Optional: verify downstream dependencies
  // Only if you want health to reflect DB connectivity
  // Caution: this makes health checks slower and can
  // cause restart loops if the DB is temporarily down

  return NextResponse.json(health, { status: 200 });
}

Configure the health check in the Azure portal: App Service > Health check > Path: /api/health. Set the threshold to 3 failed checks before restart.

See it in action

Common deployment failures

Deployment to multiple environments

The DS platform deploys to three environments: dev, staging, and production. The deployment script is the same; only the environment variables change.

# Dev
AZURE_RESOURCE_GROUP=DS-Platform-Dev-RG AZURE_APP_NAME=ds-platform-dev ./deploy.sh

# Staging
AZURE_RESOURCE_GROUP=DS-Platform-Staging-RG AZURE_APP_NAME=ds-platform-staging ./deploy.sh

# Production (requires manual approval in Azure Pipelines)
AZURE_RESOURCE_GROUP=DS-Platform-Prod-RG AZURE_APP_NAME=ds-platform-prod ./deploy.sh

Key takeaways

• Standalone output mode produces a minimal server bundle without node_modules. Add output: 'standalone' to next.config.ts and add native SDKs like applicationinsights to serverExternalPackages.
• Copy static files before zipping. cp -r .next/static .next/standalone/.next/static and cp -r public .next/standalone/public are mandatory. This is the most common Next.js deployment failure on Azure App Service.
• Azure Gov uses .azurewebsites.us, not .azurewebsites.net. All URLs, CORS origins, and callback configurations must use the gov domain.
• Port 8080 is the Azure App Service convention. Set both PORT and WEBSITES_PORT to 8080 in App Service configuration.
• Health checks should be simple. Return 200 if the process is alive. Do not check database connectivity in the health endpoint unless you want restart loops during transient DB outages.
• Secrets belong in Key Vault, not in App Service configuration. NEXTAUTH_SECRET, database connection strings, and API keys should be fetched at runtime via Managed Identity.

What’s next

In the capstone lesson, you will automate this entire deployment process in an Azure Pipelines YAML pipeline: lint, test, build, Docker image, and deploy to Azure Gov — with approval gates, SAST scanning, and environment-specific variables.