Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart: Deploy Your First App

This guide takes you from an invitation email to a running app: sign in, create a Project and an Environment, create a Web Application, connect it to your GitHub or GitLab repository, and open it in a browser. From then on, every push to your branch deploys automatically.

You’ll need your app’s code in a GitHub or GitLab repository. The platform is invitation-only — there is no self-serve signup. If you do not have an invitation yet, ask an Organization owner or admin to send you one.

Accept your invitation and sign in

Open the email you received. If you are new to the platform, that email asks you to set a password; once that is done you land on the invitation accept page. If you already have an account, the email links straight to the accept page. Sign in and accept the invitation.

After signing in you have your own personal Organization, plus membership in any Organization you were invited to. The examples below use an Organization named acme.

Create a Project

In the dashboard, open your Organization’s projects and create a new Project. The Create Project form asks for:

  • Project Name — a display name, for example “Shop”.
  • URL Slug — lowercase letters, numbers, and hyphens. It is generated from the name and appears in dashboard URLs (/orgs/acme/projects/shop).
  • Description — optional.

You can also create projects from the CLI with paas projects create — see the Command Reference.

Create an Environment

Inside the Project, create an Environment named production:

  • Environment Name — lowercase letters, numbers, and hyphens only.
  • Environment Type — Development, Staging, or Production.
  • Git Branch — leave the default, main. The branch your app deploys from is the one you pick when you link your repository below.
  • Automatic deployment — leave it on, so every push deploys automatically.

You can leave Protected Environment off for now.

Create the Web Application

Open the production Environment and create a Resource. Pick the Web Application type (an HTTP service with a web endpoint), then fill in:

  • Name — web. Lowercase letters, numbers, and hyphens; it is used in URLs and DNS.
  • Framework — Ruby on Rails, Node.js, Python, Go, Rust, or Static Files (see Supported Frameworks for the files each one needs).
  • Port and Health Check Path — the port defaults to 3000; the dashboard suggests /health for dynamic apps and / for Static Files. Your app should listen on the port in the PORT environment variable, and answer the health check path with 200 OK — if it doesn’t have a /health page, set the path to one it does answer, such as /. Otherwise the deployment waits for a healthy app that never appears.
  • Replicas, CPU Limit, Memory Limit — the defaults are fine to start.

Nothing runs yet: next, tell the platform where your code lives.

Connect GitHub or GitLab

This is done once per Organization, by an Organization owner or admin — if that isn’t you, ask one to do it.

  1. Open Organization Settings → Integrations.
  2. Click Connect GitHub or Connect GitLab.
    • GitHub asks you to install the d2o PaaS app on your account or organization, and to choose which repositories it can see. Include your app’s repository. Only an owner of that GitHub account or organization can install it.
    • GitLab asks you to authorize d2o.
  3. You’re returned to Integrations, and the connection shows as Active.

Using your own GitLab server? See Self-managed GitLab.

  1. Open the web app and go to its Settings.
  2. In the Deploy from GitHub/GitLab section, pick the Connection, search for your Repository, and pick the Branch to deploy — usually main.
  3. Click Save. The section now says “Deploys from GitHub acme/shop@main” (or GitLab).
  4. Wait for CI is enabled by default, so a commit waits for its tests. If the repository has no checks, d2o waits 10 minutes before proceeding.
  5. Click Deploy latest to deploy the branch as it is now.

From now on, every push to that branch deploys the app automatically — just git push to GitHub or GitLab as you normally would.

Several apps from one repository (say a web server and a background worker)? Create them with Repository → The environment’s shared repository, and link the Environment instead of each app — see Link a repo to an Environment or app.

Watch the build and deployment

Each deployment builds your code with buildpacks for the framework you chose, then rolls it out. You can follow it in three places:

  • In the dashboard — the app’s Deployments tab lists each deployment; open one to see its stages, the live build log and, if it fails, the reason.

  • On GitHub or GitLab — the commit gets a d2o: production check that moves from Building to Rolling out to Live, or says why it didn’t deploy. It links to the deployment.

  • From the CLI (optional — see Installing the CLI) — one command follows the whole deployment until the new version is live, or tells you why it isn’t:

    paas watch -o acme -p shop -e production -a web

If the deployment fails, its page shows the reason — most first-deployment problems are an app that doesn’t listen on $PORT or doesn’t answer its health check path. See Troubleshooting & FAQ.

Open your app

When the deployment succeeds, open the app’s public URL shown in the dashboard. Your first app is live.

Need a runnable application? Follow a language tutorial to create a hello app, then add a database, worker, and storage using the dashboard or CLI.

Next steps