Deploy OSS on Microsoft Azure

How to deploy OSS Password Pusher on Azure, including VM + Docker Compose and managed Azure alternatives.

This article applies to: OSS Self-Hosted

Deploy OSS Password Pusher on Microsoft Azure

This guide explains how to run open source Password Pusher on Azure and what to do when your Azure target service does not run docker-compose.yml directly.

For most teams, the easiest and most supportable Azure path is:

  • Azure Linux VM + Docker Compose

OSS vs Pro on Azure (important differences)

  • Image source
    • OSS: public Docker Hub images (pglombardo/*)
    • Pro: private registry.apnotic.com/*
  • Install flow
    • OSS: you manage your own docker-compose.yml, secrets, and updates
    • Pro: personalized installer writes deployment artifacts
  • Secrets
    • OSS: you must manage and back up runtime secrets (for example PWPUSH_MASTER_KEY, SECRET_KEY_BASE) yourself
    • Pro: installer-generated .env is part of recovery

Does Azure support Docker Compose?

It depends on the Azure service:

  • Azure Virtual Machines: yes. Install Docker + Docker Compose and run the standard OSS compose flow.
  • Azure App Service: legacy Docker Compose support exists but is on a retirement path; Sidecar is the migration model.
  • Azure Container Apps / AKS: use platform-native configuration instead of directly running docker-compose.yml.

For this reason, Azure VM + Compose is the default recommendation for OSS.

OSS images for Azure deployments

OSS images are published on Docker Hub and built for linux/amd64:

  • pglombardo/pwpush
  • pglombardo/pwpush-public-gateway
  • pglombardo/pwpush-worker

Use tags appropriate for your release policy (stable, latest, or versioned tags).

Recommended path: Azure VM + Docker Compose

1) Provision VM

  1. Create an Ubuntu LTS VM in Azure.
  2. Open ports needed by your deployment (80/443 for in-container TLS, or your reverse-proxy path).
  3. Assign static IP and DNS for your hostname.

2) Install Docker and Compose

docker --version
docker compose version

3) Deploy with OSS compose

  1. Download/clone the OSS docker-compose.yml.
  2. Set required environment values (at minimum your encryption keys and desired TLS/database settings).
  3. Start services:
docker compose up -d

See Installation for baseline setup details.

Troubleshooting: architecture mismatch in Azure

If Azure reports an invalid manifest/architecture when deploying an image from ACR, the mirrored tag likely does not match your target runtime architecture.

Password Pusher OSS images are published as linux/amd64 only.

Check the manifest:

docker manifest inspect <image>:<tag>

Confirm platform includes linux/amd64.

Use image directly (no mirror)

If your Azure service can pull directly from Docker Hub, use the OSS image directly and skip ACR mirroring:

  • pglombardo/pwpush:stable (or your chosen tag)

This is the simplest way to avoid architecture mismatch during copy/push workflows.

If you mirror images into ACR, import directly into ACR instead of pulling/re-pushing from a local workstation:

az acr import \
  --name <your-acr-name> \
  --source docker.io/pglombardo/pwpush:stable \
  --image pwpush:stable

For additional OSS images:

  • docker.io/pglombardo/pwpush-public-gateway:stable -> pwpush-public-gateway:stable
  • docker.io/pglombardo/pwpush-worker:stable -> pwpush-worker:stable

Then verify:

docker manifest inspect <your-acr-login-server>/pwpush:stable

How updates work on Azure (OSS)

Updates are image replacement operations. Data persists when stored on persistent volumes or external databases/storage.

Azure VM + Docker Compose

From your compose directory:

docker compose pull
docker compose down
docker compose up -d

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

Deploy a new revision/version while keeping:

  • the same persistent storage for /opt/PasswordPusher/storage (if using SQLite/local files)
  • and/or the same external PostgreSQL endpoint (if using DATABASE_URL)

SQLite and upload persistence

For default SQLite deployments, keep persistent storage mounted. If SQLite or uploads live only in the container writable layer, replacing containers will lose data.

See Upgrades & Backups and How to Make the Database Ephemeral for details.

Managed Azure path (ACA/AKS) notes

When using ACA/AKS, translate compose settings into platform-native resources:

  • image reference
  • environment variables/secrets
  • persistent storage
  • ingress and custom domain/TLS

If you plan multi-replica operation, external PostgreSQL is generally the better long-term choice over SQLite.