Creating a Web Application
A Web Application is an HTTP service with a web endpoint. It lives inside an Environment, which lives inside a Project, which lives inside an Organization — see Organizations, Projects & Environments if that hierarchy is new to you.
You can create a Web Application in the dashboard or with the paas CLI. Both
paths create the same thing: an app record plus a platform-hosted git
repository. Pushing code to that repository is what triggers a build and
deploy — you don’t upload code at create time.
Before you begin
- You need an existing Environment to create the app in.
- You need permission to manage web applications in the project — without it, the Create button is disabled. See Access Control.
In the dashboard
Open your Organization, then the Project and Environment, and choose Add Resource. Select the Web Application resource type, then fill in the form:
Name — up to 50 lowercase letters, numbers, and hyphens, starting with a
letter and ending with a letter or number (for example web). The name is used in URLs and DNS, so
pick something short and stable.
Framework — the language or stack your code is written in: Ruby on Rails, Node.js, Python, Go, Rust, or Static Files. This selects the buildpack that turns your code into a runnable app, and it is required: an app without a supported framework cannot build, and the platform rejects the create. All six frameworks have hosted builders; see Supported Frameworks for detection files and runtime versions for availability.
Deploy with Git push — the platform hosts the app’s repository for you.
After creating the app you get a remote to push to; pushing to the main
branch triggers a build and deployment. Building from an arbitrary git URL isn’t
supported; to deploy from GitHub or GitLab,
link the repository after creating the app.
See Deploying with Git Push.
Repository — Its own repository (the default) or The environment’s shared repository, with a Directory for where the app’s code lives in it — see One remote for several apps.
Process type — select a process declared by your build, such as web or
worker, or leave blank for the default. This is a process name, not a shell
command. See Procfile.
Port (default 3000) — the port your app listens on for HTTP traffic.
Set this to whatever your server binds to.
Health Check Path (dashboard default /health, or / for Static Files) — a path on your app the platform
requests to confirm an instance is up. Your app should answer it with a
success response. Or set it in d2o-paas.yaml in your repository instead —
see d2o-paas.yaml Reference.
Replicas (default 1) — how many instances of your app run at once. The
form accepts 1 through 10 at creation (scale to 0 later to stop the app);
your plan’s limits also apply (see
Plans, Limits & Usage). You can change this later
or enable autoscaling — see Scaling & Autoscaling.
CPU Limit (default 500m) and Memory Limit (default 512Mi) — the
most CPU and memory each instance may use. CPU is written in millicores
(500m is half a core, 1000m a full core); memory in Mi/Gi (512Mi,
1Gi).
Max egress per replica (Mbps) — an optional per-instance limit on outbound network bandwidth; it counts against your plan’s network capacity. Leave it blank for no limit.
Click Create Resource. The app appears in the environment’s resource list, and stays in a provisioning state until you push code.
With the CLI
paas apps create web \
-o acme -p shop -e production \
--framework nodejs \
--port 3000 --health-check-path /health
Created app web
Only the name is a positional argument; everything else is a flag. Always pass
--framework (rails, nodejs, python, go, rust, or static) —
creates without a supported framework are rejected, and a misspelling such as
--framework node is rejected with a message naming the field and the
accepted values. The other flags mirror the dashboard form:
--port,--health-check-path--replicas(defaults to 1 when omitted),--cpu,--memory--autoscaling-min,--autoscaling-max,--autoscaling-cpu-target— passing any of these creates the app with autoscaling enabled (see Scaling & Autoscaling)--shared-source,--source-dir— build from the Environment’s shared repository (see below)--process(alias--start-command),--release-command,--auto-rollback true|false— see Deployments, Health Checks & Rollback--singleton true— see Singleton apps--worker— creates a Background Worker instead--json— print the raw API response
--port defaults to 3000, the same as the dashboard. The platform passes
the port to your app as the PORT environment variable, so a server that
binds to $PORT needs no flag.
For non-static apps, pass --health-check-path /health explicitly: the CLI
does not choose a path. Static apps default to / at creation. See the
health-check defaults and rollout rules.
--git-repo, --git-branch, and --source-mode also appear in the help, but
building from an arbitrary git URL isn’t supported, and the API rejects
external-source creates. To deploy from GitHub or GitLab,
link the repository after creating the app.
Deploy your code
Once the app exists, point a git remote at its hosted repository and push:
paas git remote -o acme -p shop -e production -a web
git push paas main
paas git remote prints and configures the paas remote for the app. The
push to main triggers the build and deployment. Full walkthrough:
Deploying with Git Push.
Several apps from one repository? Create them with --shared-source and use the
Environment’s remote instead — see
One remote for several apps.