Deploy on Microsoft Azure

How to deploy Password Pusher Pro Self-Hosted on Azure, including what to do when your target Azure service does not run docker-compose.yml directly.

This article applies to: Pro Self-Hosted

Deploy Password Pusher Pro on Microsoft Azure

This guide explains practical Azure deployment paths for Self-Hosted Pro and how they map to your edition (Starter, Advanced, or Enterprise).

If you want the quickest, lowest-risk Azure deployment, use an Azure Linux VM and run the standard install flow as-is.

Does Azure support Docker Compose?

Short answer: it depends on which Azure service you choose.

  • Azure Virtual Machines: yes. You can install Docker + Docker Compose and run the exact files from the Pro installer.
  • Azure App Service: legacy Docker Compose support exists today but Microsoft has announced retirement of this feature on March 31, 2027. New App Service deployments should use the Sidecar model instead of Compose. See Microsoft: Docker Compose migration on App Service.
  • Azure Service Fabric: has Docker Compose support in preview only and is marked not supported for production in Microsoft documentation: Service Fabric Compose preview.
  • Azure Container Apps / AKS: these platforms do not run your docker-compose.yml directly as the runtime model; you translate Compose settings into platform-native configuration.

Because of this, most customers should deploy Pro on Azure VM + Docker Compose unless they already operate Kubernetes or Container Apps at scale.

Choose your Azure deployment model

Azure model Best for Starter/Advanced Enterprise Notes
Azure VM + Docker Compose (recommended) Fastest path, closest to official install flow Yes Yes Runs the installer artifacts with minimal translation.
Azure Container Apps (ACA) Teams already standardized on ACA Possible, but more operational caveats Yes (recommended only with managed PostgreSQL) You must convert Compose settings to ACA definitions and secrets.
Azure Kubernetes Service (AKS) Large teams with Kubernetes expertise Possible Yes Highest control, highest complexity.
Azure App Service (Sidecar) Existing App Service shops Limited fit Limited fit Requires Sidecar config, not future-facing Compose.

Installer artifacts you must preserve

Your personalized install command (curl ... install.sh | sh) writes deployment artifacts that you should treat as canonical:

  • docker-compose.yml
  • .env (contains generated encryption keys and other runtime secrets)
  • create-dbs.sql (Enterprise, used to create cache/cable/queue PostgreSQL databases)

Back up .env with the same rigor as your database. Without these secrets, restored data may be undecryptable. See Backups.

Recommended path: Azure VM + Docker Compose

This path keeps the Pro deployment model unchanged and is the easiest to support.

1) Provision the VM

  1. Create an Ubuntu LTS VM in Azure.
  2. Size it using System Requirements.
  3. Open inbound ports 80 and 443 on the VM’s network security group.
  4. Assign a static public IP (or front it with your existing edge architecture).

2) Install Docker and Compose

Install Docker Engine and Docker Compose plugin on the VM, then verify:

docker --version
docker compose version

3) Configure DNS

Point your licensed hostname (for example pwp.example.com) to the VM public IP.

4) Run your personalized install command

Run the command from your provisioning email on the VM:

curl -fsSL "https://license-server/install.sh?license_key=YOUR-LICENSE-KEY" | sh

This pulls your image credentials and writes deployment files including .env with fresh encryption keys.

5) Verify edition-specific files

From the install directory:

  • All editions: confirm docker-compose.yml and .env exist.
  • Enterprise: confirm create-dbs.sql is present.

6) Start and complete first boot

docker compose up -d
docker compose logs --tail=100 pwpush-pro

Use the boot code from logs to create the first admin user in the web UI.

7) Complete post-install essentials

  1. Configure SMTP in Admin -> Settings -> Email.
  2. Configure SSO if needed in Admin -> Settings -> Auth.
  3. Implement database + .env backups.

Use Getting started checklist for the full runbook.

Azure Container Apps or AKS path (platform-native)

Use this path only if your organization requires ACA/AKS operations.

What changes compared to Compose

You will not run docker compose up -d. Instead, you map the same values into Azure-native resources:

  • Container image (by edition):
    • registry.apnotic.com/pwpush-pro:latest
    • registry.apnotic.com/pwpush-pro-advanced:latest
    • registry.apnotic.com/pwpush-pro-enterprise:latest
  • Environment variables and secrets from your generated .env
  • Persistent storage mount at /opt/PasswordPusher/storage
  • Ingress and custom domain/TLS routing

Enterprise database requirements on Azure

Enterprise requires four logical PostgreSQL databases:

  • pwpush-pro
  • pwpush-pro-cache
  • pwpush-pro-cable
  • pwpush-pro-queue

In Compose deployments, create-dbs.sql creates these automatically on first init. In managed Azure PostgreSQL, create them manually and then set:

  • DATABASE_URL
  • CACHE_DATABASE_URL
  • CABLE_DATABASE_URL
  • QUEUE_DATABASE_URL
  • BLAZER_DATABASE_URL

using your Azure PostgreSQL host and credentials.

Important caveat for Starter/Advanced on managed platforms

Starter/Advanced use SQLite by default. On orchestrated platforms, SQLite + shared network storage can introduce locking/performance tradeoffs depending on your storage class and scaling model. If you plan to scale replicas or operate fully managed Azure runtimes, Enterprise + PostgreSQL is generally the cleaner long-term architecture.

Troubleshooting: architecture mismatch in Azure

If Azure reports an architecture or manifest error (for example when creating a container from an image copied into ACR), the pushed image usually does not match the runtime architecture expected by the Azure host.

For Pro Self-Hosted, customers do not build images. Apnotic publishes official Pro images as linux/amd64.

Most mismatches happen during image mirroring/copying (for example, wrong source image/tag, or an architecture-specific copy process).

How to check image architecture

docker manifest inspect <image>:<tag>

Look for the platform entries in the manifest list.

Use the official published Pro image directly from registry.apnotic.com whenever possible. If you mirror into ACR, mirror the same official image/tag and verify the copied tag still resolves to linux/amd64.

docker pull --platform linux/amd64 registry.apnotic.com/pwpush-pro:latest
docker tag registry.apnotic.com/pwpush-pro:latest <your-acr>.azurecr.io/pwpush-pro:latest
docker push <your-acr>.azurecr.io/pwpush-pro:latest

For Advanced/Enterprise, substitute the corresponding image name.

Better than local re-push (when possible)

Prefer registry-to-registry import in Azure so your workstation architecture does not influence the result. This avoids many accidental architecture/tag mistakes when mirroring images.

Import directly from the Apnotic registry into your Azure Container Registry using Azure CLI.

  1. Ensure you have:
    • ACR name (for example myacr)
    • Your Self-Hosted Pro license key (used for registry.apnotic.com auth)
  2. Run import:

For registry.apnotic.com, both username and password are your license key.

az acr import \
  --name <your-acr-name> \
  --source registry.apnotic.com/pwpush-pro:latest \
  --image pwpush-pro:latest \
  --username <your-license-key> \
  --password <your-license-key>

For Advanced or Enterprise, replace the source and target image names:

  • registry.apnotic.com/pwpush-pro-advanced:latest -> pwpush-pro-advanced:latest
  • registry.apnotic.com/pwpush-pro-enterprise:latest -> pwpush-pro-enterprise:latest
  1. Verify the imported tag:
docker manifest inspect <your-acr-login-server>/pwpush-pro:latest

Confirm manifest platform entries include linux/amd64.

How updates work on Azure

Self-Hosted Pro updates are always an image replacement operation. Your data persists as long as it is stored outside the container writable layer.

Azure VM + Docker Compose

From the install directory:

docker compose pull
docker compose up -d

This recreates containers with newer images while keeping persistent volumes.

Managed Azure platforms (ACA/AKS/App Service Sidecar)

You deploy a new image revision/version and keep the same external state:

  • Same persistent volume mount for /opt/PasswordPusher/storage (Starter/Advanced local storage path)
  • Or same external PostgreSQL connection (Enterprise)
  • Or same external object storage if configured for uploads

SQLite and uploaded files: will updates lose data?

Not if persistence is configured correctly.

  • Safe: SQLite database and upload files on a persistent volume mounted at /opt/PasswordPusher/storage
  • Unsafe: SQLite and uploads stored only in container filesystem layer

If data is stored only inside the container layer, replacing the container will lose that data. This is why persistent volume configuration is mandatory for production.

Azure decision checklist

Choose Azure VM + Docker Compose if:

  • You want the documented install path with minimal changes.
  • You do not need Kubernetes-level orchestration.
  • You want the easiest recovery and support path.

Choose ACA/AKS if:

  • Your platform standards already require ACA/AKS.
  • Your team is comfortable translating Compose config to Azure-native resources.
  • You can manage external PostgreSQL for Enterprise and secret distribution from .env.
Topic Doc
Ordered setup runbook Getting started checklist
Install flow and personalized command How it works
Start/stop/update/logs Operations
Database and .env backup strategy Backups
Resource sizing System requirements