DEV Community

Zia Ullah
Zia Ullah

Posted on

How to Deploy a Full-Stack Node.js App on Azure: A Step-by-Step Guide

#azure #cicd #node #tutorial

The first time I deployed a production app to Azure, I spent three hours troubleshooting a crash that turned out to be one line: the app was listening on port 3000 instead of process.env.PORT. Azure injects its own port at runtime, and if your app ignores it, the health check fails silently and the whole thing dies on startup.

That was my introduction to cloud deployment. Since then I've deployed several production apps to Azure across different projects. I've made most of the mistakes worth making, and this guide is the walkthrough I wish I'd had.

We'll cover App Service, Azure Database for PostgreSQL, environment variables, and a GitHub Actions CI/CD pipeline that handles deployments automatically.

Prerequisites

  • An Azure account (free tier works for this guide)
  • A Node.js app (Express or similar) with a package.json
  • PostgreSQL as your database
  • A GitHub repository for your code
  • Azure CLI installed locally

What We'll Deploy

  • Backend: Node.js / Express API
  • Database: Azure Database for PostgreSQL (Flexible Server)
  • Hosting: Azure App Service (Linux)
  • CI/CD: GitHub Actions

Step 1: Create a Resource Group

Everything in Azure lives inside a Resource Group — a logical container for all your app's cloud resources.

az login

az group create \
  --name myapp-rg \
  --location westeurope
Enter fullscreen mode Exit fullscreen mode

Use a location close to your users. westeurope (Netherlands) works well for European users.

Step 2: Create the PostgreSQL Database

Today, the recommended option is Azure Database for PostgreSQL Flexible Server. It is cheaper and more flexible than the older Single Server from Azure, which is being retired.

az postgres flexible-server create \
  --resource-group myapp-rg \
  --name myapp-db-server \
  --location westeurope \
  --admin-user dbadmin \
  --admin-password YourStrongPassword123! \
  --sku-name Standard_B1ms \
  --tier Burstable \
  --storage-size 32 \
  --version 15
Enter fullscreen mode Exit fullscreen mode

Then create your database:

az postgres flexible-server db create \
  --resource-group myapp-rg \
  --server-name myapp-db-server \
  --database-name myappdb
Enter fullscreen mode Exit fullscreen mode

Allow your App Service to connect by adding a firewall rule:

az postgres flexible-server firewall-rule create \
  --resource-group myapp-rg \
  --name myapp-db-server \
  --rule-name AllowAzureServices \
  --start-ip-address 0.0.0.0 \
  --end-ip-address 0.0.0.0
Enter fullscreen mode Exit fullscreen mode

Setting start and end IP to 0.0.0.0 allows Azure-internal traffic. This is fine for App Service to Database communication — just don't open it to public internet IPs.

Step 3: Create the App Service Plan and Web App

The compute resources are defined by the App Service Plan. Begin at B1 (Basic) and develop later if required.

az appservice plan create \
  --name myapp-plan \
  --resource-group myapp-rg \
  --sku B1 \
  --is-linux

az webapp create \
  --name myapp-api \
  --resource-group myapp-rg \
  --plan myapp-plan \
  --runtime "NODE:20-lts"
Enter fullscreen mode Exit fullscreen mode

Your app will be live at: https://myapp-api.azurewebsites.net

Step 4: Set Environment Variables

Never put secrets in your code. Azure App Service has Application Settings. They are injected as environment variables on runtime, never touching your source code or repository.

az webapp config appsettings set \
  --name myapp-api \
  --resource-group myapp-rg \
  --settings \
    NODE_ENV=production \
    DATABASE_URL="postgresql://dbadmin:YourStrongPassword123!@myapp-db-server.postgres.database.azure.com/myappdb?sslmode=require" \
    JWT_SECRET="your-secret-key-here" \
    PORT=8080
Enter fullscreen mode Exit fullscreen mode

In your Node.js app, read them as normal:

const dbUrl = process.env.DATABASE_URL;
const jwtSecret = process.env.JWT_SECRET;
Enter fullscreen mode Exit fullscreen mode

And this is the fix for the port issue I mentioned at the start — make sure your server uses process.env.PORT:

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Running on port ${PORT}`));
Enter fullscreen mode Exit fullscreen mode

Step 5: Prepare Your App for Production

Make sure your package.json has a start script:

{
  "scripts": {
    "start": "node server.js",
    "build": "npm install --production"
  }
}
Enter fullscreen mode Exit fullscreen mode

Azure PostgreSQL requires SSL. If you're using the pg package:

const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: {
    rejectUnauthorized: false,
  },
});
Enter fullscreen mode Exit fullscreen mode

Pin your Node.js version in package.json:

{
  "engines": {
    "node": ">=20.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 6: Deploy with GitHub Actions (CI/CD)

Manual deployments are OK, but once you have GitHub Actions set up, every push to main automatically deploys. The azure documentation for this is not great so here is the exact process:

Get your publish profile:

az webapp deployment list-publishing-profiles \
  --name myapp-api \
  --resource-group myapp-rg \
  --xml
Enter fullscreen mode Exit fullscreen mode

Copy the XML output. In your GitHub repo go to Settings → Secrets → Actions and add a secret called AZURE_WEBAPP_PUBLISH_PROFILE with that XML as the value.

Then create .github/workflows/deploy.yml:

name: Deploy to Azure

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci --production

      - name: Deploy to Azure Web App
        uses: azure/webapps-deploy@v3
        with:
          app-name: myapp-api
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
          package: .
Enter fullscreen mode Exit fullscreen mode

Push to main, watch the Actions tab, and your app is live within a couple of minutes.

Step 7: Run Database Migrations on Deploy

If you use a migration tool like Knex or db-migrate, add a migration step before deploying:

- name: Run database migrations
  run: npm run migrate
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
Enter fullscreen mode Exit fullscreen mode

Add DATABASE_URL as a separate GitHub Actions secret for this.

Step 8: Set Up Health Checks

Add a health endpoint to your app:

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
});
Enter fullscreen mode Exit fullscreen mode

Configure Azure to use it:

az webapp config set \
  --name myapp-api \
  --resource-group myapp-rg \
  --generic-configurations '{"healthCheckPath": "/health"}'
Enter fullscreen mode Exit fullscreen mode

Azure periodically pings this endpoint. If it gets anything other than 200, it takes traffic off that instance and starts it back up again. It's saved me a few times when a deployment went awry.

Monitoring and Logs

To stream live logs:

az webapp log tail \
  --name myapp-api \
  --resource-group myapp-rg
Enter fullscreen mode Exit fullscreen mode

For Application Insights, initialize the SDK at the very top of your entry file, before any other imports:

const appInsights = require('applicationinsights');
appInsights.setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING).start();
Enter fullscreen mode Exit fullscreen mode

Things That Caught Me Off Guard

A few things from running Node.js apps on Azure in production that aren't obvious from the docs.

Turn on "Always On" under Configuration → General Settings. By default, Azure puts your app to sleep after a period of inactivity on lower tiers. If you're building anything where users expect instant response — not a 15-second cold start — you need this on. I've seen clients blame "the server" for slowness when it was just Azure waking up from idle.

Use deployment slots. Azure App Service lets you deploy to a staging slot first, verify everything works, then swap to production with zero downtime. The swap is quick and reversible. I started using this after a bad deployment took down a production app during business hours. It won't happen again.

Watch your PostgreSQL CPU credits on the Burstable tier. The B1ms is cheap but runs on burstable CPU — you have a credit bucket that depletes under sustained load. Set up an Azure Monitor alert on CPU credit balance so you know before the instance starts throttling, not after users start complaining.

Wrapping Up

From the first az login to a live URL takes about 30 minutes. After that, the GitHub Actions pipeline handles every deployment automatically. Migrations run on push, and health checks restart the app if anything goes wrong.

The things that trip up most people are the PORT variable, SSL on the PostgreSQL connection, and forgetting to turn on Always On. Get these right from the start, and you'll save yourself a few hours of debugging.

Zia Ullah is a full-stack developer with over 12 years of experience, starting in 2013. He specializes in web applications for healthcare and SaaS. He works at ValueAdd, a software development company based in Sweden.

Top comments (0)