App platform App Service configuration complete field-manual-complete field-manual-complete

Startup command

A startup command is the instruction Azure App Service uses to start your Linux web app when the container comes up. It might launch Gunicorn, start a Node process, run a Java JAR, call a shell script, or point .NET to the right DLL. Without the right command, the app can deploy successfully but never listen on the expected port. For learners, it is the difference between files being present and the application process actually running correctly.

Aliases
startup-command, Startup command, App Service startup command, Linux App Service startup command, startup file, appCommandLine
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-25

Microsoft Learn

Microsoft Learn describes startup commands for App Service on Linux as commands or scripts the platform runs to start an application container. They tell the runtime how to launch the app process, such as a Java JAR, Node script, Python startup file, .NET DLL, or custom shell script.

Microsoft Learn: Azure App Service on Linux FAQ2026-05-25

Technical context

In Azure architecture, a startup command sits inside App Service configuration for Linux web apps and custom containers. It affects runtime startup, process launch, logging, health checks, restarts, and deployment troubleshooting. The command is evaluated after the app content or image is available, so it must match the runtime stack, filesystem paths, environment variables, and port behavior expected by App Service. It is not a control-plane resource by itself, but it is stored as app configuration and often managed through portal, ARM, Bicep, CLI, or pipeline automation.

Why it matters

It matters because many App Service incidents start after a clean deployment that never starts the intended process. The platform can pull code, mount files, and allocate an instance, but users still see 502, 503, or timeout errors if the startup command points to the wrong script, uses a missing package, binds to the wrong interface, or exits too early. The term also matters during migrations from virtual machines or containers because startup assumptions change. A documented command gives developers and operators a shared contract for how the app boots, where logs appear, and what must be checked before blaming Azure, code, networking, or scaling.

Where you see it

Signals, screens, and Azure surfaces where this term usually becomes operational.

Signal 01

In the App Service Configuration blade for Linux apps, where the Startup Command field shows the process or script Azure runs at container start time.

Signal 02

In Azure CLI output from az webapp config show, where appCommandLine and linuxFxVersion reveal how the site is expected to boot on Linux today safely.

Signal 03

In log stream or deployment logs, where missing scripts, wrong working directories, port binding failures, and package errors appear immediately after restart attempts in production.

When this becomes relevant

Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.

  • Start a Python web app with Gunicorn when App Service cannot infer the correct module, worker model, or bind settings.
  • Launch a Java JAR, Node server, or .NET DLL from the deployed path after migrating from a virtual machine.
  • Call a checked-in shell script that prepares lightweight runtime state before starting the actual application process.
  • Standardize startup behavior across deployment slots so a swap does not introduce a hidden process-launch difference.
  • Troubleshoot 502 or 503 responses after deployment when files exist but the application process never starts correctly.

Real-world case studies

Different enterprise-style examples that show the term being used to hit measurable objectives.

Case study 01

Language-learning platform fixes silent Python boot failures

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

An education technology platform migrated a Flask API to App Service on Linux, but deployments repeatedly succeeded while students received intermittent 503 errors after each release.

Business/Technical Objectives
  • Stop post-deployment outages caused by the wrong Python entry point.
  • Make startup behavior identical across staging and production slots.
  • Capture logs that showed whether Gunicorn started and stayed alive.
  • Give developers a rollback path that operators could execute quickly.
Solution Using Startup command

The team discovered that App Service was starting the wrong module after a package restructuring change. They defined an explicit startup command that launched Gunicorn with the correct app module, bind address, worker count, and timeout. The command was stored in deployment automation instead of edited in the portal. Operators used Azure CLI to record appCommandLine and linuxFxVersion before and after the change, then tailed logs immediately after slot restarts. A staging slot received the command first, ran smoke tests against lesson APIs, and then swapped to production after the log stream showed stable worker startup.

Results & Business Impact
  • Post-release 503 incidents dropped from five in one month to zero across the next six releases.
  • Average recovery time from a failed startup test improved from 47 minutes to eight minutes.
  • Staging and production startup configuration drift was eliminated in pipeline validation.
  • Student login failures during release windows fell from 3.8 percent to under 0.2 percent.
Key Takeaway for Glossary Readers

A startup command turns application boot into an explicit contract, which is essential when deployments succeed but the process never starts.

Case study 02

Factory scheduling app removes fragile boot-time installs

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A manufacturing plant ran a Java scheduling web app on App Service and used a startup script to download tools and patch configuration every time the app restarted.

Business/Technical Objectives
  • Reduce restart time during shift-change incidents.
  • Remove internet download dependencies from production startup.
  • Keep JVM startup parameters visible to both developers and operators.
  • Prevent scale-out events from repeating the same boot-time failure.
Solution Using Startup command

A review showed that the startup script installed dependencies from external URLs before launching the JAR, so every restart depended on network availability. The team moved dependency packaging into the build pipeline and changed the startup command to a short, deterministic java -jar command with documented memory and profile settings. App settings supplied environment-specific values, and the command no longer contained secrets or package-install logic. Operators used Azure CLI to compare the previous and new appCommandLine values, restart the staging slot, and watch log stream output for JVM initialization and port binding before production rollout.

Results & Business Impact
  • Average restart time dropped from 11 minutes to 92 seconds during maintenance tests.
  • Three monthly outages tied to blocked external downloads were eliminated.
  • Scale-out validation passed on six instances without repeating the old script failure.
  • Operator escalation time fell by 35 minutes because JVM parameters were documented and visible.
Key Takeaway for Glossary Readers

The best startup command is usually simple and deterministic; build pipelines should prepare artifacts before the runtime has to boot.

Case study 03

Civic grants portal restores predictable Node startup

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A nonprofit grants portal used a Node application on Linux App Service, but emergency portal edits left production and staging with different startup commands.

Business/Technical Objectives
  • Remove hidden slot drift before the annual grant application deadline.
  • Standardize the Node process manager and startup arguments.
  • Create a safe rollback command for future releases.
  • Prove to program staff that the portal could survive restarts.
Solution Using Startup command

The platform engineer exported App Service configuration for both slots and found that production started a legacy server.js file while staging used a newer PM2 configuration. The team chose the PM2 startup command, added it to infrastructure automation, and removed the hand-edited portal value. They restarted staging repeatedly, tailed logs, and verified application health probes, authentication redirects, and form submission paths. After the swap, Azure CLI checks confirmed both slots carried the same appCommandLine pattern. The previous command was saved as a rollback variable but was never needed during the application window.

Results & Business Impact
  • Slot configuration drift dropped from seven startup-related differences to zero before launch.
  • Restart tests completed successfully 20 times without a single process mismatch.
  • Deadline-week support calls about unavailable forms fell by 81 percent from the prior year.
  • The release checklist shrank from 24 manual portal checks to six scripted validations.
Key Takeaway for Glossary Readers

Startup commands should be managed like release-critical configuration, especially when slots and emergency edits can hide dangerous drift.

Why use Azure CLI for this?

After ten years of Azure engineering, I use Azure CLI for startup command work because startup failures are easiest to solve when configuration, logs, and restarts are captured together. CLI lets me show appCommandLine, linuxFxVersion, app settings, and recent log output without hunting through portal blades. It also gives deployment pipelines a safe way to set the same startup command in dev, test, and production. When a command change is risky, I want exact before-and-after JSON, a rollback command, and log tailing in the same terminal. That discipline prevents guesswork during a production boot failure. Record it every time.

CLI use cases

  • Show the current startup command, runtime stack, and configuration before changing a production Linux web app.
  • Set or clear the startup-file value from a pipeline so dev, test, and production use repeatable boot behavior.
  • Tail App Service logs immediately after restart to confirm the command launched the expected process successfully.
  • Compare production and staging slot configuration to catch startup command drift before a slot swap.
  • Restart the app after a reviewed command change and capture JSON evidence for rollback and incident notes.

Before you run CLI

  • Confirm subscription, resource group, app name, slot name, runtime stack, and whether the target is a Linux code app or custom container.
  • Get owner approval before changing startup behavior because one bad command can take every instance of the app offline.
  • Check whether the command contains secrets, downloads remote scripts, changes permissions, or performs work that belongs in the build pipeline.
  • Validate file paths, executable permissions, working directory, expected port binding, environment variables, and package availability before restart.
  • Use JSON output for evidence and keep the previous command available as an immediate rollback value.

What output tells you

  • appCommandLine shows the configured startup command that App Service will attempt to run when the Linux container starts.
  • linuxFxVersion identifies the runtime stack, which helps confirm whether the command matches Python, Node, Java, .NET, PHP, Ruby, or a container image.
  • App settings output reveals variables the command may depend on, including ports, environment names, feature flags, and Key Vault references.
  • Log stream output shows whether the command found its script, started the process, bound correctly, or exited with an error.
  • Restart and deployment status fields indicate whether the platform accepted the change, but logs prove whether the application actually became healthy.

Mapped Azure CLI commands

Startup command CLI operations

direct
az webapp config show --resource-group <resource-group> --name <app-name> --query "{linuxFxVersion:linuxFxVersion,appCommandLine:appCommandLine}" --output json
az webapp configdiscoverApp platform
az webapp config set --resource-group <resource-group> --name <app-name> --startup-file "<startup-command>" --output json
az webapp configconfigureApp platform
az webapp config appsettings list --resource-group <resource-group> --name <app-name> --output table
az webapp config appsettingsdiscoverWeb
az webapp log tail --resource-group <resource-group> --name <app-name>
az webapp logdiscoverWeb
az webapp restart --resource-group <resource-group> --name <app-name>
az webappoperateApp platform

Architecture context

Architecturally, a startup command is the bridge between App Service platform hosting and the application runtime contract. I review it whenever a Linux app uses a framework that does not start automatically, needs a process manager, or wraps startup in a shell script. The command must align with deployment layout, language stack, environment variables, working directory, port expectations, and logging behavior. For production, I treat it as code-owned configuration, not an operator tweak. It belongs in deployment templates or pipelines, with rollback notes and app-owner approval, because a one-line command can make every scaled-out instance fail at the same time.

Security

Security impact is direct when the startup command contains secrets, downloads packages, runs shell logic, or changes filesystem permissions. Never embed passwords, tokens, connection strings, or tenant-specific secrets in the command. Use app settings, managed identity, Key Vault references, or deployment artifacts instead. Operators should review who can modify site configuration, because changing startup behavior can execute arbitrary commands under the app context. Avoid curling untrusted scripts at boot, weakening permissions, or printing secrets to logs. Security review should also check whether the command starts a debug server, exposes management endpoints, or bypasses expected runtime hardening. Review command ownership quarterly.

Cost

Cost impact is indirect but real. A bad startup command can keep paid App Service instances running while serving no traffic, trigger repeated restarts, increase support time, or force emergency scale-up that does not fix the underlying issue. Commands that install dependencies on every boot also slow recovery and consume build or runtime resources. In Premium or isolated environments, wasted worker time is expensive. Operators should avoid using startup logic as a substitute for proper build steps. The cheapest command is usually simple, deterministic, and backed by pipeline artifacts, not a boot-time installation script that fails under pressure. Measure restart waste explicitly.

Reliability

Reliability impact is direct because the command determines whether the app process starts after deployment, restart, scale-out, platform update, or instance recovery. A fragile command can create intermittent outages when a package path changes, a script lacks execute permission, or a dependency is installed at runtime and fails. Operators should test startup in staging, verify logs, and use deployment slots when command changes are risky. The command should be deterministic and fast enough for platform health checks. If every instance uses the same broken command, scaling cannot help; the failure simply repeats across more workers. Practice rollback before incidents. now.

Performance

Performance impact appears during startup, restart, scale-out, and recovery. A lean command starts the application quickly, binds to the expected interface, and reaches readiness before health checks fail. A heavy command that installs packages, compiles assets, waits on remote services, or performs migrations can stretch cold start time and make scale-out feel broken. Runtime performance can also suffer if the command chooses a weak process manager, wrong worker count, or debug mode. Operators should measure startup duration, log milestones, and application response after restart. The command should launch the app, not perform every operational task. Tune worker settings deliberately. carefully.

Operations

Operators inspect startup commands during failed deployments, cold starts, app restarts, language upgrades, custom container migrations, and support escalations. Practical work includes showing current configuration, comparing slots, tailing logs, validating paths, checking app settings, restarting the site, and documenting rollback commands. Runbooks should identify the owning development team because operators can observe failures but may not know the correct process entry point. For production, changes should move through pipeline-controlled configuration rather than emergency portal edits. Good operations turns startup troubleshooting into a repeatable sequence instead of a midnight guessing game. Keep these checks in the release runbook. under pressure safely.

Common mistakes

  • Treating a successful deployment as proof that the startup command works, even though the app process never started.
  • Embedding secrets or long connection strings directly in the command instead of using app settings or Key Vault references.
  • Running package installation, database migrations, or asset builds at startup, which slows recovery and makes failures harder to diagnose.
  • Using a command that binds only to localhost or the wrong port, causing health checks and user traffic to fail.
  • Editing production startup configuration by hand without recording the previous value, deployment slot differences, or rollback command.