8 min read
Deploy Docker Container to Azure Web App: Complete Guide
Key takeaways
- Deploying a Docker container to Azure Web App requires pushing your image to Azure Container Registry, then creating the app with --deployment-container-image-name.
- Setting WEBSITES_PORT to match your container's listening port fixes most 500 errors and timeouts after deploy.
- Your container must bind to 0.0.0.0, not localhost, or Azure reports the app as unhealthy regardless of configuration.
- Continuous deployment is wired by enabling CD on the Web App and registering the resulting webhook URL against your ACR registry for push events.
- Azure requires an international payment card even for free-tier usage, so developers paying with MTN or Airtel mobile money need an alternative PaaS.
To deploy a Docker container to Azure Web App, push your image to Azure Container Registry, create a Web App with az webapp create pointing at that image, then set WEBSITES_PORT so Azure maps traffic to the right container port. This guide covers every az CLI command, webhook-based continuous deployment, and the two failure points most tutorials skip, plus what it costs and which alternatives accept mobile money.
What do you need before deploying a Docker container to Azure Web App?
Four things: an Azure account, the Azure CLI installed, Docker running locally, and a Dockerfile that builds. The az CLI reference covers every command you will run, and you can install Docker from the official docs for your OS.
The card requirement nobody mentions for East African developers
Azure requires a payment card even for free-tier usage, and it bills in USD. If your only payment methods are MTN Mobile Money or Airtel Money, you cannot complete signup, and the walkthrough below stops at step one. If that is your situation, a PaaS that accepts mobile money, like Omeganodes, or a git-push deploy flow such as deploying Node.js with git push skips the card problem entirely.
What a minimal Dockerfile must look like
Azure runs your container as-is, so your Dockerfile needs an explicit EXPOSE for the port your app listens on and a working CMD. If your app reads a PORT environment variable, handle the mismatch before you deploy; section 4 covers why.
How do you push your Docker image to Azure Container Registry?
Create the registry with az acr create
Pick a globally unique name (lowercase letters and numbers only), then run:
az acr create --resource-group myRG --name myregistry --sku Basic
Basic is the right SKU for a side project. Log in next:
az acr login --name myregistry
Tag and push your image
ACR needs its login server in the tag. Get it, tag, push:
az acr show --name myregistry --query loginServer -o tsv
docker tag myapp:latest myregistry.azurecr.io/myapp:v1
docker push myregistry.azurecr.io/myapp:v1
If the push stalls on auth, run az acr login again; tokens expire.
Why Admin credentials are the pragmatic choice for a solo dev
Web App needs credentials to pull from ACR. Service principals are the "correct" answer, but for one person shipping a side project, admin credentials are simpler:
az acr update -n myregistry --admin-enabled true
az acr credential show --name myregistry --query "passwords[0].value" -o tsv
You will paste these into the Web App config in the next section. If you would rather skip Azure entirely, a push-to-deploy PaaS like Omeganodes handles the registry step for you.
How do you create an Azure Web App configured for a custom container?
The exact az webapp create command
Create a Linux plan first, then the app:
az appservice plan create --name myplan --resource-group myrg --is-linux --sku B1
az webapp create --resource-group myrg --plan myplan --name myapp \
--deployment-container-image-name myregistry.azurecr.io/myapp:latest
The --deployment-container-image-name flag is what tells Azure this is a custom container, not a code deployment.
Pointing the Web App at your ACR image
Your registry is private, so the Web App needs credentials to pull from it. The simplest path is the admin credential:
az webapp config container set --name myapp --resource-group myrg \
--container-image-name myregistry.azurecr.io/myapp:latest \
--container-registry-url https://myregistry.azurecr.io \
--container-registry-user myregistry --container-registry-password <token>
This wiring is the step most tutorials compress into one line and then wonder why pulls fail. The Microsoft Learn documentation on App Service covers the container configuration options in full, including managed identity as an alternative to admin credentials. The same principle applies on any PaaS: the platform needs to authenticate against your registry before anything else works. If you would rather skip registry wiring entirely, a push-to-deploy platform like Omeganodes builds from your repo and handles the pull for you.
Choosing a pricing tier without surprises
The B1 tier is the cheapest Linux option and is fine for a side project, but it has roughly 1.75 GB RAM and shared CPU, so a Node or Java container will feel tight. Free and shared tiers exist for Linux but do not support custom containers reliably, so budget for B1 from day one.
How do you set the correct port and startup command for your container?
WEBSITES_PORT: the setting that fixes most 500 errors
Azure routes traffic to port 80 and 443 by default. If your container listens on anything else, requests fail with a 500 error or a timeout. Set the app setting so the platform knows where to forward:
az webapp config appsettings set \
--resource-group my-rg --name my-webapp \
--settings WEBSITES_PORT=3000
No YAML, no config file, just one setting. Restart the app after changing it.
When you actually need a startup command
Only set a startup command when your image has no valid ENTRYPOINT or CMD. Otherwise leave it empty and let the image do its job:
az webapp config set \
--resource-group my-rg --name my-webapp \
--startup-file "node server.js"
A startup command that duplicates the image's own entrypoint is a common cause of crash loops.
Listening on 0.0.0.0, not localhost
Your app must bind to 0.0.0.0. A container bound to localhost accepts nothing from outside, and Azure reports the app as unhealthy no matter what you set. This single line fixes more "container not starting" reports than any other change. The same trap exists on every PaaS, including the ones we compare later, and it is one reason we built push-to-deploy on Omeganodes to handle port detection for you.
How do you enable continuous deployment from ACR to Azure Web App?
Enable CD with az webapp deployment container config
One command wires the webhook:
az webapp deployment container config \
--name myapp --resource-group myrg --enable-cd true
The output includes a webhook URL. Register it against your registry so a docker push triggers redeploy:
az acr webhook create \
--registry myregistry --name myapp-cd \
--uri <WEBHOOK_URL> --actions push
What the webhook does and how to test it
On every push, ACR POSTs to the webhook and App Service pulls the new image tagged latest. Test it with az acr webhook ping --registry myregistry --name myapp-cd, then check az webapp log tail for the pull event. If the app restarts with the old image, confirm the container exposes the port App Service expects, since the App Service documentation covers how custom containers route traffic.
Adding a GitHub Actions build step on top
Call az acr build in your workflow, then ping the webhook. If you would rather skip ACR, webhooks, and YAML entirely, Omeganodes deploys straight from GitHub with automatic HTTPS and MTN or Airtel mobile money billing.
Why is your container failing to start on Azure Web App?
Four failures cover almost every broken deploy: wrong port, missing startup command, image pull errors, and crash loops. Diagnose all four from the logs before touching configuration.
Reading logs with az webapp log tail
Run az webapp log tail --name <app> --resource-group <rg> to stream live logs. Container startup errors appear within seconds of a restart, so trigger one with az webapp restart and watch the output. Enable --web-server-logging filesystem first if the stream is empty.
Port mismatch vs startup command failure
A port mismatch logs "container didn't respond to HTTP pings on port" followed by the port Azure expected. Fix it with az webapp config appsettings set --settings WEBSITES_PORT=3000, matching your app's EXPOSE value. A startup command failure instead shows the container exiting immediately with your command in the error text; set it via az webapp config set --startup-file <command> or fix your image's ENTRYPOINT.
Image pull and authentication errors
"Unauthorized" or "manifest unknown" means the Web App's ACR credentials are wrong or the tag doesn't exist. Re-run az webapp config container set with --image pointing at an exact tag, never latest. Each restart burns billable compute time while you debug, and even the free tier has limits documented on Microsoft's App Service pricing page.
How does deploying to Azure Web App compare with ECS, Fargate, EKS, Google Cloud Run, and DigitalOcean?
Comparison table: setup effort, pricing, payment methods
| Platform | Setup effort | Pricing model | Payment |
|---|---|---|---|
| Azure Web App (containers) | az CLI, ACR, WEBSITES_PORT, startup command | Pay-as-you-go, per instance | International card required |
| AWS ECS / Fargate / EKS | Cluster, task definitions, load balancer | Per-second on Fargate, EKS adds cluster fee | International card required |
| Google Cloud Run | Build image, one deploy command | Per-second, scale to zero | International card required |
| DigitalOcean App Platform | Git or registry connection | Fixed tiers | Card or PayPal |
| Omeganodes | Git push to deploy, no YAML | Fixed tiers, regional prices | MTN Mobile Money, Airtel Money |
Every option above except Omeganodes bills in USD on a card most Kenyan and Ugandan developers cannot get. That is the deciding filter before pricing even matters.
Where Omeganodes falls short: no Docker-in-the-middle, fewer regions, no per-second billing
Honest run through the same criteria: Omeganodes deploys from GitHub rather than letting you push an existing Docker image to a registry, so the Azure walkthrough in this article has no equivalent there. Regions are limited to EU servers, not global. Billing is fixed tiers, not per-second, so idle side projects pay the same as busy ones.
When Azure Web App is still the right call
If you already have a Dockerfile, need a specific Azure region, or want per-second-style scaling tied to usage, Azure Web App earns the setup effort. If you need git push to deploy and mobile money, the alternatives above fit better.
FAQ
How much does Azure App Service cost per month for a small container app?
The B1 tier is the cheapest Linux plan that reliably runs custom containers, and it bills hourly on a pay-as-you-go basis, so a container running around the clock costs roughly $13 per month. Free and shared Linux tiers exist but do not support custom containers reliably, so budget for B1 from day one.
Can I pay for Azure with mobile money like MTN or Airtel?
No. Azure requires an international payment card even for free-tier usage and bills in USD, so MTN Mobile Money or Airtel Money cannot complete signup. If those are your only payment methods, a PaaS that bills in mobile money, or a git-push deploy platform, avoids the card requirement entirely.
Why does my Azure Web App return a 500 error after deploying my container?
Almost always a port mismatch. Azure forwards traffic to the port it expects, and if your container listens elsewhere, requests fail with a 500 or timeout. Set WEBSITES_PORT to match your app's listening port, confirm the app binds to 0.0.0.0 rather than localhost, then restart the app.
Deploy at the speed of Africa
World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.