# Web Apps

Web Server Management / Web Apps

Web Apps is the recommended feature for deploying new web applications on cPanel. It deploys container-based applications and supersedes the older Application Manager (PassengerApps) feature. Prefer Web Apps for all new deployments; use Application Manager only to manage existing Passenger applications.

## Update an application's configuration.

 - [GET /WebApp/configure](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_configure.md): This function updates an application's configuration. Only the
parameters you pass change; omitted parameters keep their current
values.

Important:

  The env parameter uses replace-all semantics — the value you
  pass becomes the application's complete set of environment
  variables. To change one variable, read the current set first and
  resubmit it with your change applied.

## Delete an application.

 - [GET /WebApp/delete](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_delete.md): This function deletes an application: it stops the application's
running process and removes its container, moves the application's
directory aside to a .bak sibling (kept for verification or rollback
rather than deleted), and removes the application from the account's
registry.

Deleting an application cannot be undone, so it requires an explicit
confirmation: verify must be 1 to proceed. A verify of 0 makes
no changes and returns a confirmation-required error.

The application's domain is not affected; subdomains are managed
independently.

On failure, the metadata.error_category field carries a
machine-readable failure category.

Important:

  The verify parameter is required and has no default. You must
  set it to 1 to confirm this irreversible operation.

## Deploy an application.

 - [GET /WebApp/deploy](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_deploy.md): Web Apps is the recommended feature for deploying new web applications; prefer it over the older Application Manager (PassengerApps) feature for new deployments.

This function deploys an application: it installs dependencies, runs
the build, and promotes the result to the live environment.

Note:

  This function starts an asynchronous task and returns immediately.
  Stream the returned sse_url for live progress, or poll the task.
  While the task runs, the application's status is deploying. When
  the task finishes the status transitions to running on success or
  errored on failure. Use WebApp::list to read the current status
  and inspect last_deploy for the outcome and any failure category.

Important:

  This function is idempotent. If you call it while a deploy for the
  same application is already running, it returns the in-flight
  task's identifiers instead of starting a new deploy.

If this call fails before the task is dispatched (for example, when
the application does not exist), metadata.error_category carries a
machine-readable failure category. Build and runtime failures occur
inside the background task and are recorded asynchronously in
last_deploy.error_category, which is accessible via WebApp::list.

## Fetch an application's runtime or build logs.

 - [GET /WebApp/fetch_logs](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_fetch_logs.md): This function fetches an application's runtime or build logs. It
returns the most recent lines from the log the container persists on
disk. It returns a static tail; live streaming of new lines is not yet
available.

## List available application runtimes and limits.

 - [GET /WebApp/get_available](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_get_available.md): This function returns the account's application capacity: the
account-wide application pool, and — per App Type enabled on the
server — the runtime's supported version tags and their package
managers and the account's current per-type usage.

Call this function first to determine what kinds of applications the
account can deploy.

## Report whether the Web Apps feature is available.

 - [GET /WebApp/has_feature](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_has_feature.md): This function reports whether the Web Apps feature is available
to the current account, so an interface can decide whether to surface
it.

It is available when the server has the feature enabled, the
account's package feature list includes the feature, and the account is
allowed at least one application.

## List the account's web applications.

 - [GET /WebApp/list](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_list.md): This function lists the account's web applications and their current
state.

## Redeploy an application, pulling source updates first.

 - [GET /WebApp/redeploy](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_redeploy.md): This function redeploys an already-deployed application. For
Git-sourced applications, it pulls the latest changes from the
configured branch before deploying. Otherwise it behaves exactly
like WebApp::deploy.

Note:

  This function starts an asynchronous task and returns immediately.
  Stream the returned sse_url for live progress, or poll the task.
  While the task runs, the application's status is deploying. When
  the task finishes the status transitions to running on success or
  errored on failure. Use WebApp::list to read the current status
  and inspect last_deploy for the outcome and any failure category.

Important:

  This function is idempotent. If you call it while a deploy for the
  same application is already running, it returns the in-flight
  task's identifiers instead of starting a new deploy.

If this call fails before the task is dispatched (for example, when
the application does not exist), metadata.error_category carries a
machine-readable failure category. Build and runtime failures occur
inside the background task and are recorded asynchronously in
last_deploy.error_category, which is accessible via WebApp::list.

## Restart an application's server process.

 - [GET /WebApp/restart](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_restart.md): This function restarts an application's server process.

Important:

  This function only applies to applications in the server
  category. Calling it on a static application fails with the
  invalid_category error category.

## Set an application's run mode.

 - [GET /WebApp/set_mode](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_set_mode.md): This function sets an application's run mode and restarts the
application so the new mode takes effect.

Important:

  This function only applies to applications in the server
  category. Calling it on a static application fails with the
  invalid_category error category.

## Register a new web application.

 - [GET /WebApp/stage](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_stage.md): Web Apps is the recommended feature for deploying new web applications, and this function is the entry point. Prefer it over the older Application Manager (PassengerApps) feature for new deployments.

This function registers a new web application from an uploaded
archive or a Git repository. Once the source is placed on disk, it
runs a preflight that inspects the source and detects the
application's framework and category, records them on the
application, and derives suggested configuration defaults. The
detection confidence and the suggested defaults are returned so
you can pass them to WebApp::configure. The application is
registered but not deployed — call WebApp::configure (optional)
and then WebApp::deploy to bring it live.

The preflight never fails the stage: a source with no recognizable
markers is registered with a none confidence and generic defaults.

Registering a name that is still staged (not yet deployed)
overwrites it: the previously staged application and its source are
replaced, and the response warnings array reports that the old
files were overwritten.

Registering a name that is already deployed leaves the running
application untouched — its container and live routing are never
disturbed — but the new application cannot reuse the deployed
application's display name, or WebApp::list and bare-name
addressing could not tell the two apart. So it is registered under
the next free -N (for example, my-app-2), and the response
warnings array reports the assigned name. Read the assigned name
from the response data.name: you must pass that name (not the one
you requested) to WebApp::configure and WebApp::deploy to act on
this application, which stands up as its own separate container.

On failure, the metadata.error_category field carries a
machine-readable failure category.

## Start an application's server process.

 - [GET /WebApp/start](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_start.md): This function starts an application's server process.

Important:

  This function only applies to applications in the server
  category. Calling it on a static application fails with the
  invalid_category error category.

## Stop an application's server process.

 - [GET /WebApp/stop](https://api.docs.cpanel.net/specifications/cpanel.openapi/web-apps/webapp_stop.md): This function stops an application's server process.

Important:

  This function only applies to applications in the server
  category. Calling it on a static application fails with the
  invalid_category error category.