Register a new web application.
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 <name>-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.
Query parameters
The requested application name (slug). If a deployed application already uses it, the application is registered under the next free <name>-N instead; read the assigned name from the response data.name and use it for WebApp::configure and WebApp::deploy.
The application's source location. This is required for every source type:
- When source_type is zip — the path, relative to the user's home directory, of a previously uploaded source archive (for example, uploads/my-app.zip).
- When source_type is git — the Git repository URL to clone (for example, https://github.com/example/my-app.git).
Security note: This source is built and run on the server. Only use ZIP archives or Git repositories from a trusted origin.
Do not embed credentials (such as a username and password or an access token) in the Git URL — they are stored in plaintext. To clone a private repository, use a Git SSH URL that you have an SSH key configured for.
The application's source type.
- zip — An archive previously uploaded with Fileman::upload_files.
- git — A Git repository.
The application root, relative to the top of the cloned repository or extracted archive, for a source whose application does not live at the top level (for example, packages/web in a monorepo). The preflight inspects this directory to detect the framework.
This parameter must be a relative path inside the source. When omitted, it defaults to the source root, unless the manifest is found in a single top-level subdirectory (as in a repository zip), in which case that subdirectory is used automatically.
The Git branch to clone. Only meaningful when source_type is git.
This parameter defaults to the repository's default branch.
The run mode for server category applications.
This parameter defaults to production.
The runtime that backs the application.
This parameter defaults to the system default runtime (nodejs).
Response
HTTP Request was successful.
Example response
{
"apiversion": 3,
"func": "stage",
"module": "WebApp",
"result": {
"data": {
"category": "server",
"container_name": "my-app.bob.01",
"confidence": "high",
"defaults": {
"build_command": "npm run build",
"output_dir": ".next",
"runtime_tag": "22",
"startup_command": "npm run start"
},
"db": {
"env_keys": [
"DB_NAME",
"DB_HOST",
"DB_PORT"
],
"host": "localhost",
"name": "example_my_app",
"port": 3306
},
"domain": "my-app.example.com",
"env": {
"NODE_ENV": "production"
},
"last_deploy": {
"deploy_id": "dp-20260612-0001",
"result": "success",
"timestamp": "2026-06-12T14:03:22.000Z"
},
"mode": "production",
"name": "my-app",
"package_manager": "npm",
"runtime": "nodejs",
"runtime_tag": "22",
"source": {
"branch": "main",
"type": "git",
"url": "https://github.com/example/my-app.git"
},
"staged": true,
"status": "created",
"url": "https://my-app.example.com"
},
"status": 1
}
}