01
Confirm what the process started, not just that it started
Record the image tag or digest, startup command, and the application’s listening address from its logs. A process listening on 127.0.0.1:3000 is a different situation from one listening on 0.0.0.0:8080. An EXPOSE instruction in a Dockerfile documents a port; it does not make the application bind that port.
Also check whether the entrypoint exits or fails before starting HTTP at all. Missing files, invalid runtime configuration, failed dependency initialization, and wrong executable architecture will not be fixed by changing a routing setting. Keep the earliest useful startup error.
02
Identify classic custom-container versus sidecar-enabled configuration
The port-setting mechanism depends on the App Service container model. In the classic Linux custom-container model, the documented WEBSITES_PORT setting tells App Service about a nondefault application port. It is a routing setting, not an instruction that rewrites your application’s listen call.
For sidecar-enabled apps, use the main container’s configured target port in the site-container configuration. Do not assume changing WEBSITES_PORT will control a sidecar-enabled app. Identify the mode in the portal or the relevant configuration before applying a recipe from another deployment.
03
Inspect a narrow set of configuration and logs
The following commands inspect the app’s reported state, Linux container configuration, and only the relevant classic port setting. Avoid dumping all app settings into a support ticket; they can contain credentials. CLI output and exact properties can vary with the app model.
If container logging is not enabled, enable the appropriate diagnostic logging through your operational process, then reproduce once and read the startup sequence. State being Running does not establish that an HTTP request reaches the application.
az webapp show --resource-group example-rg --name example-app --query '{state:state,host:defaultHostName}'
az webapp config show --resource-group example-rg --name example-app --query '{linuxFxVersion:linuxFxVersion}'
az webapp config appsettings list --resource-group example-rg --name example-app --query "[?name=='WEBSITES_PORT']"
az webapp log tail --resource-group example-rg --name example-app04
Make the listener and routing target agree
For a classic app whose process is confirmed to listen on port 8080, setting WEBSITES_PORT=8080 is one side of the correction. Configure the application to bind a reachable interface on that port using its framework’s supported settings. Changing only the Dockerfile metadata does not do this.
The command below changes the classic app configuration and may cause an app restart; apply it only after confirming the target app and mode. For a sidecar-enabled app, change the main container’s target-port configuration instead. Keep that routing change separate from unrelated image or dependency upgrades.
# Classic Linux custom-container apps only; this changes configuration.
az webapp config appsettings set --resource-group example-rg --name example-app --settings WEBSITES_PORT=808005
Reproduce the image contract locally
Run the same image with the same startup command and nonsecret settings in a disposable local environment. Map the port the process actually uses, then make an HTTP request through the host mapping. If the request fails locally, fix the application contract before adding Azure-specific workarounds.
If local HTTP passes but Azure still fails, compare the deployed digest, environment settings, startup override, and routing mode. A cached local image or different command can make “it works on my machine” a comparison of two different programs.
06
Verify the public path after the change
Check the new startup logs and request the intended application endpoint through the App Service hostname. Test a representative operation as well as a lightweight endpoint. Confirm that a subsequent instance start succeeds without an unexplained delay or manual intervention.
If the listener and target match, move on to the next supported hypothesis: application exceptions, unavailable dependencies, authentication, health-check behavior, or image startup failure. Port configuration is a specific explanation, not a universal cure for every failed deployment.
Know the limits
This guide concerns Linux custom containers, not every built-in App Service runtime. Portal and CLI options evolve. Do not apply the classic WEBSITES_PORT command to a sidecar-enabled configuration without checking its routing model.
Sources & further reading
A technical publication by CoreTrailKit.
Browse all articles