Welcome to d2o PaaS

Deploy web applications, background workers, databases, and object storage from one platform. Start with the task you want to complete; the sidebar contains the full documentation.

Deploy your first app

Follow the Quickstart, or build an example app in Node.js, Rails, Python, Go, Rust, or static HTML. The tutorials include runnable downloads and both dashboard and CLI instructions. Install the CLI if you prefer the terminal.

Bring an existing application

Check supported frameworks, choose a runtime version, and review Designing Apps for d2o. Deploy with Git push or connect GitHub/GitLab. There are focused guides for Go, static sites, and background workers.

Connect data and configuration

Create and attach a database, store files in object storage, and manage environment variables and secrets. Learn how Organizations, Projects, and Environments keep resources organized and how access control works.

Prepare for production

Use Take an Example to Production as a bridge from the tutorials, then complete the production checklist. Review promotion and rollback, scaling, custom domains, and durability and recovery.

Diagnose a problem

Start with Troubleshooting & FAQ, then inspect deployments, logs, and metrics. Check limits and usage when an operation is refused.

Look up a command or setting

Use the CLI command reference, d2o-paas.yaml reference, Procfile reference, and verified runtime catalog. For integrations, see API Access & Automation or MCP.

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.

Link your repository

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

• Designing Apps for d2o — configuration, storage, and process lifecycle

• Best Practices for Production Apps — what to set up before real users arrive

• Deploy from GitHub or GitLab — Wait for CI, direct pushes, Deploy latest and more

• Pipelines, Promotion & Rollback — add staging and production stages

• Environment Variables — configure your app

• Installing the CLI — manage everything from your terminal

• Deploying with Git Push — push straight to d2o instead of GitHub or GitLab

• Deploying from CI — push from a CI pipeline with a deployment token

Deploying with Git Push

Every Web Application or Background Worker gets a source repository hosted on the platform. You push your code to it, the platform builds an image from your source with buildpacks, and the new version is deployed to the app’s Environment. This works the same whether your code is public or private. Pushing to this repository is one way in; you can also link a GitHub or GitLab branch so the platform deploys from it (see Deploy from GitHub or GitLab).

This guide assumes you already have an app. If you don’t, see Creating a Web Application first. Pushing requires deploy access to the app’s Project.

The examples use the paas CLI with org acme, project shop, environment production, and an app named web. Add -e production to the commands (the environment has no configurable default; it is only inferred from an existing paas or d2o remote), plus -o acme -p shop if you haven’t set defaults (paas orgs set-default, paas projects set-default). See Installing the CLI.

Upload an SSH key

Pushing over SSH authenticates with an SSH public key attached to your account. A key lets you push to any app repository you have deploy access to.

In the dashboard: open Account Settings, then under SSH Keys click Add Key. Give the key a name (for example laptop), paste your public key (the contents of a .pub file, e.g. ssh-ed25519 AAAA... user@host), and save. The list shows each key’s fingerprint; deleting a key immediately stops it from pushing.

With the CLI:

paas keys add

With no argument, this uploads ~/.ssh/id_ed25519.pub (falling back to id_ecdsa.pub, then id_rsa.pub). To upload a specific key:

paas keys add ~/.ssh/other_key.pub

paas keys list shows your keys with their IDs and fingerprints; paas keys remove <key-id> deletes one.

Add the paas remote

From inside your app’s local git repository, run:

paas git remote -a web

This looks up the app’s platform-hosted repository, adds it to your local repo as a remote named paas (or updates the remote if it already exists), and prints the result:

$ paas git remote -a web
Set remote paas → ssh://git@<git-host>:<port>/sources/acme/shop/production/web.git

The exact host and port are filled in for your installation. To print the URL without touching your git configuration, add --print. Running the command outside a git repository also just prints the URL.

-a matters. Bare paas git remote — no -a — sets up the Environment’s shared remote instead, named d2o (see One remote for several apps below). For a single app’s own remote, always pass -a <app>.

If an older checkout already has a d2o remote left over from before the shared remote existed — pointing at this app’s own repository, not an Environment — paas git remote refuses to touch it rather than silently repointing it to the Environment (a push there would then build nothing). This applies both to the bare command and to -a <shared-app> for an app on the shared source. Fix it first, then re-run whichever command you meant:

git remote rename d2o paas

If paas is already taken too (both remotes present in the same checkout), rename isn’t possible — remove d2o instead, since the per-app remote it pointed at is already available as paas:

git remote remove d2o

Push

git push paas main

The platform builds the main branch, so push to main. If your local branch has a different name, push it as main:

git push paas HEAD:main

The push returns within seconds, printing a deployment number, the commit, a link to follow it live, and the paas watch command to run:

remote: Deploy #42 started for abc1234 → web
remote:   Follow live: https://d2o.io/orgs/acme/projects/shop/envs/production/deploys/42
remote:   Or run:      paas watch --deploy 42

It doesn’t wait for the build — open the link or run the printed command to follow what happens next.

When a push is refused

A push is refused, and nothing is built, in two cases:

• The Environment is promote-only. It runs versions promoted from another Environment, so the push is refused with environment production is promote-only; push to `staging` and promote. Push to the named Environment instead and promote from there. The dashboard shows no push command for a promote-only Environment.
• The app or Environment deploys from a linked GitHub or GitLab branch and direct pushes are off. The message says where to push instead: This environment deploys from GitHub acme/shop@main. Push there instead, or allow direct pushes in the environment's settings. The dashboard hides the push command and says Direct pushes are off. See Deploy from GitHub or GitLab.

What happens next

1. Build. The platform builds a runnable version from the pushed source with buildpacks, using the language/framework you chose when creating the app.
2. Deploy. When the Environment has Auto Deploy enabled (the default), a successful build rolls out automatically, and only takes traffic once it passes its health check. With Auto Deploy off, the build waits until you deploy it yourself with paas deploy -a web. See Deploys, Health Checks & Rollback for the full stage-by-stage picture, including what happens when a new version never becomes healthy.

Without --deploy, paas watch follows the newest deploy for the app:

paas watch -a web

Or check on it yourself:

paas releases          # recent deployments for the environment
paas status -a web     # the app's sync, health and instances
paas logs -a web --tail

While the image is still building, the log stream tells you so instead of streaming; once the new instances are running, logs flow normally. In the dashboard, the app’s Deployments view shows the same history and status.

HTTPS remote alternative

If you can’t use SSH (for example, from a machine with no SSH key set up), push over HTTPS with a URL that embeds an access token scoped to this app’s repository. The token expires after 30 days, and until then it grants push access, so treat the URL like a password.

In the dashboard: on the app’s Deployments tab, the Deploy via Git Push panel has a Show push command button. It generates ready-to-copy commands:

git remote add paas https://x-access-token:<token>@<git-host>/sources/acme/shop/production/web.git
git push paas HEAD:main

Use Regenerate token to mint a fresh URL for your next push. Don’t share the URL or commit it anywhere — it carries write access to the app’s source repository.

With the CLI:

paas git remote -a web --https

This configures the paas remote over HTTPS instead of SSH and stores a freshly minted push token with git’s credential helper, so the token never appears in .git/config or git remote -v. It needs a credential helper (your OS keychain, or git config --global credential.helper store) and stops with an error when none is configured. You can run it again at any time for a fresh token. When a push fails with fatal: Authentication failed after the token’s 30 days are up, run the same command again.

For CI pipelines, create a deploy token for the app’s remote (paas deploy-tokens create ci -a web), or for the Environment’s remote when your apps use the shared repository — see Deploying from CI.

One remote for several apps

Apps in one Environment can share one repository: the Environment’s own, at sources/<org>/<project>/<environment>.git. One push then rebuilds every app that uses it, and apps whose code is the same — same directory, same framework — share a single build, so the image is built once and deployed to all of them.

Create each app with --shared-source, and give each app its process with --process when one build produces several (for example web and worker from a Procfile, or two binaries of one Cargo project):

paas apps create admin --shared-source --framework rust --port 3000 --process admin -e production
paas apps create bot --worker --shared-source --framework rust --process bot -e production

--process is only needed when the app’s name doesn’t already match a line in the Procfile — a newly created app named worker with a worker: Procfile line picks it up automatically, with nothing to set. Name matching only applies to apps created from now on, though: an app that already existed keeps running its current process regardless of its name, until you clear its Process setting (paas apps update <app> --process ""). See Procfile for the full order the platform tries. A file’s own d2o-paas.yaml can set process: too, for apps that keep their settings in the repository — see d2o-paas.yaml Reference.

If an app’s code lives in a directory of the repository, add --source-dir <DIR>. Then add the Environment’s remote — without -a — and push once:

paas git remote -e production
git push d2o main

paas git remote without -a adds the Environment’s remote as d2o; an app’s own remote keeps the name paas. In the dashboard, the Environment’s Deployments tab has a Git remote panel with the same commands.

Inside the shared repository the CLI works out the app from your working directory: the app whose directory contains it, or the only app that builds from the repository root. When several apps build from the root, pass -a. paas watch without -a follows every app of the push until each runs the new build.

To move an existing app to the shared repository:

paas apps update admin --shared-source -e production

The app keeps running its current version until the first shared build succeeds. Its own repository is kept until you delete the app, but it no longer accepts pushes; switch back with paas apps update admin --own-source.

Switching back rebuilds immediately from the app’s own repository’s last pushed commit — whatever that was before you moved it to the shared repository, which can be old or stale. The own repository starts accepting pushes again the moment you switch back, so push the code you actually want right away rather than assuming the version that comes up is current.

Next steps

• How Builds & Deployments Work — what happens between push and running app
• Deployments, Health Checks & Rollback — stages, health checks, and rollback
• Logs — snapshots and live streaming
• Account, SSH Keys & API Tokens — managing your keys and credentials

Installing the CLI

The paas command-line tool lets you manage Organizations, Projects, Environments, and Resources from your terminal — everything from creating an app to streaming its logs. This page gets it installed and logged in.

Most of what the CLI does is also available in the dashboard, so the CLI is optional — though a few things, such as printing a bucket’s S3 credentials, are currently CLI-only. It’s also the fastest way to work once you deploy regularly.

Prerequisites

• A platform account. The platform is invitation-only, so you should already have accepted an invitation and be able to sign in to the dashboard. If not, see Inviting People.
• Nothing else. The CLI is a single prebuilt binary with no runtime dependencies — you do not need a Rust toolchain unless you choose to build it yourself.

Install

On macOS and Linux, the install script picks the right build for your operating system and CPU, verifies its SHA-256 checksum, and installs the paas binary into ~/.local/bin. If minisign is installed, the script also verifies the release signature and refuses to install on a mismatch; without it, the script says it skipped that check and installs on the checksum alone.

curl -fsSL https://dl.d2o.io/install.sh | sh

If ~/.local/bin is not on your PATH, the script says so and prints the line to add to your shell profile. Three environment variables change what it does:

For example, to pin a version and install into ~/bin:

curl -fsSL https://dl.d2o.io/install.sh | PAAS_VERSION=0.12.0 PAAS_INSTALL_DIR="$HOME/bin" sh

Verify it:

paas --version

The language tutorials and paas apps attach, paas apps attachments, and paas apps detach require 0.9.0 or later. paas deploy-tokens, paas connections and paas links need version 0.8.0 or later; paas deploys and paas manifest check need 0.7.0; paas attach and paas detach need 0.4.0. Run paas --version to check; to upgrade, run the install script again.

Install manually

Releases are published under https://dl.d2o.io/paas/v<VERSION>/. Check the current version:

curl -fsS https://dl.d2o.io/paas/latest.json

The examples below read that version, so they install the latest release. To pin a release, set VERSION (or $v on Windows) yourself.

macOS: select the archive for your CPU (arm64 below; use amd64 for Intel).

VERSION=$(curl -fsS https://dl.d2o.io/paas/latest.json | sed -n 's/.*"version" *: *"\([^"]*\)".*/\1/p')
BASE="https://dl.d2o.io/paas/v$VERSION"
ARCHIVE=paas-darwin-arm64.tar.gz
curl -fsSLO "$BASE/$ARCHIVE" && \
curl -fsSLO "$BASE/SHA256SUMS" && \
shasum -a 256 --ignore-missing -c SHA256SUMS && \
tar xzf "$ARCHIVE" && \
sudo install -d /usr/local/bin && \
sudo install -m 0755 paas /usr/local/bin/paas

Linux: select amd64 or arm64 for your CPU.

VERSION=$(curl -fsS https://dl.d2o.io/paas/latest.json | sed -n 's/.*"version" *: *"\([^"]*\)".*/\1/p')
BASE="https://dl.d2o.io/paas/v$VERSION"
ARCHIVE=paas-linux-amd64.tar.gz
curl -fsSLO "$BASE/$ARCHIVE" && \
curl -fsSLO "$BASE/SHA256SUMS" && \
sha256sum --ignore-missing -c SHA256SUMS && \
tar xzf "$ARCHIVE" && \
sudo install -m 0755 paas /usr/local/bin/paas

Stop if download or verification fails; do not install an archive with a checksum mismatch. Expect an OK line for the archive you selected. --ignore-missing skips the other platform archives listed in the shared checksum file.

Each archive is flat and holds the binary, a completions/ directory, a README, and — on Linux and macOS — the paas.1 man page.

Optionally, verify the release signature too (the install script does this for you when minisign is installed). SHA256SUMS.minisig is a minisign signature over SHA256SUMS, which in turn covers the archives, so checking it covers everything. Your platform operator publishes the public key:

curl -fsSLO $BASE/SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P 'RWQHV7FbUhxhZzDFI+69HMeEtGMmL1XWAPl3rLKpPs70Bt+2YyC6zgsZ'

Opening https://dl.d2o.io/ in a browser returns an AccessDenied document rather than a file listing. That is expected: the download host serves the objects above, not an index.

Windows

There is no install script for Windows. Download the .zip for your architecture, compare its hash against the matching line in SHA256SUMS, unpack it, and add the folder holding paas.exe to your PATH:

$v    = (Invoke-RestMethod https://dl.d2o.io/paas/latest.json).version
$base = "https://dl.d2o.io/paas/v$v"
$dir  = "$env:LOCALAPPDATA\Programs\paas"

Invoke-WebRequest "$base/paas-windows-amd64.zip" -OutFile paas-windows-amd64.zip
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS

$want = (Select-String 'paas-windows-amd64.zip' SHA256SUMS).Line.Split()[0]
$got  = (Get-FileHash paas-windows-amd64.zip -Algorithm SHA256).Hash
if ($want -ne $got) { throw "checksum mismatch - do not install this file" }

New-Item -ItemType Directory -Force $dir
Expand-Archive paas-windows-amd64.zip -DestinationPath $dir -Force

$old = [Environment]::GetEnvironmentVariable('Path', 'User')
$new = (@($old -split ';') + $dir | Where-Object { $_ }) -join ';'
[Environment]::SetEnvironmentVariable('Path', $new, 'User')

Get-FileHash prints the hash in uppercase and SHA256SUMS records it in lowercase — that is fine, because PowerShell compares strings case-insensitively. Run the PATH block once; it appends, so a second run adds a duplicate entry.

The PATH change only reaches new processes, so open a fresh terminal before running paas --version.

Build from source

If your platform has no published binary, or you want to run an unreleased change, build the CLI from a checkout with a Rust toolchain:

cargo install --path crates/paas

Shell completions

Every archive ships completions in completions/, and the CLI can also print them for bash, elvish, fish, powershell, or zsh. Send the output to your shell’s completion directory:

paas completions zsh

Log in

Logging in happens through your browser, so you never type your password into the terminal:

paas login --host <your-platform-url>

<your-platform-url> is the full dashboard origin, including https:// (hosted d2o: https://dashboard.d2o.io). You need --host the first time; after that the CLI remembers your current host, and a plain paas login targets it.

Step by step:

1. The CLI starts a small listener on your own machine (127.0.0.1) and opens your browser to the platform. It also prints the address, so if no browser opens you can visit it in a browser on the same machine.
2. The platform’s sign-in page appears — sign in with your account. (You are asked to sign in each time you authorize a CLI login, even if you already have an active dashboard session.)
3. A page titled Approve d2o CLI sign-in shows the account you’re signed in as, that a code will be sent to 127.0.0.1:<port> on this machine — that is, back to the CLI — and the name of the API token it will create. Click Approve sign-in. If you didn’t run paas login, close the tab. Approve within 10 minutes of running paas login; after that the page says “CLI login expired or missing — run paas login again”.
4. The browser hands a short-lived, single-use code back to the CLI, which exchanges it for an API token and stores it. The tab then reads Signed in to d2o PaaS (“You can close this tab and return to your terminal”) — you are logged in. If it reads Sign-in didn’t complete instead, your terminal says why.

Each login creates a named API token so you can tell your devices apart later. The default name is cli <hostname>; pick your own with --name:

paas login --host <your-platform-url> --name "work-laptop"

Logging in again replaces the stored token and attempts to revoke the old one. If revocation fails, the old token remains listed under paas auth tokens list; revoke it there.

Remote terminals and CI

The browser must reach the CLI listener on the machine running paas login. Opening the printed URL on your laptop while the CLI runs on a remote server sends the callback to the laptop instead. Use SSH port forwarding for the callback port, or provision an account API token through your secret-management workflow and supply PAAS_API_URL and PAAS_API_TOKEN in the remote environment. See API Access & Automation; a Git deployment token cannot log in to the API.

Verify

paas whoami

This prints the logged-in user for your current host. If instead you see “Not logged in”, run paas login again.

Where the token is stored

The CLI keeps its state in your platform’s configuration directory:

• Linux: ~/.config/paas/config.toml
• macOS: ~/Library/Application Support/paas/config.toml
• Windows: %APPDATA%\paas\config.toml (that is, C:\Users\<you>\AppData\Roaming\paas\config.toml)

This file holds your API token for each host you have logged in to, plus your current host and any default Organization or Project you set (there is no stored default Environment — supply it with -e or run inside a repo with a paas or d2o git remote). The token is stored in plain text. On Linux and macOS the CLI restricts the file to your user; on Windows it inherits whatever your user profile directory allows. Either way, treat the file like a password and do not commit or share it.

For scripts and CI, you can bypass the config file entirely: set PAAS_API_URL to the platform address and PAAS_API_TOKEN to a token. An environment-supplied token is never written to disk.

You can review every token issued to your account with paas auth tokens list and revoke one by ID with paas auth tokens revoke <uuid> — useful if a laptop goes missing. See Account, SSH Keys & API Tokens.

Log out

paas logout

This revokes the current host’s token on the server and removes it from your local config. If your token comes from the PAAS_API_TOKEN environment variable, paas logout refuses — unset the variable instead.

Next steps

• CLI Overview & Authentication — context flags, defaults, and --json output
• Command Reference — every command and flag
• Quickstart: Deploy Your First App — from zero to a running app
• Deploying with Git Push — push your code straight to the platform

Best Practices for Production Apps

This guide is for anyone taking an app from “it works” to “people depend on it”. It explains the setup we recommend, and the habits that keep an app up while you deploy, scale, change its database and recover from mistakes. Each section says what to do, why it matters, and where to read more.

If you’re in a hurry, jump to the checklist at the end.

The recommended setup

   GitHub / GitLab repo (main)
              │  every push
              ▼
   development   builds every push · Wait for CI on · linked to the repo
              │  promote (the same version, never rebuilt)
              ▼
   staging       promote-only
              │  promote
              ▼
   production    promote-only · Protected

In words:

1. Your code lives on GitHub or GitLab, and one Environment (here development) is linked to your main branch. Every push is built and deployed there automatically.
2. Wait for CI is on (CI is your automated tests, such as GitHub Actions or GitLab CI), so d2o waits for the commit’s checks. Configure a test job on the linked branch: if a commit has no checks, d2o deploys after 10 minutes. See Wait for CI.
3. Staging and production never build anything. You promote the exact version that already ran in development, so what you tested is byte-for-byte what you ship.
4. Production is Protected, so it can’t be deleted by accident and promoting into it asks you to confirm.

The rest of this guide explains each piece, and how to build your app so that deployments don’t interrupt anyone.

1. Deploy from GitHub or GitLab

Linking a repository is the recommended way to get code onto d2o:

• Your repo is the source of truth. What’s running is always a commit you can see on GitHub or GitLab, reviewed through your normal pull or merge requests.
• Tests gate deployments. With Wait for CI on, d2o waits for the commit’s checks (GitHub Actions, GitLab CI, or any other CI that reports a status) and refuses to deploy a commit whose checks failed.
• You see the result on the commit. Each push gets a d2o: <environment> check showing Building, Rolling out and then Live — or why it didn’t deploy — with a link to the deployment.
• Keep deployments tied to the linked repository. Leave Allow direct pushes off to refuse pushes straight to d2o’s git remote. Configure branch protection and required reviews on GitHub or GitLab to enforce your review policy.

To set it up:

1. An organization Owner or Admin connects GitHub or GitLab under the organization’s Settings → Integrations.
2. Link your build Environment (or an app — see the next section) to the branch you deploy, usually main.
3. Turn on Wait for CI if your repository runs tests.

If a push ever doesn’t start a deployment, Deploy latest deploys the branch’s current commit on demand.

Can’t use GitHub or GitLab? A CI job can push with a deployment token instead. It’s scoped to one Environment or app and belongs to the organization, not to a person.

See Deploy from GitHub or GitLab for every option.

2. One repository for the Environment, or one per app?

Every Environment can deploy in two ways, and you choose per app:

Rule of thumb: if your apps share code and should always run the same version, use the Environment repository. If they’re separate projects that change at different times, give each its own.

With the Environment repository, each app picks which process to run — web, worker, and so on — from your Procfile or from d2o-paas.yaml. See One remote for several apps.

3. Build once, then promote

Set up a pipeline of Environments in your project:

• One build Environment (for example development). It builds every push and is the one you link to GitHub or GitLab.
• Promote-only Environments after it (staging, production). Switch them to promote-only in the Environment’s Settings → General → Release source before you create apps in them; each app you then create there starts from the same-named app upstream.

Promoting copies the exact build that ran upstream — it never rebuilds — so a version that worked in staging is the same bytes in production. The pipeline board on the project page shows which version is in each stage and promotes with one click, or from the CLI:

paas promote web --from staging --to production -o acme -p shop

Things to know:

• Data and settings aren’t promoted. Each Environment has its own databases, buckets, secrets and environment variables. Set them up in every stage.
• Your app’s release command runs in each Environment you promote into, against that Environment’s database (see migrations).
• Link only the build Environment to GitHub or GitLab. Promote-only Environments can’t be linked, because they never build.
• Turn on Protected for production. Promoting into a protected Environment asks you to type its name, and it can’t be deleted.

See Pipelines, Promotion & Rollback.

4. Build your app the way the platform expects

Follow Designing Apps for d2o: keep durable state outside instances, read runtime configuration from the environment, validate required settings, bind to 0.0.0.0:$PORT, and log to stdout/stderr. Temporary scratch files are fine; they must not be the only copy of data you need to keep.

Version process selection, port, health checks, and release commands in d2o-paas.yaml. The tutorial-to-production guide identifies additional work needed before exposing the example apps to real users.

5. Zero-downtime deployments

When you deploy, d2o replaces your app’s instances one at a time:

1. It starts one new instance next to the old ones.
2. It waits until the new instance passes its health check.
3. Only then does it stop one old instance — and repeats until every instance runs the new version.

Old instances keep serving traffic the whole time. If the new version never becomes healthy, the old ones are never stopped and the platform rolls back for you. A few habits make this work.

Give every web app a health check

Set an HTTP path your app actually serves; give workers an HTTP or command check where practical. See health-check defaults and rollout waiting periods. A missing probe cannot establish that an app is ready to serve, and a singleton still stops before its replacement starts.

Keep the health check fast and shallow

Return a quick, unauthenticated success response once the process has started. Avoid cascading restarts when a shared dependency is briefly unavailable. The health-check guide explains ongoing checks and failure behavior.

Shut down gracefully

Handle SIGTERM, drain in-flight work, and exit within the 30-second window. Workers must safely retry interrupted jobs. Follow the shutdown and retry guidance.

A stuck deployment fails after five minutes

A deployment fails if five minutes pass without another new instance becoming healthy; a slow deployment that keeps making progress is never cut short. A new instance that keeps crashing — three restarts — fails the deployment right away, with the app’s last log lines as the reason. Follow a deployment in the dashboard, or with:

paas watch

See Deployments, Health Checks & Rollback.

6. High availability

Run at least two instances

An app with one instance has one point of failure. When it runs two or more:

• They’re spread across different servers, so if one server fails, the other instances keep serving.
• Platform maintenance moves one instance at a time, so the app stays up.

With a single instance, your app is unavailable while that instance moves — for a few minutes if its server fails. For anything your users depend on, run at least two:

paas scale 2 -o acme -p shop -e production -a web

Autoscale with a floor of two

Autoscaling adds instances when CPU use is high and removes them when it drops. For production, set the minimum to at least 2, so the app stays spread across servers even when traffic is quiet.

The Target CPU % is measured against each instance’s baseline of 0.1 CPU core (or its CPU limit, if that’s lower), not its CPU limit — so the default target of 70 adds instances once they average about 0.07 cores each.

Use singleton only when an app must never run twice

A singleton app runs at most one instance, and every deployment, restart or configuration change stops the old instance before starting the new one. That means a short outage every time — from a few seconds to a minute, depending on how fast your app stops and starts — and several minutes if its server fails.

Use it only when two copies running at once would cause a problem — a chat bot that holds one live session, or a scheduler that must not fire twice. Everything else should run normally.

Give instances enough memory

An instance that uses more memory than its Memory Limit is stopped and restarted (exit code 137). Watch the memory chart on the app’s Metrics and raise the limit before you get close to it. CPU works differently: an instance that uses too much is slowed down, not stopped.

Protect your data

Choose PostgreSQL with high availability when production data needs automatic failover. Attach services instead of copying credentials. Review the durability and recovery matrix for backup coverage, Redis/MongoDB limitations, object-storage tiers, and what deletion removes. Practise recovery; replication does not undo accidental deletion.

7. Change your database safely

Run migrations as a release command

Configure a release command for versioned migrations. It runs with the new code and target Environment’s configuration before rollout, while old code continues serving. A shared build runs it once for the build, not independently for every app. Follow the execution and retry rules in that guide; keep long backfills in background jobs.

Old and new code run at the same time

This is the most important rule for migrations. During a deployment, old and new instances serve traffic side by side for a while. And after a rollback, the old code runs against the database your new migration already changed — a rollback never undoes database changes.

So every migration must keep working with both the version before it and the version after it.

Do:

• Add before you remove. Add a new column or table in one deployment, and remove the old one in a later deployment, once no running code uses it.
• Make new columns optional (nullable, or with a default), so old code that doesn’t know about them can still insert rows.
• Widen before you narrow — loosen a constraint before the code relies on the looser rule; tighten it only after all code obeys it.

Don’t:

• Rename or drop a column in one step. Old instances still running would break immediately.
• Edit a migration that has already run. Write a new one instead.

Example: renaming name to full_name, safely. Remember that the release command runs before the new code starts, so each step must still work with the code from the step before:

1. Deployment 1 — add a nullable full_name column. The code writes both columns and reads name.
2. Deployment 2 — copy the old values into full_name (as a background job, if the table is large). The code still writes both, but now reads full_name.
3. Deployment 3 — make name nullable. The code stops using it.
4. Deployment 4 — drop name.

Make migrations safe to run twice

A release command can occasionally run more than once — for example if its server is restarted mid-run, or when you roll back by hand, which runs the older version’s release command again. Use your framework’s migration tool, which records what has already run, rather than raw SQL scripts.

For PostgreSQL, each deployment whose release command ran shows a data restore point — the time to ask support to restore to if a migration damages data. See Database migrations and rollbacks.

8. Rollbacks

Automatic rollback: keep it on

If a new version doesn’t become healthy, d2o puts the previous version back on its own. This is on by default. Keep it on.

It protects you during the deployment itself. It doesn’t help with:

• A build or release command that fails. Nothing changed yet, so the old version simply keeps running.
• A version that breaks after it went live. Roll back by hand (below).
• Configuration changes. Changing an environment variable or attaching a database restarts your app with the new settings, but it isn’t a tracked deployment: there’s no deployment number and no automatic rollback. A health check still keeps traffic away from instances that never become ready. Try configuration changes in staging first.

Rolling back by hand

How you roll back depends on the Environment:

• In a promote-only Environment (staging, production), click Rollback… in the app’s header and pick an earlier release, or run paas rollback web --to <deployment-id> (the ids are in paas deploys list --json). It switches straight back to a build that already ran there, so it’s fast — nothing is rebuilt. This is one more reason to promote into production rather than build there.
• In a build Environment, fix forward: push a fix, or git revert the bad commit and push. The branch decides what runs, so a revert is a rollback. (If the newest deployment failed, its deployment page also offers Roll back.)

What a rollback restores

Because the database stays as it is, a rollback is only safe if your migrations followed the rules above.

9. Configuration and secrets

Set plain configuration at the appropriate scope using the precedence rules. Keep each stage’s settings separate. Use secrets for credentials and attachments for managed services.

Variable changes and secret rotation roll out automatically; the secret lifecycle table explains the delete-and-recreate exception. Test configuration changes in staging because they do not have numbered-deployment automatic rollback.

10. Watch your app

• Follow every deployment. paas watch ends with exit code 0 only when the new version is live, so you can use it as a step in CI with an account API token. See CI verification.
• Read your logs in the app’s Logs tab or with paas logs --tail — they include every instance. See Logs.
• Check metrics after a deployment and when traffic changes: CPU, memory and, for web apps, requests and response times. See Metrics.
• Deployment problems are emailed to the organization owner: failed builds, failed or rolled-back deployments.

Production checklist

Before you send real users to an app, check that:

• The code deploys from a linked GitHub or GitLab repository, with Wait for CI on and direct pushes off.
• There’s a build Environment, and staging and production are promote-only. Production is Protected.
• The app listens on $PORT on 0.0.0.0, logs to stdout/stderr, and keeps durable state outside instances (local scratch files are temporary).
• It checks its required settings at startup and exits with a clear message if one is missing.
• Web apps have a fast, shallow health check path; workers have a health check command.
• The app handles SIGTERM and finishes in-flight work within 30 seconds.
• Production runs at least two instances (or autoscales with a minimum of two), and isn’t a singleton unless it must be.
• Memory limits leave headroom above normal use.
• Production data lives in PostgreSQL with High availability, attached rather than copied.
• Migrations run as the release command, are backward compatible, and are safe to run twice.
• Automatic rollback is on, and you know how to roll back by hand in each Environment.
• Credentials are in secrets, and each stage has its own settings and databases.

Next steps

• Deploy from GitHub or GitLab — connect your repository
• Pipelines, Promotion & Rollback — set up development, staging and production
• Deployments, Health Checks & Rollback — what happens during a deployment, in detail
• Scaling & Autoscaling — instances, CPU, memory and singleton apps
• d2o-paas.yaml Reference — keep your app’s settings in your repo

Build an example app

Start with a small HTTP app, then give it persistent notes, a background export worker, and private object storage. Choose one language; each path is self-contained.

Every server-side path follows the same sequence:

1. Create and deploy a hello app.
2. Store notes in PostgreSQL.
3. Queue exports in Redis and process them in a separate worker.
4. Store exports in a private S3-compatible bucket.
5. Optionally replace PostgreSQL with MariaDB or MongoDB.

PostgreSQL, MariaDB, and MongoDB are alternative primary stores; Redis is the queue. You do not need all three primary databases for an app. The static path uses browser-safe public assets; it has no server process that can use database credentials.

Each chapter provides dashboard and CLI paths. Choose one path for each step; do not create the same resource twice. Both paths push source with Git. The prerequisites describe access, tooling, and availability checks. Local services let you try the same source on your computer.

These are learning apps without user accounts. Anyone with the app URL can read and create notes and request downloads, even though the backing bucket is private. Use sample text only. Add authentication, authorization, rate limits, and export retention before adapting the code to real users. Queued jobs and export status depend on Redis; notes remain in the primary database if Redis data is lost, and exports can be regenerated.

When you finish, follow Take an Example to Production. It connects the learning checkpoints to app design, migrations, availability, and recovery guidance.

Before you start

1. Check access and tools

You need an invited d2o account, an Organization, permission to create and deploy apps, and permission to manage databases and object storage in your tutorial Project. See Access Control. Creating resources consumes your plan’s quota.

Install Git and your chosen language runtime. Install the paas CLI if following the CLI path. A POSIX shell (bash/zsh, or WSL on Windows) is used below. Docker Compose is only needed for optional local service tests. The AWS CLI is only needed if you follow the optional local S3 tests; hosted uploads use paas buckets put.

2. Check that your installation has the tutorial features

Use CLI 0.9.0 or later for app-scoped attachment commands. Check paas --version and update with the installation instructions if necessary. The dashboard path uses Process type on Create Resource to select web and worker processes.

All six tutorial frameworks are available on hosted d2o. Check the framework requirements and runtime catalog for the language version you use. On a self-hosted installation, your operator can confirm whether its builders and storage services are enabled.

Object storage availability can vary by Environment type; these examples use Development Environments.

3. Create one Project

Dashboard: open your Organization → Create Project, name it Examples, and use the slug examples. You will create a separate Development Environment for each language, so the example resource names never collide.

CLI: replace your-org below with your Organization slug, then run:

TUTORIAL_ORG=your-org
paas login --host https://dashboard.d2o.io
paas projects create examples -o "$TUTORIAL_ORG" --name Examples
paas keys add

For a self-hosted installation, substitute your dashboard origin in paas login; see API addresses.

If examples already exists and is suitable for disposable tutorial data, reuse it. Keep TUTORIAL_ORG set in each terminal running CLI commands. Each chapter spells out Project and Environment flags; it does not change your saved defaults.

4. Prepare Git authentication

Dashboard: Account Settings → SSH Keys → Add Key; paste your public key. The Environment’s Git remote panel supplies the actual remote URL and push commands.

CLI: paas keys add uploads your existing public key. If you do not have an SSH key, follow Deploying with Git Push first. The tutorial uses the Environment’s shared repository from its first commit so the web and worker can share one build later. There is no external GitHub repository to configure.

5. Use the source checkpoints

Each language provides two ZIPs: hello and notes. The downloads include source, lockfiles, and a local compose.yaml; they exclude installed dependencies and credentials. The hello chapter shows the small app’s files. The notes ZIP is the complete next checkpoint: copy it over hello, then enable its database, queue, and storage integrations one chapter at a time. The source appendix explains the application code; no code generator is required.

Each app listens on 0.0.0.0:$PORT, with port 3000 configured on PaaS, and exposes GET /health. Health intentionally checks the HTTP process only, allowing you to open a console and initialize the database schema before the notes routes are usable.

Run the notes examples locally

Local testing is optional; the deployment walkthrough uses managed PaaS resources. These commands use only the disposable services in the example’s compose.yaml. The supplied passwords are local demo values, not PaaS credentials.

1. Start the services

Install Docker with Compose. From an unpacked notes download, run:

docker compose up -d --wait
cp .env.example .env
set -a
. ./.env
set +a

From a repository checkout, use docker compose -f ../../compose.yaml up -d --wait inside examples/<language>/notes instead. The file starts PostgreSQL, MariaDB, MongoDB, Redis, and a SeaweedFS S3 service. All published ports bind to 127.0.0.1. They use unusual port numbers to avoid colliding with your existing development databases.

2. Choose a primary database

The default .env.example selects PostgreSQL. For another engine, change these two values in your local .env, then load it again in both web and worker terminals:

REDIS_URL=redis://:tutorial@127.0.0.1:18379/0 is shared by the web and worker. Run one language at a time against this local queue; otherwise one language’s worker can pick up another’s export request. Use distinct Redis database numbers for independent simultaneous examples.

3. Install and start the chosen app

Follow the download’s README to install dependencies. Initialize the schema once, then start the web process and worker in separate terminals with the same environment:

Activate .venv in each Python terminal. For Rails, set a local SECRET_KEY_BASE using ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'; use RAILS_ENV=development locally. Open http://localhost:3000, save a note, and export it. Without the optional S3 variables, the worker stores the generated JSON in Redis.

4. Enable local object storage

Uncomment all five S3/AWS variables in .env and reload it. With the AWS CLI installed, create the local bucket once:

aws --endpoint-url "$S3_ENDPOINT" --region "$S3_REGION" s3 mb "s3://$S3_BUCKET"

Restart both processes with those variables and request a new export. List its file:

aws --endpoint-url "$S3_ENDPOINT" --region "$S3_REGION" s3 ls "s3://$S3_BUCKET/exports/"

These settings point at the local S3-compatible service. On PaaS, bucket attachments supply the actual endpoint, region, name, and credentials instead.

5. Stop and reset

Stop web/worker processes with Ctrl+C. docker compose stop retains local service state; docker compose down -v removes the local tutorial containers and data. From the repo checkout, include -f ../../compose.yaml again. These commands do not touch your PaaS resources.

Return to your language tutorial for hosted deployment, or continue with production preparation.

Node.js and Express: notes and background exports

You will use Node.js 22 and build a web app named notes-web plus a worker named notes-worker in the examples Project’s nodejs Environment.

Express handles HTTP routes. The pg, mysql2, and MongoDB drivers implement the three persistence options; redis and the AWS S3 SDK handle jobs and files.

Complete Before you start, then follow these chapters in order:

1. Create and deploy hello
2. Persist notes in PostgreSQL
3. Add a Redis export worker
4. Save exports in object storage
5. Try MariaDB or MongoDB instead
6. Prepare for production, or troubleshoot and clean up

Downloads: hello source · complete notes source. The source walkthrough is included directly from those runnable files.

1. Create and deploy a Node.js and Express hello app

You will see a hello response at / and ok at /health before adding any services.

1. Download and run locally

Download the hello ZIP into a working directory, then open a terminal in that directory:

unzip nodejs-hello.zip
cd nodejs-hello
npm ci
npm start

Keep it running. In another terminal, curl -fsS http://localhost:3000/health should print ok. Open http://localhost:3000/ and confirm the hello message. Stop the server with Ctrl+C.

The app source is small enough to inspect in full:

package.json

{
  "name": "d2o-hello",
  "private": true,
  "type": "module",
  "engines": {
    "node": "22.x"
  },
  "scripts": {
    "start": "node server.mjs"
  }
}

server.mjs

import { createServer } from 'node:http';
const server = createServer((req, res) => {
  res.setHeader('Content-Type', 'text/plain');
  res.end(req.url === '/health' ? 'ok\n' : 'Hello from Node.js on d2o!\n');
});
server.listen(Number(process.env.PORT || 3000), '0.0.0.0');
process.on('SIGTERM', () => server.close());

Procfile

web: npm start

Keep the supplied lockfiles in Git. The buildpack uses these manifests and its runtime version declaration to reproduce the app’s dependencies.

2. Create the Environment

Dashboard: open Project Examples → create Environment nodejs, type Development, branch main, release source Build, Automatic deployment on.

CLI:

paas envs create nodejs -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build

3. Create the web app

Dashboard: inside nodejs choose Add Resource → Web Application. Name it notes-web, choose Framework Node.js, Repository The environment’s shared repository, Directory blank (repository root), and Process type web. Use Port 3000, Health Check Path /health, and one replica. Click Create Resource.

CLI:

paas apps create notes-web --framework nodejs --shared-source --start-command web --port 3000 --health-check-path /health -o "$TUTORIAL_ORG" -p examples -e nodejs

4. Commit and push

Initialize a repository in the unpacked hello directory:

git init -b main
git add .
git commit -m "Add hello application"

Dashboard path: open the Environment’s Git remote panel, copy its shared-repository remote command into this directory, then run its push command. This is the Environment remote, not a per-app remote. The dashboard supplies the correct host and authentication URL.

CLI path: omit -a when setting the shared remote:

paas git remote -o "$TUTORIAL_ORG" -p examples -e nodejs
git push d2o main
paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs

5. Verify the deployed app

Dashboard: open notes-web → Deployments, wait for the successful build and running instance, then open its public URL. Append /health; it should display ok. CLI: paas ps and paas logs with -o "$TUTORIAL_ORG" -p examples -e nodejs and -a notes-web show the running process. Use the public URL displayed in the dashboard, or read the url field from paas apps info notes-web --json with the same Organization, Project, and Environment flags.

APP_URL=https://your-app-host
curl -fsS "$APP_URL/health"
curl -fsS "$APP_URL/"

Set APP_URL to your actual URL, with no trailing slash. If the build fails, see troubleshooting before continuing.

Next: Persist notes in PostgreSQL.

2. Persist notes in PostgreSQL

Replace hello with the notes checkpoint, attach PostgreSQL, and create the schema once. The Redis and S3 code is present but is not used until you request an export.

1. Replace the source checkpoint

Download the complete notes ZIP beside your hello directory. From inside nodejs-hello, run:

cd ..
unzip nodejs-notes.zip
cp -R nodejs-notes/. nodejs-hello/
cd nodejs-hello
rm server.mjs
npm ci

This retains the hello directory’s .git history and shared remote. The rm command removes only the superseded hello source file in this tutorial directory. The source appendix shows the database implementation. Notes use UUID IDs, validated text, and parameterized SQL or the MongoDB driver; no file on the app instance stores notes. For an optional local run, follow Local services and run node app.mjs migrate before npm start.

2. Create and attach PostgreSQL

Dashboard: in nodejs add a Database named notes-db, engine PostgreSQL, with 1 GB storage. Wait until running. Open notes-web → Config → Attached Resources, select notes-db, leave the variable name blank (DATABASE_URL), and click Attach. In the same Config tab add plain variable DATABASE_ENGINE=postgresql.

CLI:

paas dbs create notes-db --type postgresql --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e nodejs
paas dbs info notes-db -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-web notes-db -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=postgresql -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs

Wait for database provisioning before trying to initialize the schema. The attachment injects DATABASE_URL; never copy credentials into the source or .env in Git. Check attachment names with paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs.

3. Deploy the notes app

git add .
git commit -m "Add persistent notes and export processes"
git push d2o main

Dashboard: wait for notes-web to be running in its Deployments/Overview view. CLI: run paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs. /health succeeds even before the schema exists; /notes may return 503 until the next step.

4. Initialize the schema

Dashboard: notes-web → Console → select a running instance → Connect. Run:

/cnb/process/migrate

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs -- /cnb/process/migrate

The migrate process is declared in the Procfile. Calling /cnb/process/migrate loads the buildpack runtime environment, including the language executable and dependencies. Expect Schema ready. The command creates the notes table if missing, so it is safe to repeat for this example. paas run does not relay the remote exit code: inspect the output and verify /notes, rather than assuming a zero CLI exit means the schema succeeded.

5. Check persistence

Open the app URL, enter a sample note, and choose Save note. Refresh; the note remains. You can also test from your terminal:

curl -fsS -H "Content-Type: application/json" -d '{"body":"My first persistent note"}' "$APP_URL/notes"
curl -fsS "$APP_URL/notes"

Restart notes-web from its dashboard action or run paas restart -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs. Wait for it to be running and fetch /notes again; the note must still be present. An empty body returns HTTP 400. Leave Export notes for the next chapter.

For production, replace manual schema setup with versioned release-command migrations.

Next: Add a Redis export worker.

3. Add a Redis export worker

The web app queues a job and immediately returns its ID. A separate process reads the notes and generates JSON. This chapter stores that JSON in Redis; the next moves it to S3.

1. Create Redis

Dashboard: in nodejs add Database notes-queue, engine Redis, 1 GB storage; wait until running. In notes-web → Config, attach it with variable name REDIS_URL. Do not use the default DATABASE_URL, which already points at PostgreSQL.

CLI:

paas dbs create notes-queue --type redis --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-web notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e nodejs

2. Create the worker from the same code

Dashboard: add a Background Worker named notes-worker, Framework nodejs (the same selection as the web app), Repository The environment’s shared repository, Directory blank, Process type worker, one replica. A worker has no public HTTP endpoint. Open its Config tab, set DATABASE_ENGINE=postgresql, and attach both notes-db as DATABASE_URL and notes-queue as REDIS_URL.

CLI:

paas apps create notes-worker --worker --framework nodejs --shared-source --process worker -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=postgresql -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-worker notes-db -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-worker notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e nodejs

The worker must have its own attachments; the web app’s configuration is not inherited. The process value is a named buildpack process, not a shell command. See the worker source for the job loop.

3. Push and check the worker

Trigger a shared build after both apps have their configuration:

git commit --allow-empty -m "Deploy web and export worker"
git push d2o main

Dashboard: wait for both apps to run, then open notes-worker → Logs and look for Worker ready. CLI: paas watch -o "$TUTORIAL_ORG" -p examples -e nodejs follows both apps; then use paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs. The web app must still answer /health.

4. Export and recover a queued job

In the browser, click Export notes, wait for the download link, and open the JSON. It must contain your saved note. Logs show Export ready: <id>.

To check queueing while the worker is unavailable, open its dashboard Overview and use − in the Replicas row to reach 0, then confirm the stop, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs. Request an export; it stays queued. Use + in the same row to restore replicas to 1 (or paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs); the same job should complete. If the UI polling times out after 90 seconds, query /exports/<id> and download from /exports/<id>/download once ready, or submit another export.

The worker uses Redis Streams with a consumer group. It acknowledges only after saving the result. A replacement worker claims unacknowledged jobs idle for 30 seconds; writes use the same export ID so a retried job overwrites the same result. Failures remain queued for retry and appear in worker logs. This is at-least-once delivery, not exactly-once delivery. Do not use this loop unchanged for side effects such as charging a payment.

Redis itself is not backed up by the platform. For essential jobs, retain enough information in the primary database to recreate or reconcile them. See durability and recovery and production preparation.

Next: Save exports in object storage.

4. Save exports in object storage

Keep notes in the database and move newly generated JSON exports into a private bucket. The web app streams downloads from S3; browser code never receives bucket credentials.

1. Create the bucket

Dashboard: in nodejs add Object Storage, name notes-exports, tier Capacity, quota 1 GB. Leave it private and wait until provisioned. Capacity is suitable here because exports can be recreated from notes. Use High availability for irreplaceable files.

CLI:

paas buckets create notes-exports --tier capacity --quota-gb 1 -o "$TUTORIAL_ORG" -p examples -e nodejs
paas buckets info -a notes-exports -o "$TUTORIAL_ORG" -p examples -e nodejs

Wait for available: true; keep public: false.

2. Attach the bucket to both apps

Dashboard: open each app’s Config tab, choose bucket notes-exports in the attachment card, leave the credential prefix blank, and click Attach.

CLI:

paas apps attach notes-web notes-exports -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-worker notes-exports -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

The primary attachment injects S3_ENDPOINT, S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. The storage implementation passes the endpoint and region explicitly and uses path-style S3 requests. Do not add these credentials to frontend code, Git, or ordinary config variables. Wait for both apps to restart with the new attachment before testing.

3. Generate a new export

Open the app and request a new export. Exports made before the bucket attachment still live in Redis, so their old download links no longer work while S3 mode is enabled. Download the new JSON and confirm your note appears.

Dashboard: open notes-exports → Files → exports/. The file named <job-id>.json should be present. CLI:

paas buckets ls exports/ -a notes-exports -o "$TUTORIAL_ORG" -p examples -e nodejs

A direct anonymous object request should return 403; downloading through the app succeeds because its server uses the attachment credentials. The bucket stays private, but the example app itself has no user authentication. Do not enter confidential data.

4. Verify durability and diagnose failures

Restart notes-worker, submit another export, and check that it completes. Restart notes-web and download the completed export again. No result depends on either app’s local filesystem. If a job stays queued, check worker logs, both apps’ attachment lists, and bucket readiness. After fixing a failed S3 write, the unacknowledged job retries after its 30-second idle interval.

Export files and Redis status records have no expiration in this teaching example. Delete unneeded files in the bucket’s Files tab, or clean up the entire isolated Environment when done.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MariaDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects the same SQL notes table, through its MariaDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in nodejs create Database notes-mariadb, engine MariaDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mariadb --type mariadb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e nodejs
paas dbs info notes-mariadb -o "$TUTORIAL_ORG" -p examples -e nodejs

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mariadb using DATABASE_URL, then set DATABASE_ENGINE=mariadb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-web notes-mariadb -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-worker notes-mariadb -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=mariadb -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=mariadb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs. Create a new note identifying MariaDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MongoDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects a notes collection with a unique id index, through its MongoDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in nodejs create Database notes-mongodb, engine MongoDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mongodb --type mongodb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e nodejs
paas dbs info notes-mongodb -o "$TUTORIAL_ORG" -p examples -e nodejs

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mongodb using DATABASE_URL, then set DATABASE_ENGINE=mongodb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-web notes-mongodb -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attach notes-worker notes-mongodb -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=mongodb -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas config set DATABASE_ENGINE=mongodb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs. Create a new note identifying MongoDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Node.js and Express source walkthrough

The runnable source below is included from the same files packaged in the notes download. Lockfiles, configuration, and the shared browser UI are included in the download.

Database

A notes request reaches this adapter after input validation. DATABASE_ENGINE chooses PostgreSQL, MariaDB, or MongoDB; DATABASE_URL comes from the app’s attachment. SQL uses parameters rather than interpolating note text, and MongoDB uses driver operations. The initialization process creates a table or unique index. Records live in the database, so replacing a web instance leaves them available to its replacement.

const engine = process.env.DATABASE_ENGINE || 'postgresql';
let db;
async function database() {
  if (db) return db;
  if (!process.env.DATABASE_URL) throw new Error('Attach a database first');
  if (engine === 'postgresql') db = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
  else if (engine === 'mariadb') db = mysql.createPool(process.env.DATABASE_URL);
  else if (engine === 'mongodb') {
    const client = new MongoClient(process.env.DATABASE_URL);
    await client.connect();
    db = client.db().collection('notes');
  } else throw new Error('Unsupported DATABASE_ENGINE');
  return db;
}
async function migrate() {
  const db = await database();
  if (engine === 'mongodb') await db.createIndex({ id: 1 }, { unique: true });
  else await db.query('CREATE TABLE IF NOT EXISTS notes (id VARCHAR(36) PRIMARY KEY, body TEXT NOT NULL)');
  console.log('Schema ready');
}
async function notes() {
  const db = await database();
  if (engine === 'mongodb') return db.find({}, { projection: { _id: 0 } }).sort({ id: 1 }).toArray();
  const result = await db.query('SELECT id, body FROM notes ORDER BY id');
  return engine === 'postgresql' ? result.rows : result[0];
}
async function addNote(body) {
  const db = await database(), note = { id: randomUUID(), body };
  if (engine === 'mongodb') await db.insertOne({ ...note });
  else await db.query(engine === 'postgresql'
    ? 'INSERT INTO notes (id, body) VALUES ($1, $2)'
    : 'INSERT INTO notes (id, body) VALUES (?, ?)', [note.id, body]);
  return note;
}

Worker

Creating an export enqueues an ID and returns immediately. This loop reads the notes, writes an export under that ID, records its status, and acknowledges the stream entry. It also reclaims jobs abandoned before acknowledgement. Retrying writes the same export key, so interruption does not create an additional export file; the snapshot can reflect newer notes if they changed before the retry. See worker recovery.

async function worker() {
  const redis = await queue(), consumer = randomUUID();
  try { await redis.xGroupCreate('exports', 'workers', '0', { MKSTREAM: true }); }
  catch (error) { if (!error.message.includes('BUSYGROUP')) throw error; }
  let stopping = false;
  process.on('SIGTERM', () => { stopping = true; });
  process.on('SIGINT', () => { stopping = true; });
  console.log('Worker ready');
  while (!stopping) {
    try {
      const claimed = await redis.xAutoClaim('exports', 'workers', consumer, 30000, '0-0', { COUNT: 1 });
      const messages = claimed.messages.length ? claimed.messages
        : (await redis.xReadGroup('workers', consumer, [{ key: 'exports', id: '>' }], { COUNT: 1, BLOCK: 5000 }))?.[0].messages || [];
      for (const message of messages) {
        const id = message.message.id;
        if (!/^[0-9a-f-]{36}$/.test(id || '')) {
          await redis.xAck('exports', 'workers', message.id);
          continue;
        }
        if (await redis.get(`export:${id}`) !== 'ready') {
          await saveExport(redis, id, JSON.stringify(await notes(), null, 2));
          await redis.set(`export:${id}`, 'ready');
        }
        await redis.xAck('exports', 'workers', message.id);
        await redis.xDel('exports', message.id);
        console.log(`Export ready: ${id}`);
      }
    } catch {
      console.error('Export failed; unacknowledged jobs retry after 30 seconds. Check attachments and schema.');
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  process.exit(0);
}

Object storage

Without S3 configuration, exports are stored in Redis for the worker checkpoint. With an attached bucket, the worker writes JSON to exports/<id>.json and the web process reads that object for downloads. Both processes need their own bucket attachment. The client uses the supplied endpoint and region with path-style requests. Credentials stay on the server; a private bucket does not add authentication to the example’s public download route.

let s3;
function storage() {
  s3 ||= new S3Client({ endpoint: process.env.S3_ENDPOINT, region: process.env.S3_REGION, forcePathStyle: true });
  return s3;
}
async function saveExport(redis, id, data) {
  if (process.env.S3_BUCKET) {
    await storage().send(new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: `exports/${id}.json`, Body: data, ContentType: 'application/json' }));
  } else await redis.set(`export:${id}:data`, data);
}
async function loadExport(redis, id) {
  if (!process.env.S3_BUCKET) return redis.get(`export:${id}:data`);
  const result = await storage().send(new GetObjectCommand({ Bucket: process.env.S3_BUCKET, Key: `exports/${id}.json` }));
  return result.Body.transformToString();
}

Complete application

The complete source and startup commands are in the notes ZIP linked above. The HTTP layer connects the three components: POST /notes validates and saves a record, GET /notes lists records, POST /exports queues work, and the export status and download routes expose the result. Follow the language’s tutorial sequence to exercise each part, then review production preparation.

Troubleshoot and clean up Node.js and Express

Diagnose a failed checkpoint

Commit package-lock.json and use npm ci locally. Keep Procfile and package.json in the source root. The worker mode is node app.mjs worker; npm start runs the web mode.

Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.

CLI:

paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e nodejs
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e nodejs

Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.

Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.

Clean up

Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.

Dashboard: open Project Examples → Environment nodejs → Settings → Delete Environment, then confirm its name. Make sure this Environment contains only the tutorial resources.

CLI: review its resources, then confirm deletion:

paas apps list -o "$TUTORIAL_ORG" -p examples -e nodejs
paas dbs list -o "$TUTORIAL_ORG" -p examples -e nodejs
paas envs delete nodejs -o "$TUTORIAL_ORG" -p examples --confirm nodejs

This removes the web/worker, primary and optional databases, Redis, and tutorial bucket created in this Environment. If you used local services, run docker compose down -v from the example folder to discard that separate local dataset.

Ruby on Rails: notes and background exports

You will use Ruby 3.4 and Bundler and build a web app named notes-web plus a worker named notes-worker in the examples Project’s rails Environment.

This is a small Rails API application using Rails routing and controllers. Active Record handles PostgreSQL and MariaDB (the Trilogy adapter); the Mongo Ruby driver handles MongoDB. It deliberately has no asset pipeline or database-backed job framework: the worker chapter shows the Redis queue directly.

Complete Before you start, then follow these chapters in order:

1. Create and deploy hello
2. Persist notes in PostgreSQL
3. Add a Redis export worker
4. Save exports in object storage
5. Try MariaDB or MongoDB instead
6. Prepare for production, or troubleshoot and clean up

Downloads: hello source · complete notes source. The source walkthrough is included directly from those runnable files.

1. Create and deploy a Ruby on Rails hello app

You will see a hello response at / and ok at /health before adding any services.

1. Download and run locally

Download the hello ZIP into a working directory, then open a terminal in that directory:

unzip rails-hello.zip
cd rails-hello
bundle install
bundle exec puma -b tcp://0.0.0.0:3000

Keep it running. In another terminal, curl -fsS http://localhost:3000/health should print ok. Open http://localhost:3000/ and confirm the hello message. Stop the server with Ctrl+C.

The app source is small enough to inspect in full:

Gemfile

source "https://rubygems.org"
ruby "~> 3.4.0"
gem "rails", "~> 8.0.0"
gem "puma", "~> 6.6"

Procfile

web: bundle exec puma -b tcp://0.0.0.0:$PORT

config.ru

require_relative "config/environment"
run Rails.application

Rakefile

require_relative "config/application"
Rails.application.load_tasks

bin/rails

#!/usr/bin/env ruby
APP_PATH = File.expand_path("../config/application", __dir__)
require "bundler/setup"
require "rails/commands"

config/application.rb

require "bundler/setup"
require "rails"
require "action_controller/railtie"
module HelloTutorial
 class Application < Rails::Application
  config.load_defaults 8.0
  config.api_only = true
  config.eager_load = ENV["RAILS_ENV"] == "production"
  config.hosts << ENV["PAAS_PUBLIC_HOST"] if ENV["PAAS_PUBLIC_HOST"]
  config.logger = ActiveSupport::Logger.new($stdout)
 end
end

config/environment.rb

require_relative "application"
Rails.application.initialize!

config/routes.rb

Rails.application.routes.draw do
 root "hello#index"
 get "/health", to: "hello#health"
end

app/controllers/hello_controller.rb

class HelloController < ActionController::API
 def index
  render plain: "Hello from Rails on d2o!\n"
 end
 def health
  render plain: "ok\n"
 end
end

Keep the supplied lockfiles in Git. The buildpack uses these manifests and its runtime version declaration to reproduce the app’s dependencies.

2. Create the Environment

Dashboard: open Project Examples → create Environment rails, type Development, branch main, release source Build, Automatic deployment on.

CLI:

paas envs create rails -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build

3. Create the web app

Dashboard: inside rails choose Add Resource → Web Application. Name it notes-web, choose Framework Ruby on Rails, Repository The environment’s shared repository, Directory blank (repository root), and Process type web. Use Port 3000, Health Check Path /health, and one replica. Click Create Resource.

CLI:

paas apps create notes-web --framework rails --shared-source --start-command web --port 3000 --health-check-path /health -o "$TUTORIAL_ORG" -p examples -e rails

4. Set the Rails application secret

Generate a value locally with ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'. In the dashboard, open the rails Environment’s Secrets page and add RAILS_SECRET_KEY_BASE with that value. Secret creation is currently dashboard-only, including when you follow the CLI path. Do not put the value in Git or a plain config variable.

Dashboard: on notes-web → Config, add SECRET_KEY_BASE, choose Link to secret, and select RAILS_SECRET_KEY_BASE.

CLI: after creating the secret in the dashboard:

paas config set --secret-ref RAILS_SECRET_KEY_BASE SECRET_KEY_BASE -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails

The platform supplies the value at runtime. Local development can use a locally generated SECRET_KEY_BASE; the source never contains a deployment secret.

5. Commit and push

Initialize a repository in the unpacked hello directory:

git init -b main
git add .
git commit -m "Add hello application"

Dashboard path: open the Environment’s Git remote panel, copy its shared-repository remote command into this directory, then run its push command. This is the Environment remote, not a per-app remote. The dashboard supplies the correct host and authentication URL.

CLI path: omit -a when setting the shared remote:

paas git remote -o "$TUTORIAL_ORG" -p examples -e rails
git push d2o main
paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails

6. Verify the deployed app

Dashboard: open notes-web → Deployments, wait for the successful build and running instance, then open its public URL. Append /health; it should display ok. CLI: paas ps and paas logs with -o "$TUTORIAL_ORG" -p examples -e rails and -a notes-web show the running process. Use the public URL displayed in the dashboard, or read the url field from paas apps info notes-web --json with the same Organization, Project, and Environment flags.

APP_URL=https://your-app-host
curl -fsS "$APP_URL/health"
curl -fsS "$APP_URL/"

Set APP_URL to your actual URL, with no trailing slash. If the build fails, see troubleshooting before continuing.

Next: Persist notes in PostgreSQL.

2. Persist notes in PostgreSQL

Replace hello with the notes checkpoint, attach PostgreSQL, and create the schema once. The Redis and S3 code is present but is not used until you request an export.

1. Replace the source checkpoint

Download the complete notes ZIP beside your hello directory. From inside rails-hello, run:

cd ..
unzip rails-notes.zip
cp -R rails-notes/. rails-hello/
cd rails-hello
rm app/controllers/hello_controller.rb
bundle install

This retains the hello directory’s .git history and shared remote. The rm command removes only the superseded hello source file in this tutorial directory. The source appendix shows the database implementation. Notes use UUID IDs, validated text, and parameterized SQL or the MongoDB driver; no file on the app instance stores notes. For an optional local run, follow Local services and run bundle exec ruby bin/rails runner 'NotesStore.migrate' before bundle exec puma -b tcp://0.0.0.0:3000.

2. Create and attach PostgreSQL

Dashboard: in rails add a Database named notes-db, engine PostgreSQL, with 1 GB storage. Wait until running. Open notes-web → Config → Attached Resources, select notes-db, leave the variable name blank (DATABASE_URL), and click Attach. In the same Config tab add plain variable DATABASE_ENGINE=postgresql.

CLI:

paas dbs create notes-db --type postgresql --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rails
paas dbs info notes-db -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-web notes-db -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=postgresql -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails

Wait for database provisioning before trying to initialize the schema. The attachment injects DATABASE_URL; never copy credentials into the source or .env in Git. Check attachment names with paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails.

3. Deploy the notes app

git add .
git commit -m "Add persistent notes and export processes"
git push d2o main

Dashboard: wait for notes-web to be running in its Deployments/Overview view. CLI: run paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails. /health succeeds even before the schema exists; /notes may return 503 until the next step.

4. Initialize the schema

Dashboard: notes-web → Console → select a running instance → Connect. Run:

/cnb/process/migrate

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails -- /cnb/process/migrate

The migrate process is declared in the Procfile. Calling /cnb/process/migrate loads the buildpack runtime environment, including the language executable and dependencies. Expect Schema ready. The command creates the notes table if missing, so it is safe to repeat for this example. paas run does not relay the remote exit code: inspect the output and verify /notes, rather than assuming a zero CLI exit means the schema succeeded.

5. Check persistence

Open the app URL, enter a sample note, and choose Save note. Refresh; the note remains. You can also test from your terminal:

curl -fsS -H "Content-Type: application/json" -d '{"body":"My first persistent note"}' "$APP_URL/notes"
curl -fsS "$APP_URL/notes"

Restart notes-web from its dashboard action or run paas restart -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails. Wait for it to be running and fetch /notes again; the note must still be present. An empty body returns HTTP 400. Leave Export notes for the next chapter.

For production, replace manual schema setup with versioned release-command migrations.

Next: Add a Redis export worker.

3. Add a Redis export worker

The web app queues a job and immediately returns its ID. A separate process reads the notes and generates JSON. This chapter stores that JSON in Redis; the next moves it to S3.

1. Create Redis

Dashboard: in rails add Database notes-queue, engine Redis, 1 GB storage; wait until running. In notes-web → Config, attach it with variable name REDIS_URL. Do not use the default DATABASE_URL, which already points at PostgreSQL.

CLI:

paas dbs create notes-queue --type redis --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-web notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e rails

2. Create the worker from the same code

Dashboard: add a Background Worker named notes-worker, Framework rails (the same selection as the web app), Repository The environment’s shared repository, Directory blank, Process type worker, one replica. A worker has no public HTTP endpoint. Open its Config tab, set DATABASE_ENGINE=postgresql, and attach both notes-db as DATABASE_URL and notes-queue as REDIS_URL.

CLI:

paas apps create notes-worker --worker --framework rails --shared-source --process worker -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=postgresql -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-worker notes-db -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-worker notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e rails

Also link the worker’s SECRET_KEY_BASE variable to RAILS_SECRET_KEY_BASE in Config, or run paas config set --secret-ref RAILS_SECRET_KEY_BASE SECRET_KEY_BASE -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails.

The worker must have its own attachments; the web app’s configuration is not inherited. The process value is a named buildpack process, not a shell command. See the worker source for the job loop.

3. Push and check the worker

Trigger a shared build after both apps have their configuration:

git commit --allow-empty -m "Deploy web and export worker"
git push d2o main

Dashboard: wait for both apps to run, then open notes-worker → Logs and look for Worker ready. CLI: paas watch -o "$TUTORIAL_ORG" -p examples -e rails follows both apps; then use paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails. The web app must still answer /health.

4. Export and recover a queued job

In the browser, click Export notes, wait for the download link, and open the JSON. It must contain your saved note. Logs show Export ready: <id>.

To check queueing while the worker is unavailable, open its dashboard Overview and use − in the Replicas row to reach 0, then confirm the stop, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails. Request an export; it stays queued. Use + in the same row to restore replicas to 1 (or paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails); the same job should complete. If the UI polling times out after 90 seconds, query /exports/<id> and download from /exports/<id>/download once ready, or submit another export.

The worker uses Redis Streams with a consumer group. It acknowledges only after saving the result. A replacement worker claims unacknowledged jobs idle for 30 seconds; writes use the same export ID so a retried job overwrites the same result. Failures remain queued for retry and appear in worker logs. This is at-least-once delivery, not exactly-once delivery. Do not use this loop unchanged for side effects such as charging a payment.

Redis itself is not backed up by the platform. For essential jobs, retain enough information in the primary database to recreate or reconcile them. See durability and recovery and production preparation.

Next: Save exports in object storage.

4. Save exports in object storage

Keep notes in the database and move newly generated JSON exports into a private bucket. The web app streams downloads from S3; browser code never receives bucket credentials.

1. Create the bucket

Dashboard: in rails add Object Storage, name notes-exports, tier Capacity, quota 1 GB. Leave it private and wait until provisioned. Capacity is suitable here because exports can be recreated from notes. Use High availability for irreplaceable files.

CLI:

paas buckets create notes-exports --tier capacity --quota-gb 1 -o "$TUTORIAL_ORG" -p examples -e rails
paas buckets info -a notes-exports -o "$TUTORIAL_ORG" -p examples -e rails

Wait for available: true; keep public: false.

2. Attach the bucket to both apps

Dashboard: open each app’s Config tab, choose bucket notes-exports in the attachment card, leave the credential prefix blank, and click Attach.

CLI:

paas apps attach notes-web notes-exports -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-worker notes-exports -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

The primary attachment injects S3_ENDPOINT, S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. The storage implementation passes the endpoint and region explicitly and uses path-style S3 requests. Do not add these credentials to frontend code, Git, or ordinary config variables. Wait for both apps to restart with the new attachment before testing.

3. Generate a new export

Open the app and request a new export. Exports made before the bucket attachment still live in Redis, so their old download links no longer work while S3 mode is enabled. Download the new JSON and confirm your note appears.

Dashboard: open notes-exports → Files → exports/. The file named <job-id>.json should be present. CLI:

paas buckets ls exports/ -a notes-exports -o "$TUTORIAL_ORG" -p examples -e rails

A direct anonymous object request should return 403; downloading through the app succeeds because its server uses the attachment credentials. The bucket stays private, but the example app itself has no user authentication. Do not enter confidential data.

4. Verify durability and diagnose failures

Restart notes-worker, submit another export, and check that it completes. Restart notes-web and download the completed export again. No result depends on either app’s local filesystem. If a job stays queued, check worker logs, both apps’ attachment lists, and bucket readiness. After fixing a failed S3 write, the unacknowledged job retries after its 30-second idle interval.

Export files and Redis status records have no expiration in this teaching example. Delete unneeded files in the bucket’s Files tab, or clean up the entire isolated Environment when done.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MariaDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects the same SQL notes table, through its MariaDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in rails create Database notes-mariadb, engine MariaDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mariadb --type mariadb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rails
paas dbs info notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rails

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mariadb using DATABASE_URL, then set DATABASE_ENGINE=mariadb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rails
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-web notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-worker notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=mariadb -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=mariadb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails. Create a new note identifying MariaDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MongoDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects a notes collection with a unique id index, through its MongoDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in rails create Database notes-mongodb, engine MongoDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mongodb --type mongodb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rails
paas dbs info notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rails

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mongodb using DATABASE_URL, then set DATABASE_ENGINE=mongodb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rails
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-web notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attach notes-worker notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=mongodb -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas config set DATABASE_ENGINE=mongodb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails. Create a new note identifying MongoDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Ruby on Rails source walkthrough

The runnable source below is included from the same files packaged in the notes download. Lockfiles, configuration, and the shared browser UI are included in the download.

Database

A notes request reaches this adapter after input validation. DATABASE_ENGINE chooses PostgreSQL, MariaDB, or MongoDB; DATABASE_URL comes from the app’s attachment. SQL uses parameters rather than interpolating note text, and MongoDB uses driver operations. The initialization process creates a table or unique index. Records live in the database, so replacing a web instance leaves them available to its replacement.

  def database
    DB_MUTEX.synchronize do
      return @database if @database
      url = ENV.fetch("DATABASE_URL")
      @database = case ENGINE
      when "mongodb" then Mongo::Client.new(url, server_selection_timeout: 5)[:notes]
      when "postgresql", "mariadb"
        # Active Record uses the Trilogy adapter for MariaDB.
        url = url.sub(/\Amysql:/, "trilogy:") if ENGINE == "mariadb"
        ActiveRecord::Base.establish_connection(url)
      else raise "Unsupported DATABASE_ENGINE"
      end
    end
  end

  def migrate
    db = database
    if ENGINE == "mongodb"
      db.indexes.create_one({ id: 1 }, unique: true)
    else
      ActiveRecord::Base.connection_pool.with_connection do |c|
        c.execute("CREATE TABLE IF NOT EXISTS notes (id VARCHAR(36) PRIMARY KEY, body TEXT NOT NULL)")
      end
    end
    puts "Schema ready"
  end

  def notes
    db = database
    if ENGINE == "mongodb"
      db.find.projection(_id: 0).sort(id: 1).to_a
    else
      Note.order(:id).pluck(:id, :body).map { |id, body| { id: id, body: body } }
    end
  end

  def add_note(body)
    db = database
    note = { id: SecureRandom.uuid, body: body }
    ENGINE == "mongodb" ? db.insert_one(note.dup) : Note.create!(note)
    note
  end

Worker

Creating an export enqueues an ID and returns immediately. This loop reads the notes, writes an export under that ID, records its status, and acknowledges the stream entry. It also reclaims jobs abandoned before acknowledgement. Retrying writes the same export key, so interruption does not create an additional export file; the snapshot can reflect newer notes if they changed before the retry. See worker recovery.

stopping = false
Signal.trap("TERM") { stopping = true }
Signal.trap("INT") { stopping = true }
consumer = SecureRandom.uuid
NotesStore.queue do |q|
  begin
    q.call("XGROUP", "CREATE", "exports", "workers", "0", "MKSTREAM")
  rescue Redis::CommandError => error
    raise unless error.message.include?("BUSYGROUP")
  end
  puts "Worker ready"
  until stopping
    begin
      messages = q.call("XAUTOCLAIM", "exports", "workers", consumer, "30000", "0-0", "COUNT", "1")[1]
      if messages.empty?
        result = q.call("XREADGROUP", "GROUP", "workers", consumer, "COUNT", "1", "BLOCK", "5000", "STREAMS", "exports", ">")
        messages = result ? result[0][1] : []
      end
      messages.each do |message_id, values|
        id = Hash[*values]["id"]
        unless id&.match?(/\A[0-9a-f-]{36}\z/)
          q.call("XACK", "exports", "workers", message_id)
          next
        end
        unless q.get("export:#{id}") == "ready"
          NotesStore.save_export(q, id, JSON.pretty_generate(NotesStore.notes))
          q.set("export:#{id}", "ready")
        end
        q.call("XACK", "exports", "workers", message_id)
        q.call("XDEL", "exports", message_id)
        puts "Export ready: #{id}"
      end
    rescue StandardError
      warn "Export failed; unacknowledged jobs retry after 30 seconds. Check attachments and schema."
      sleep 1
    end
  end
end

Object storage

Without S3 configuration, exports are stored in Redis for the worker checkpoint. With an attached bucket, the worker writes JSON to exports/<id>.json and the web process reads that object for downloads. Both processes need their own bucket attachment. The client uses the supplied endpoint and region with path-style requests. Credentials stay on the server; a private bucket does not add authentication to the example’s public download route.

  def storage
    Aws::S3::Client.new(endpoint: ENV.fetch("S3_ENDPOINT"), region: ENV.fetch("S3_REGION"), force_path_style: true)
  end

  def save_export(q, id, data)
    if ENV["S3_BUCKET"]
      storage.put_object(bucket: ENV.fetch("S3_BUCKET"), key: "exports/#{id}.json", body: data, content_type: "application/json")
    else
      q.set("export:#{id}:data", data)
    end
  end

  def load_export(q, id)
    if ENV["S3_BUCKET"]
      storage.get_object(bucket: ENV.fetch("S3_BUCKET"), key: "exports/#{id}.json").body.read
    else
      q.get("export:#{id}:data")
    end
  end

Routes and controller

Rails.application.routes.draw do
  root "notes#index"
  get "/health", to: "notes#health"
  get "/notes", to: "notes#list"
  post "/notes", to: "notes#create"
  post "/exports", to: "notes#export"
  get "/exports/:id", to: "notes#status"
  get "/exports/:id/download", to: "notes#download"
end

class NotesController < ActionController::API
  rescue_from StandardError do
    render json: { error: "Check attachments, schema, and service availability" }, status: 503
  end

  def index
    render html: File.read(Rails.root.join("public/index.html")).html_safe
  end

  def health
    render plain: "ok\n"
  end

  def list
    render json: NotesStore.notes
  end

  def create
    body = params[:body]
    unless body.is_a?(String) && !body.strip.empty? && body.length <= 2000
      return render json: { error: "Enter a note of 1–2000 characters" }, status: 400
    end
    render json: NotesStore.add_note(body), status: 201
  end

  def export
    id = SecureRandom.uuid
    NotesStore.queue do |q|
      q.set("export:#{id}", "queued")
      q.call("XADD", "exports", "*", "id", id)
    end
    render json: { id: id }, status: 202
  end

  def status
    state = NotesStore.queue { |q| q.get("export:#{params[:id]}") }
    render json: { status: state || "unknown" }, status: state ? 200 : 404
  end

  def download
    id = params[:id]
    state = NotesStore.queue { |q| q.get("export:#{id}") }
    unless id.match?(/\A[0-9a-f-]{36}\z/) && state == "ready"
      return render json: { error: "Export not ready" }, status: 404
    end
    data = NotesStore.queue { |q| NotesStore.load_export(q, id) }
    send_data data, type: "application/json", filename: "notes.json"
  end
end

Review production preparation before adapting these handlers to real users.

Troubleshoot and clean up Ruby on Rails

Diagnose a failed checkpoint

Commit Gemfile.lock with a Linux platform entry (bundle lock --add-platform x86_64-linux). A missing SECRET_KEY_BASE is fixed by the linked Rails secret. MariaDB uses Trilogy; do not replace its connection scheme with an arbitrary string. The API-only app does not need an asset compilation step.

Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.

CLI:

paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rails
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rails

Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.

Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.

Clean up

Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.

Dashboard: open Project Examples → Environment rails → Settings → Delete Environment, then confirm its name. Make sure this Environment contains only the tutorial resources.

CLI: review its resources, then confirm deletion:

paas apps list -o "$TUTORIAL_ORG" -p examples -e rails
paas dbs list -o "$TUTORIAL_ORG" -p examples -e rails
paas envs delete rails -o "$TUTORIAL_ORG" -p examples --confirm rails

This removes the web/worker, primary and optional databases, Redis, and tutorial bucket created in this Environment. If you used local services, run docker compose down -v from the example folder to discard that separate local dataset.

Python and Flask: notes and background exports

You will use Python 3.13 and build a web app named notes-web plus a worker named notes-worker in the examples Project’s python Environment.

Flask defines the routes and Gunicorn serves them in the deployed web process. Psycopg, PyMySQL, and PyMongo handle persistence. The committed Procfile is required by the Python builder.

Complete Before you start, then follow these chapters in order:

1. Create and deploy hello
2. Persist notes in PostgreSQL
3. Add a Redis export worker
4. Save exports in object storage
5. Try MariaDB or MongoDB instead
6. Prepare for production, or troubleshoot and clean up

Downloads: hello source · complete notes source. The source walkthrough is included directly from those runnable files.

1. Create and deploy a Python and Flask hello app

You will see a hello response at / and ok at /health before adding any services.

1. Download and run locally

Download the hello ZIP into a working directory, then open a terminal in that directory:

unzip python-hello.zip
cd python-hello
python3.13 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
gunicorn --bind 0.0.0.0:3000 app:app

Keep it running. In another terminal, curl -fsS http://localhost:3000/health should print ok. Open http://localhost:3000/ and confirm the hello message. Stop the server with Ctrl+C.

The app source is small enough to inspect in full:

.python-version

3.13

requirements.txt

blinker==1.9.0
click==8.5.0
Flask==3.1.3
gunicorn==23.0.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.4
packaging==26.3
Werkzeug==3.1.9

Procfile

web: gunicorn --bind 0.0.0.0:$PORT app:app

app.py

import os
from flask import Flask
app = Flask(__name__)
@app.get('/')
def index():
    return 'Hello from Python on d2o!\n'
@app.get('/health')
def health():
    return 'ok\n'
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.getenv('PORT', '3000')))

Keep the supplied lockfiles in Git. The buildpack uses these manifests and its runtime version declaration to reproduce the app’s dependencies.

2. Create the Environment

Dashboard: open Project Examples → create Environment python, type Development, branch main, release source Build, Automatic deployment on.

CLI:

paas envs create python -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build

3. Create the web app

Dashboard: inside python choose Add Resource → Web Application. Name it notes-web, choose Framework Python, Repository The environment’s shared repository, Directory blank (repository root), and Process type web. Use Port 3000, Health Check Path /health, and one replica. Click Create Resource.

CLI:

paas apps create notes-web --framework python --shared-source --start-command web --port 3000 --health-check-path /health -o "$TUTORIAL_ORG" -p examples -e python

4. Commit and push

Initialize a repository in the unpacked hello directory:

git init -b main
git add .
git commit -m "Add hello application"

Dashboard path: open the Environment’s Git remote panel, copy its shared-repository remote command into this directory, then run its push command. This is the Environment remote, not a per-app remote. The dashboard supplies the correct host and authentication URL.

CLI path: omit -a when setting the shared remote:

paas git remote -o "$TUTORIAL_ORG" -p examples -e python
git push d2o main
paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e python

5. Verify the deployed app

Dashboard: open notes-web → Deployments, wait for the successful build and running instance, then open its public URL. Append /health; it should display ok. CLI: paas ps and paas logs with -o "$TUTORIAL_ORG" -p examples -e python and -a notes-web show the running process. Use the public URL displayed in the dashboard, or read the url field from paas apps info notes-web --json with the same Organization, Project, and Environment flags.

APP_URL=https://your-app-host
curl -fsS "$APP_URL/health"
curl -fsS "$APP_URL/"

Set APP_URL to your actual URL, with no trailing slash. If the build fails, see troubleshooting before continuing.

Next: Persist notes in PostgreSQL.

2. Persist notes in PostgreSQL

Replace hello with the notes checkpoint, attach PostgreSQL, and create the schema once. The Redis and S3 code is present but is not used until you request an export.

1. Replace the source checkpoint

Download the complete notes ZIP beside your hello directory. From inside python-hello, run:

cd ..
unzip python-notes.zip
cp -R python-notes/. python-hello/
cd python-hello
python3.13 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

This retains the hello directory’s .git history and shared remote. The source appendix shows the database implementation. Notes use UUID IDs, validated text, and parameterized SQL or the MongoDB driver; no file on the app instance stores notes. For an optional local run, follow Local services and run python app.py migrate before gunicorn --bind 0.0.0.0:3000 app:app.

2. Create and attach PostgreSQL

Dashboard: in python add a Database named notes-db, engine PostgreSQL, with 1 GB storage. Wait until running. Open notes-web → Config → Attached Resources, select notes-db, leave the variable name blank (DATABASE_URL), and click Attach. In the same Config tab add plain variable DATABASE_ENGINE=postgresql.

CLI:

paas dbs create notes-db --type postgresql --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e python
paas dbs info notes-db -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-web notes-db -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=postgresql -a notes-web -o "$TUTORIAL_ORG" -p examples -e python

Wait for database provisioning before trying to initialize the schema. The attachment injects DATABASE_URL; never copy credentials into the source or .env in Git. Check attachment names with paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e python.

3. Deploy the notes app

git add .
git commit -m "Add persistent notes and export processes"
git push d2o main

Dashboard: wait for notes-web to be running in its Deployments/Overview view. CLI: run paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e python. /health succeeds even before the schema exists; /notes may return 503 until the next step.

4. Initialize the schema

Dashboard: notes-web → Console → select a running instance → Connect. Run:

/cnb/process/migrate

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e python -- /cnb/process/migrate

The migrate process is declared in the Procfile. Calling /cnb/process/migrate loads the buildpack runtime environment, including the language executable and dependencies. Expect Schema ready. The command creates the notes table if missing, so it is safe to repeat for this example. paas run does not relay the remote exit code: inspect the output and verify /notes, rather than assuming a zero CLI exit means the schema succeeded.

5. Check persistence

Open the app URL, enter a sample note, and choose Save note. Refresh; the note remains. You can also test from your terminal:

curl -fsS -H "Content-Type: application/json" -d '{"body":"My first persistent note"}' "$APP_URL/notes"
curl -fsS "$APP_URL/notes"

Restart notes-web from its dashboard action or run paas restart -a notes-web -o "$TUTORIAL_ORG" -p examples -e python. Wait for it to be running and fetch /notes again; the note must still be present. An empty body returns HTTP 400. Leave Export notes for the next chapter.

For production, replace manual schema setup with versioned release-command migrations.

Next: Add a Redis export worker.

3. Add a Redis export worker

The web app queues a job and immediately returns its ID. A separate process reads the notes and generates JSON. This chapter stores that JSON in Redis; the next moves it to S3.

1. Create Redis

Dashboard: in python add Database notes-queue, engine Redis, 1 GB storage; wait until running. In notes-web → Config, attach it with variable name REDIS_URL. Do not use the default DATABASE_URL, which already points at PostgreSQL.

CLI:

paas dbs create notes-queue --type redis --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-web notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e python

2. Create the worker from the same code

Dashboard: add a Background Worker named notes-worker, Framework python (the same selection as the web app), Repository The environment’s shared repository, Directory blank, Process type worker, one replica. A worker has no public HTTP endpoint. Open its Config tab, set DATABASE_ENGINE=postgresql, and attach both notes-db as DATABASE_URL and notes-queue as REDIS_URL.

CLI:

paas apps create notes-worker --worker --framework python --shared-source --process worker -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=postgresql -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-worker notes-db -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-worker notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e python

The worker must have its own attachments; the web app’s configuration is not inherited. The process value is a named buildpack process, not a shell command. See the worker source for the job loop.

3. Push and check the worker

Trigger a shared build after both apps have their configuration:

git commit --allow-empty -m "Deploy web and export worker"
git push d2o main

Dashboard: wait for both apps to run, then open notes-worker → Logs and look for Worker ready. CLI: paas watch -o "$TUTORIAL_ORG" -p examples -e python follows both apps; then use paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python. The web app must still answer /health.

4. Export and recover a queued job

In the browser, click Export notes, wait for the download link, and open the JSON. It must contain your saved note. Logs show Export ready: <id>.

To check queueing while the worker is unavailable, open its dashboard Overview and use − in the Replicas row to reach 0, then confirm the stop, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python. Request an export; it stays queued. Use + in the same row to restore replicas to 1 (or paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python); the same job should complete. If the UI polling times out after 90 seconds, query /exports/<id> and download from /exports/<id>/download once ready, or submit another export.

The worker uses Redis Streams with a consumer group. It acknowledges only after saving the result. A replacement worker claims unacknowledged jobs idle for 30 seconds; writes use the same export ID so a retried job overwrites the same result. Failures remain queued for retry and appear in worker logs. This is at-least-once delivery, not exactly-once delivery. Do not use this loop unchanged for side effects such as charging a payment.

Redis itself is not backed up by the platform. For essential jobs, retain enough information in the primary database to recreate or reconcile them. See durability and recovery and production preparation.

Next: Save exports in object storage.

4. Save exports in object storage

Keep notes in the database and move newly generated JSON exports into a private bucket. The web app streams downloads from S3; browser code never receives bucket credentials.

1. Create the bucket

Dashboard: in python add Object Storage, name notes-exports, tier Capacity, quota 1 GB. Leave it private and wait until provisioned. Capacity is suitable here because exports can be recreated from notes. Use High availability for irreplaceable files.

CLI:

paas buckets create notes-exports --tier capacity --quota-gb 1 -o "$TUTORIAL_ORG" -p examples -e python
paas buckets info -a notes-exports -o "$TUTORIAL_ORG" -p examples -e python

Wait for available: true; keep public: false.

2. Attach the bucket to both apps

Dashboard: open each app’s Config tab, choose bucket notes-exports in the attachment card, leave the credential prefix blank, and click Attach.

CLI:

paas apps attach notes-web notes-exports -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-worker notes-exports -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e python

The primary attachment injects S3_ENDPOINT, S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. The storage implementation passes the endpoint and region explicitly and uses path-style S3 requests. Do not add these credentials to frontend code, Git, or ordinary config variables. Wait for both apps to restart with the new attachment before testing.

3. Generate a new export

Open the app and request a new export. Exports made before the bucket attachment still live in Redis, so their old download links no longer work while S3 mode is enabled. Download the new JSON and confirm your note appears.

Dashboard: open notes-exports → Files → exports/. The file named <job-id>.json should be present. CLI:

paas buckets ls exports/ -a notes-exports -o "$TUTORIAL_ORG" -p examples -e python

A direct anonymous object request should return 403; downloading through the app succeeds because its server uses the attachment credentials. The bucket stays private, but the example app itself has no user authentication. Do not enter confidential data.

4. Verify durability and diagnose failures

Restart notes-worker, submit another export, and check that it completes. Restart notes-web and download the completed export again. No result depends on either app’s local filesystem. If a job stays queued, check worker logs, both apps’ attachment lists, and bucket readiness. After fixing a failed S3 write, the unacknowledged job retries after its 30-second idle interval.

Export files and Redis status records have no expiration in this teaching example. Delete unneeded files in the bucket’s Files tab, or clean up the entire isolated Environment when done.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MariaDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects the same SQL notes table, through its MariaDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in python create Database notes-mariadb, engine MariaDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mariadb --type mariadb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e python
paas dbs info notes-mariadb -o "$TUTORIAL_ORG" -p examples -e python

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mariadb using DATABASE_URL, then set DATABASE_ENGINE=mariadb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e python

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e python
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-web notes-mariadb -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-worker notes-mariadb -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=mariadb -a notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=mariadb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e python -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python. Create a new note identifying MariaDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MongoDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects a notes collection with a unique id index, through its MongoDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in python create Database notes-mongodb, engine MongoDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mongodb --type mongodb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e python
paas dbs info notes-mongodb -o "$TUTORIAL_ORG" -p examples -e python

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mongodb using DATABASE_URL, then set DATABASE_ENGINE=mongodb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e python

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e python
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-web notes-mongodb -o "$TUTORIAL_ORG" -p examples -e python
paas apps attach notes-worker notes-mongodb -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=mongodb -a notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas config set DATABASE_ENGINE=mongodb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e python -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python. Create a new note identifying MongoDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Python and Flask source walkthrough

The runnable source below is included from the same files packaged in the notes download. Lockfiles, configuration, and the shared browser UI are included in the download.

Database

A notes request reaches this adapter after input validation. DATABASE_ENGINE chooses PostgreSQL, MariaDB, or MongoDB; DATABASE_URL comes from the app’s attachment. SQL uses parameters rather than interpolating note text, and MongoDB uses driver operations. The initialization process creates a table or unique index. Records live in the database, so replacing a web instance leaves them available to its replacement.

@contextmanager
def sql():
    url = os.environ['DATABASE_URL']
    if engine == 'postgresql':
        connection = psycopg.connect(url, row_factory=dict_row)
    elif engine == 'mariadb':
        parts = urlparse(url)
        connection = pymysql.connect(host=parts.hostname, port=parts.port or 3306,
            user=unquote(parts.username or ''), password=unquote(parts.password or ''),
            database=parts.path.lstrip('/'), cursorclass=pymysql.cursors.DictCursor)
    else:
        raise ValueError('Unsupported DATABASE_ENGINE')
    try:
        yield connection
        connection.commit()
    finally:
        connection.close()

def collection():
    global mongo
    if mongo is None:
        mongo = MongoClient(os.environ['DATABASE_URL'], serverSelectionTimeoutMS=5000)
    return mongo.get_default_database()['notes']

def migrate():
    if engine == 'mongodb':
        collection().create_index('id', unique=True)
    else:
        with sql() as db, db.cursor() as cursor:
            cursor.execute('CREATE TABLE IF NOT EXISTS notes (id VARCHAR(36) PRIMARY KEY, body TEXT NOT NULL)')
    print('Schema ready', flush=True)

def notes():
    if engine == 'mongodb':
        return list(collection().find({}, {'_id': 0}).sort('id', 1))
    with sql() as db, db.cursor() as cursor:
        cursor.execute('SELECT id, body FROM notes ORDER BY id')
        return list(cursor.fetchall())

def add_note(body):
    note = {'id': str(uuid.uuid4()), 'body': body}
    if engine == 'mongodb':
        collection().insert_one(dict(note))
    else:
        with sql() as db, db.cursor() as cursor:
            cursor.execute('INSERT INTO notes (id, body) VALUES (%s, %s)', (note['id'], body))
    return note

Worker

Creating an export enqueues an ID and returns immediately. This loop reads the notes, writes an export under that ID, records its status, and acknowledges the stream entry. It also reclaims jobs abandoned before acknowledgement. Retrying writes the same export key, so interruption does not create an additional export file; the snapshot can reflect newer notes if they changed before the retry. See worker recovery.

def worker():
    client, consumer = queue(), str(uuid.uuid4())
    try:
        client.xgroup_create('exports', 'workers', id='0', mkstream=True)
    except redis.ResponseError as error:
        if 'BUSYGROUP' not in str(error):
            raise
    stopping = False
    def stop(*_args):
        nonlocal stopping
        stopping = True
    signal.signal(signal.SIGTERM, stop)
    signal.signal(signal.SIGINT, stop)
    print('Worker ready', flush=True)
    while not stopping:
        try:
            messages = client.xautoclaim('exports', 'workers', consumer, 30000, '0-0', count=1)[1]
            if not messages:
                result = client.xreadgroup('workers', consumer, {'exports': '>'}, count=1, block=5000)
                messages = result[0][1] if result else []
            for message_id, fields in messages:
                export_id = fields.get('id', '')
                if not re.fullmatch(r'[0-9a-f-]{36}', export_id):
                    client.xack('exports', 'workers', message_id)
                    continue
                if client.get(f'export:{export_id}') != 'ready':
                    save_export(client, export_id, json.dumps(notes(), indent=2))
                    client.set(f'export:{export_id}', 'ready')
                client.xack('exports', 'workers', message_id)
                client.xdel('exports', message_id)
                print(f'Export ready: {export_id}', flush=True)
        except Exception:
            print('Export failed; unacknowledged jobs retry after 30 seconds. Check attachments and schema.', flush=True)
            time.sleep(1)

Object storage

Without S3 configuration, exports are stored in Redis for the worker checkpoint. With an attached bucket, the worker writes JSON to exports/<id>.json and the web process reads that object for downloads. Both processes need their own bucket attachment. The client uses the supplied endpoint and region with path-style requests. Credentials stay on the server; a private bucket does not add authentication to the example’s public download route.

def storage():
    return boto3.client('s3', endpoint_url=os.environ['S3_ENDPOINT'],
        region_name=os.environ['S3_REGION'], config=Config(s3={'addressing_style': 'path'}))

def save_export(client, export_id, data):
    if os.getenv('S3_BUCKET'):
        storage().put_object(Bucket=os.environ['S3_BUCKET'], Key=f'exports/{export_id}.json',
            Body=data.encode(), ContentType='application/json')
    else:
        client.set(f'export:{export_id}:data', data)

def load_export(client, export_id):
    if os.getenv('S3_BUCKET'):
        return storage().get_object(Bucket=os.environ['S3_BUCKET'],
            Key=f'exports/{export_id}.json')['Body'].read()
    return client.get(f'export:{export_id}:data')

Complete application

The complete source and startup commands are in the notes ZIP linked above. The HTTP layer connects the three components: POST /notes validates and saves a record, GET /notes lists records, POST /exports queues work, and the export status and download routes expose the result. Follow the language’s tutorial sequence to exercise each part, then review production preparation.

Troubleshoot and clean up Python and Flask

Diagnose a failed checkpoint

Keep Procfile at the repository root and commit requirements.txt plus .python-version. Gunicorn must bind 0.0.0.0:$PORT; the worker process is python app.py worker.

Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.

CLI:

paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e python
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e python

Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.

Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.

Clean up

Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.

Dashboard: open Project Examples → Environment python → Settings → Delete Environment, then confirm its name. Make sure this Environment contains only the tutorial resources.

CLI: review its resources, then confirm deletion:

paas apps list -o "$TUTORIAL_ORG" -p examples -e python
paas dbs list -o "$TUTORIAL_ORG" -p examples -e python
paas envs delete python -o "$TUTORIAL_ORG" -p examples --confirm python

This removes the web/worker, primary and optional databases, Redis, and tutorial bucket created in this Environment. If you used local services, run docker compose down -v from the example folder to discard that separate local dataset.

Go: notes and background exports

For an existing Go project, use the shorter Deploying Go guide. This tutorial builds a complete example step by step.

You will use Go 1.27.1 and build a web app named notes-web plus a worker named notes-worker in the examples Project’s go Environment.

The standard library serves HTTP. The database/sql drivers, MongoDB driver, Redis client, and AWS SDK implement the service integrations. The Procfile selects the web or worker mode of the same binary.

Complete Before you start, then follow these chapters in order:

1. Create and deploy hello
2. Persist notes in PostgreSQL
3. Add a Redis export worker
4. Save exports in object storage
5. Try MariaDB or MongoDB instead
6. Prepare for production, or troubleshoot and clean up

Downloads: hello source · complete notes source. The source walkthrough is included directly from those runnable files.

1. Create and deploy a Go hello app

You will see a hello response at / and ok at /health before adding any services.

1. Download and run locally

Download the hello ZIP into a working directory, then open a terminal in that directory:

unzip go-hello.zip
cd go-hello
go mod download
go run . web

Keep it running. In another terminal, curl -fsS http://localhost:3000/health should print ok. Open http://localhost:3000/ and confirm the hello message. Stop the server with Ctrl+C.

The app source is small enough to inspect in full:

go.mod

module example.com/hello

go 1.27.1

Procfile

web: hello

main.go

package main
import ("fmt"; "log"; "net/http"; "os"; "time")
func main() {
 port:=os.Getenv("PORT"); if port=="" {port="3000"}
 mux:=http.NewServeMux()
 mux.HandleFunc("/",func(w http.ResponseWriter,r *http.Request){fmt.Fprintln(w,"Hello from Go on d2o!")})
 mux.HandleFunc("/health",func(w http.ResponseWriter,r *http.Request){fmt.Fprintln(w,"ok")})
 server:=&http.Server{Addr:"0.0.0.0:"+port,Handler:mux,ReadHeaderTimeout:5*time.Second}
 log.Fatal(server.ListenAndServe())
}

Keep the supplied lockfiles in Git. The buildpack uses these manifests and its runtime version declaration to reproduce the app’s dependencies.

2. Create the Environment

Dashboard: open Project Examples → create Environment go, type Development, branch main, release source Build, Automatic deployment on.

CLI:

paas envs create go -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build

3. Create the web app

Dashboard: inside go choose Add Resource → Web Application. Name it notes-web, choose Framework Go, Repository The environment’s shared repository, Directory blank (repository root), and Process type web. Use Port 3000, Health Check Path /health, and one replica. Click Create Resource.

CLI:

paas apps create notes-web --framework go --shared-source --start-command web --port 3000 --health-check-path /health -o "$TUTORIAL_ORG" -p examples -e go

4. Commit and push

Initialize a repository in the unpacked hello directory:

git init -b main
git add .
git commit -m "Add hello application"

Dashboard path: open the Environment’s Git remote panel, copy its shared-repository remote command into this directory, then run its push command. This is the Environment remote, not a per-app remote. The dashboard supplies the correct host and authentication URL.

CLI path: omit -a when setting the shared remote:

paas git remote -o "$TUTORIAL_ORG" -p examples -e go
git push d2o main
paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e go

5. Verify the deployed app

Dashboard: open notes-web → Deployments, wait for the successful build and running instance, then open its public URL. Append /health; it should display ok. CLI: paas ps and paas logs with -o "$TUTORIAL_ORG" -p examples -e go and -a notes-web show the running process. Use the public URL displayed in the dashboard, or read the url field from paas apps info notes-web --json with the same Organization, Project, and Environment flags.

APP_URL=https://your-app-host
curl -fsS "$APP_URL/health"
curl -fsS "$APP_URL/"

Set APP_URL to your actual URL, with no trailing slash. If the build fails, see troubleshooting before continuing.

Next: Persist notes in PostgreSQL.

2. Persist notes in PostgreSQL

Replace hello with the notes checkpoint, attach PostgreSQL, and create the schema once. The Redis and S3 code is present but is not used until you request an export.

1. Replace the source checkpoint

Download the complete notes ZIP beside your hello directory. From inside go-hello, run:

cd ..
unzip go-notes.zip
cp -R go-notes/. go-hello/
cd go-hello
go mod download

This retains the hello directory’s .git history and shared remote. The source appendix shows the database implementation. Notes use UUID IDs, validated text, and parameterized SQL or the MongoDB driver; no file on the app instance stores notes. For an optional local run, follow Local services and run go run . migrate before go run . web.

2. Create and attach PostgreSQL

Dashboard: in go add a Database named notes-db, engine PostgreSQL, with 1 GB storage. Wait until running. Open notes-web → Config → Attached Resources, select notes-db, leave the variable name blank (DATABASE_URL), and click Attach. In the same Config tab add plain variable DATABASE_ENGINE=postgresql.

CLI:

paas dbs create notes-db --type postgresql --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e go
paas dbs info notes-db -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-web notes-db -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=postgresql -a notes-web -o "$TUTORIAL_ORG" -p examples -e go

Wait for database provisioning before trying to initialize the schema. The attachment injects DATABASE_URL; never copy credentials into the source or .env in Git. Check attachment names with paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e go.

3. Deploy the notes app

git add .
git commit -m "Add persistent notes and export processes"
git push d2o main

Dashboard: wait for notes-web to be running in its Deployments/Overview view. CLI: run paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e go. /health succeeds even before the schema exists; /notes may return 503 until the next step.

4. Initialize the schema

Dashboard: notes-web → Console → select a running instance → Connect. Run:

/cnb/process/migrate

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e go -- /cnb/process/migrate

The migrate process is declared in the Procfile. Calling /cnb/process/migrate loads the buildpack runtime environment, including the language executable and dependencies. Expect Schema ready. The command creates the notes table if missing, so it is safe to repeat for this example. paas run does not relay the remote exit code: inspect the output and verify /notes, rather than assuming a zero CLI exit means the schema succeeded.

5. Check persistence

Open the app URL, enter a sample note, and choose Save note. Refresh; the note remains. You can also test from your terminal:

curl -fsS -H "Content-Type: application/json" -d '{"body":"My first persistent note"}' "$APP_URL/notes"
curl -fsS "$APP_URL/notes"

Restart notes-web from its dashboard action or run paas restart -a notes-web -o "$TUTORIAL_ORG" -p examples -e go. Wait for it to be running and fetch /notes again; the note must still be present. An empty body returns HTTP 400. Leave Export notes for the next chapter.

For production, replace manual schema setup with versioned release-command migrations.

Next: Add a Redis export worker.

3. Add a Redis export worker

The web app queues a job and immediately returns its ID. A separate process reads the notes and generates JSON. This chapter stores that JSON in Redis; the next moves it to S3.

1. Create Redis

Dashboard: in go add Database notes-queue, engine Redis, 1 GB storage; wait until running. In notes-web → Config, attach it with variable name REDIS_URL. Do not use the default DATABASE_URL, which already points at PostgreSQL.

CLI:

paas dbs create notes-queue --type redis --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-web notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e go

2. Create the worker from the same code

Dashboard: add a Background Worker named notes-worker, Framework go (the same selection as the web app), Repository The environment’s shared repository, Directory blank, Process type worker, one replica. A worker has no public HTTP endpoint. Open its Config tab, set DATABASE_ENGINE=postgresql, and attach both notes-db as DATABASE_URL and notes-queue as REDIS_URL.

CLI:

paas apps create notes-worker --worker --framework go --shared-source --process worker -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=postgresql -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-worker notes-db -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-worker notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e go

The worker must have its own attachments; the web app’s configuration is not inherited. The process value is a named buildpack process, not a shell command. See the worker source for the job loop.

3. Push and check the worker

Trigger a shared build after both apps have their configuration:

git commit --allow-empty -m "Deploy web and export worker"
git push d2o main

Dashboard: wait for both apps to run, then open notes-worker → Logs and look for Worker ready. CLI: paas watch -o "$TUTORIAL_ORG" -p examples -e go follows both apps; then use paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go. The web app must still answer /health.

4. Export and recover a queued job

In the browser, click Export notes, wait for the download link, and open the JSON. It must contain your saved note. Logs show Export ready: <id>.

To check queueing while the worker is unavailable, open its dashboard Overview and use − in the Replicas row to reach 0, then confirm the stop, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go. Request an export; it stays queued. Use + in the same row to restore replicas to 1 (or paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go); the same job should complete. If the UI polling times out after 90 seconds, query /exports/<id> and download from /exports/<id>/download once ready, or submit another export.

The worker uses Redis Streams with a consumer group. It acknowledges only after saving the result. A replacement worker claims unacknowledged jobs idle for 30 seconds; writes use the same export ID so a retried job overwrites the same result. Failures remain queued for retry and appear in worker logs. This is at-least-once delivery, not exactly-once delivery. Do not use this loop unchanged for side effects such as charging a payment.

Redis itself is not backed up by the platform. For essential jobs, retain enough information in the primary database to recreate or reconcile them. See durability and recovery and production preparation.

Next: Save exports in object storage.

4. Save exports in object storage

Keep notes in the database and move newly generated JSON exports into a private bucket. The web app streams downloads from S3; browser code never receives bucket credentials.

1. Create the bucket

Dashboard: in go add Object Storage, name notes-exports, tier Capacity, quota 1 GB. Leave it private and wait until provisioned. Capacity is suitable here because exports can be recreated from notes. Use High availability for irreplaceable files.

CLI:

paas buckets create notes-exports --tier capacity --quota-gb 1 -o "$TUTORIAL_ORG" -p examples -e go
paas buckets info -a notes-exports -o "$TUTORIAL_ORG" -p examples -e go

Wait for available: true; keep public: false.

2. Attach the bucket to both apps

Dashboard: open each app’s Config tab, choose bucket notes-exports in the attachment card, leave the credential prefix blank, and click Attach.

CLI:

paas apps attach notes-web notes-exports -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-worker notes-exports -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e go

The primary attachment injects S3_ENDPOINT, S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. The storage implementation passes the endpoint and region explicitly and uses path-style S3 requests. Do not add these credentials to frontend code, Git, or ordinary config variables. Wait for both apps to restart with the new attachment before testing.

3. Generate a new export

Open the app and request a new export. Exports made before the bucket attachment still live in Redis, so their old download links no longer work while S3 mode is enabled. Download the new JSON and confirm your note appears.

Dashboard: open notes-exports → Files → exports/. The file named <job-id>.json should be present. CLI:

paas buckets ls exports/ -a notes-exports -o "$TUTORIAL_ORG" -p examples -e go

A direct anonymous object request should return 403; downloading through the app succeeds because its server uses the attachment credentials. The bucket stays private, but the example app itself has no user authentication. Do not enter confidential data.

4. Verify durability and diagnose failures

Restart notes-worker, submit another export, and check that it completes. Restart notes-web and download the completed export again. No result depends on either app’s local filesystem. If a job stays queued, check worker logs, both apps’ attachment lists, and bucket readiness. After fixing a failed S3 write, the unacknowledged job retries after its 30-second idle interval.

Export files and Redis status records have no expiration in this teaching example. Delete unneeded files in the bucket’s Files tab, or clean up the entire isolated Environment when done.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MariaDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects the same SQL notes table, through its MariaDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in go create Database notes-mariadb, engine MariaDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mariadb --type mariadb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e go
paas dbs info notes-mariadb -o "$TUTORIAL_ORG" -p examples -e go

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mariadb using DATABASE_URL, then set DATABASE_ENGINE=mariadb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e go

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e go
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-web notes-mariadb -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-worker notes-mariadb -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=mariadb -a notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=mariadb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e go -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go. Create a new note identifying MariaDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MongoDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects a notes collection with a unique id index, through its MongoDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in go create Database notes-mongodb, engine MongoDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mongodb --type mongodb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e go
paas dbs info notes-mongodb -o "$TUTORIAL_ORG" -p examples -e go

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mongodb using DATABASE_URL, then set DATABASE_ENGINE=mongodb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e go

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e go
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-web notes-mongodb -o "$TUTORIAL_ORG" -p examples -e go
paas apps attach notes-worker notes-mongodb -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=mongodb -a notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas config set DATABASE_ENGINE=mongodb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e go -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go. Create a new note identifying MongoDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Go source walkthrough

The runnable source below is included from the same files packaged in the notes download. Lockfiles, configuration, and the shared browser UI are included in the download.

Database

A notes request reaches this adapter after input validation. DATABASE_ENGINE chooses PostgreSQL, MariaDB, or MongoDB; DATABASE_URL comes from the app’s attachment. SQL uses parameters rather than interpolating note text, and MongoDB uses driver operations. The initialization process creates a table or unique index. Records live in the database, so replacing a web instance leaves them available to its replacement.

func database(ctx context.Context) error {
	dbMu.Lock()
	defer dbMu.Unlock()
	if db != nil || collection != nil {
		return nil
	}
	raw := os.Getenv("DATABASE_URL")
	if raw == "" {
		return errors.New("attach a database first")
	}
	u, err := url.Parse(raw)
	if err != nil {
		return err
	}
	switch engine {
	case "mongodb":
		client, err := mongo.Connect(ctx, options.Client().ApplyURI(raw).SetServerSelectionTimeout(5*time.Second))
		if err != nil {
			return err
		}
		collection = client.Database(strings.TrimPrefix(u.Path, "/")).Collection("notes")
	case "postgresql":
		db, err = sql.Open("pgx", raw)
	case "mariadb":
		c := mysql.NewConfig()
		c.Net = "tcp"
		c.Addr = net.JoinHostPort(u.Hostname(), envPort(u.Port(), "3306"))
		c.DBName = strings.TrimPrefix(u.Path, "/")
		if u.User != nil {
			c.User = u.User.Username()
			c.Passwd, _ = u.User.Password()
		}
		db, err = sql.Open("mysql", c.FormatDSN())
	default:
		return errors.New("unsupported DATABASE_ENGINE")
	}
	if db != nil {
		db.SetMaxOpenConns(5)
	}
	return err
}
func envPort(v, fallback string) string {
	if v == "" {
		return fallback
	}
	return v
}
func migrate(ctx context.Context) error {
	if err := database(ctx); err != nil {
		return err
	}
	if engine == "mongodb" {
		_, err := collection.Indexes().CreateOne(ctx, mongo.IndexModel{Keys: bson.D{{Key: "id", Value: 1}}, Options: options.Index().SetUnique(true)})
		return err
	}
	_, err := db.ExecContext(ctx, "CREATE TABLE IF NOT EXISTS notes (id VARCHAR(36) PRIMARY KEY, body TEXT NOT NULL)")
	return err
}
func notes(ctx context.Context) ([]Note, error) {
	result := []Note{}
	if err := database(ctx); err != nil {
		return nil, err
	}
	if engine == "mongodb" {
		cursor, err := collection.Find(ctx, bson.D{}, options.Find().SetSort(bson.D{{Key: "id", Value: 1}}))
		if err != nil {
			return nil, err
		}
		defer cursor.Close(ctx)
		err = cursor.All(ctx, &result)
		return result, err
	}
	rows, err := db.QueryContext(ctx, "SELECT id, body FROM notes ORDER BY id")
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	for rows.Next() {
		var n Note
		if err = rows.Scan(&n.ID, &n.Body); err != nil {
			return nil, err
		}
		result = append(result, n)
	}
	return result, rows.Err()
}
func addNote(ctx context.Context, body string) (Note, error) {
	n := Note{ID: uuid.NewString(), Body: body}
	if err := database(ctx); err != nil {
		return n, err
	}
	if engine == "mongodb" {
		_, err := collection.InsertOne(ctx, n)
		return n, err
	}
	query := "INSERT INTO notes (id, body) VALUES ($1, $2)"
	if engine == "mariadb" {
		query = "INSERT INTO notes (id, body) VALUES (?, ?)"
	}
	_, err := db.ExecContext(ctx, query, n.ID, n.Body)
	return n, err
}

Worker

Creating an export enqueues an ID and returns immediately. This loop reads the notes, writes an export under that ID, records its status, and acknowledges the stream entry. It also reclaims jobs abandoned before acknowledgement. Retrying writes the same export key, so interruption does not create an additional export file; the snapshot can reflect newer notes if they changed before the retry. See worker recovery.

func worker(ctx context.Context) error {
	q, err := queue()
	if err != nil {
		return err
	}
	defer q.Close()
	err = q.XGroupCreateMkStream(ctx, "exports", "workers", "0").Err()
	if err != nil && !strings.Contains(err.Error(), "BUSYGROUP") {
		return err
	}
	consumer := uuid.NewString()
	log.Print("Worker ready")
	for ctx.Err() == nil {
		messages, _, err := q.XAutoClaim(ctx, &redis.XAutoClaimArgs{Stream: "exports", Group: "workers", Consumer: consumer, MinIdle: 30 * time.Second, Start: "0-0", Count: 1}).Result()
		if err == nil && len(messages) == 0 {
			streams, readErr := q.XReadGroup(ctx, &redis.XReadGroupArgs{Group: "workers", Consumer: consumer, Streams: []string{"exports", ">"}, Count: 1, Block: 5 * time.Second}).Result()
			err = readErr
			if len(streams) > 0 {
				messages = streams[0].Messages
			}
		}
		if errors.Is(err, redis.Nil) {
			continue
		}
		if err == nil {
			for _, message := range messages {
				err = process(ctx, q, message)
				if err != nil {
					break
				}
			}
		}
		if err != nil && ctx.Err() == nil {
			log.Print("Export failed; unacknowledged jobs retry after 30 seconds. Check attachments and schema.")
			time.Sleep(time.Second)
		}
	}
	return nil
}
func process(ctx context.Context, q *redis.Client, message redis.XMessage) error {
	id, _ := message.Values["id"].(string)
	if _, err := uuid.Parse(id); err != nil {
		return q.XAck(ctx, "exports", "workers", message.ID).Err()
	}
	state, err := q.Get(ctx, "export:"+id).Result()
	if err != nil && !errors.Is(err, redis.Nil) {
		return err
	}
	if state != "ready" {
		rows, err := notes(ctx)
		if err != nil {
			return err
		}
		data, err := json.MarshalIndent(rows, "", "  ")
		if err != nil {
			return err
		}
		if err = saveExport(ctx, q, id, data); err != nil {
			return err
		}
		if err = q.Set(ctx, "export:"+id, "ready", 0).Err(); err != nil {
			return err
		}
	}
	if err = q.XAck(ctx, "exports", "workers", message.ID).Err(); err != nil {
		return err
	}
	log.Printf("Export ready: %s", id)
	return q.XDel(ctx, "exports", message.ID).Err()
}

Object storage

Without S3 configuration, exports are stored in Redis for the worker checkpoint. With an attached bucket, the worker writes JSON to exports/<id>.json and the web process reads that object for downloads. Both processes need their own bucket attachment. The client uses the supplied endpoint and region with path-style requests. Credentials stay on the server; a private bucket does not add authentication to the example’s public download route.

func storage(ctx context.Context) (*s3.Client, error) {
	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(os.Getenv("S3_REGION")))
	if err != nil {
		return nil, err
	}
	return s3.NewFromConfig(cfg, func(o *s3.Options) { o.BaseEndpoint = aws.String(os.Getenv("S3_ENDPOINT")); o.UsePathStyle = true }), nil
}
func saveExport(ctx context.Context, q *redis.Client, id string, data []byte) error {
	if os.Getenv("S3_BUCKET") == "" {
		return q.Set(ctx, "export:"+id+":data", data, 0).Err()
	}
	client, err := storage(ctx)
	if err != nil {
		return err
	}
	_, err = client.PutObject(ctx, &s3.PutObjectInput{Bucket: aws.String(os.Getenv("S3_BUCKET")), Key: aws.String("exports/" + id + ".json"), Body: bytes.NewReader(data), ContentType: aws.String("application/json")})
	return err
}
func loadExport(ctx context.Context, q *redis.Client, id string) ([]byte, error) {
	if os.Getenv("S3_BUCKET") == "" {
		return q.Get(ctx, "export:"+id+":data").Bytes()
	}
	client, err := storage(ctx)
	if err != nil {
		return nil, err
	}
	obj, err := client.GetObject(ctx, &s3.GetObjectInput{Bucket: aws.String(os.Getenv("S3_BUCKET")), Key: aws.String("exports/" + id + ".json")})
	if err != nil {
		return nil, err
	}
	defer obj.Body.Close()
	return io.ReadAll(obj.Body)
}

Complete application

The complete source and startup commands are in the notes ZIP linked above. The HTTP layer connects the three components: POST /notes validates and saves a record, GET /notes lists records, POST /exports queues work, and the export status and download routes expose the result. Follow the language’s tutorial sequence to exercise each part, then review production preparation.

Troubleshoot and clean up Go

Diagnose a failed checkpoint

Commit go.mod and go.sum. The module is named example.com/notes, so the built executable is notes on the buildpack PATH, as used in Procfile. Select worker for the background app, not web.

Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.

CLI:

paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e go
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e go

Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.

Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.

Clean up

Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.

Dashboard: open Project Examples → Environment go → Settings → Delete Environment, then confirm its name. Make sure this Environment contains only the tutorial resources.

CLI: review its resources, then confirm deletion:

paas apps list -o "$TUTORIAL_ORG" -p examples -e go
paas dbs list -o "$TUTORIAL_ORG" -p examples -e go
paas envs delete go -o "$TUTORIAL_ORG" -p examples --confirm go

This removes the web/worker, primary and optional databases, Redis, and tutorial bucket created in this Environment. If you used local services, run docker compose down -v from the example folder to discard that separate local dataset.

Rust and Axum: notes and background exports

You will use Rust 1.99.0 through rustup and build a web app named notes-web plus a worker named notes-worker in the examples Project’s rust Environment.

Axum serves HTTP. SQLx, the MongoDB driver, Redis client, and AWS SDK provide service integrations. Cargo builds separate web, worker, and migrate binaries; their names become buildpack process types. Commit Cargo.lock: the Rust builder requires it for detection.

Complete Before you start, then follow these chapters in order:

1. Create and deploy hello
2. Persist notes in PostgreSQL
3. Add a Redis export worker
4. Save exports in object storage
5. Try MariaDB or MongoDB instead
6. Prepare for production, or troubleshoot and clean up

Downloads: hello source · complete notes source. The source walkthrough is included directly from those runnable files.

1. Create and deploy a Rust and Axum hello app

You will see a hello response at / and ok at /health before adding any services.

1. Download and run locally

Download the hello ZIP into a working directory, then open a terminal in that directory:

unzip rust-hello.zip
cd rust-hello
cargo build --locked
cargo run --locked

Keep it running. In another terminal, curl -fsS http://localhost:3000/health should print ok. Open http://localhost:3000/ and confirm the hello message. Stop the server with Ctrl+C.

The app source is small enough to inspect in full:

Cargo.toml

[package]
name = "web"
version = "0.1.0"
edition = "2024"
[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

rust-toolchain.toml

[toolchain]
channel = "1.99.0"
profile = "minimal"

src/main.rs

use axum::{Router, routing::get};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = Router::new()
        .route("/", get(|| async { "Hello from Rust on d2o!\n" }))
        .route("/health", get(|| async { "ok\n" }));
    let port = std::env::var("PORT").unwrap_or_else(|_| "3000".into());
    let listener = tokio::net::TcpListener::bind(format!("0.0.0.0:{port}")).await?;
    axum::serve(listener, app).await?;
    Ok(())
}

Keep the supplied lockfiles in Git. The buildpack uses these manifests and its runtime version declaration to reproduce the app’s dependencies.

2. Create the Environment

Dashboard: open Project Examples → create Environment rust, type Development, branch main, release source Build, Automatic deployment on.

CLI:

paas envs create rust -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build

3. Create the web app

Dashboard: inside rust choose Add Resource → Web Application. Name it notes-web, choose Framework Rust, Repository The environment’s shared repository, Directory blank (repository root), and Process type web. Use Port 3000, Health Check Path /health, and one replica. Click Create Resource.

CLI:

paas apps create notes-web --framework rust --shared-source --start-command web --port 3000 --health-check-path /health -o "$TUTORIAL_ORG" -p examples -e rust

4. Commit and push

Initialize a repository in the unpacked hello directory:

git init -b main
git add .
git commit -m "Add hello application"

Dashboard path: open the Environment’s Git remote panel, copy its shared-repository remote command into this directory, then run its push command. This is the Environment remote, not a per-app remote. The dashboard supplies the correct host and authentication URL.

CLI path: omit -a when setting the shared remote:

paas git remote -o "$TUTORIAL_ORG" -p examples -e rust
git push d2o main
paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust

5. Verify the deployed app

Dashboard: open notes-web → Deployments, wait for the successful build and running instance, then open its public URL. Append /health; it should display ok. CLI: paas ps and paas logs with -o "$TUTORIAL_ORG" -p examples -e rust and -a notes-web show the running process. Use the public URL displayed in the dashboard, or read the url field from paas apps info notes-web --json with the same Organization, Project, and Environment flags.

APP_URL=https://your-app-host
curl -fsS "$APP_URL/health"
curl -fsS "$APP_URL/"

Set APP_URL to your actual URL, with no trailing slash. If the build fails, see troubleshooting before continuing.

Next: Persist notes in PostgreSQL.

2. Persist notes in PostgreSQL

Replace hello with the notes checkpoint, attach PostgreSQL, and create the schema once. The Redis and S3 code is present but is not used until you request an export.

1. Replace the source checkpoint

Download the complete notes ZIP beside your hello directory. From inside rust-hello, run:

cd ..
unzip rust-notes.zip
cp -R rust-notes/. rust-hello/
cd rust-hello
rm src/main.rs
cargo build --locked

This retains the hello directory’s .git history and shared remote. The rm command removes only the superseded hello source file in this tutorial directory. The source appendix shows the database implementation. Notes use UUID IDs, validated text, and parameterized SQL or the MongoDB driver; no file on the app instance stores notes. For an optional local run, follow Local services and run cargo run --locked --bin migrate before cargo run --locked --bin web.

2. Create and attach PostgreSQL

Dashboard: in rust add a Database named notes-db, engine PostgreSQL, with 1 GB storage. Wait until running. Open notes-web → Config → Attached Resources, select notes-db, leave the variable name blank (DATABASE_URL), and click Attach. In the same Config tab add plain variable DATABASE_ENGINE=postgresql.

CLI:

paas dbs create notes-db --type postgresql --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rust
paas dbs info notes-db -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-web notes-db -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=postgresql -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust

Wait for database provisioning before trying to initialize the schema. The attachment injects DATABASE_URL; never copy credentials into the source or .env in Git. Check attachment names with paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rust.

3. Deploy the notes app

git add .
git commit -m "Add persistent notes and export processes"
git push d2o main

Dashboard: wait for notes-web to be running in its Deployments/Overview view. CLI: run paas watch -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust. /health succeeds even before the schema exists; /notes may return 503 until the next step.

4. Initialize the schema

Dashboard: notes-web → Console → select a running instance → Connect. Run:

/cnb/process/migrate

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust -- /cnb/process/migrate

Expect Schema ready. The command creates the notes table if missing, so it is safe to repeat for this example. paas run does not relay the remote exit code: inspect the output and verify /notes, rather than assuming a zero CLI exit means the schema succeeded.

5. Check persistence

Open the app URL, enter a sample note, and choose Save note. Refresh; the note remains. You can also test from your terminal:

curl -fsS -H "Content-Type: application/json" -d '{"body":"My first persistent note"}' "$APP_URL/notes"
curl -fsS "$APP_URL/notes"

Restart notes-web from its dashboard action or run paas restart -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust. Wait for it to be running and fetch /notes again; the note must still be present. An empty body returns HTTP 400. Leave Export notes for the next chapter.

For production, replace manual schema setup with versioned release-command migrations.

Next: Add a Redis export worker.

3. Add a Redis export worker

The web app queues a job and immediately returns its ID. A separate process reads the notes and generates JSON. This chapter stores that JSON in Redis; the next moves it to S3.

1. Create Redis

Dashboard: in rust add Database notes-queue, engine Redis, 1 GB storage; wait until running. In notes-web → Config, attach it with variable name REDIS_URL. Do not use the default DATABASE_URL, which already points at PostgreSQL.

CLI:

paas dbs create notes-queue --type redis --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-web notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e rust

2. Create the worker from the same code

Dashboard: add a Background Worker named notes-worker, Framework rust (the same selection as the web app), Repository The environment’s shared repository, Directory blank, Process type worker, one replica. A worker has no public HTTP endpoint. Open its Config tab, set DATABASE_ENGINE=postgresql, and attach both notes-db as DATABASE_URL and notes-queue as REDIS_URL.

CLI:

paas apps create notes-worker --worker --framework rust --shared-source --process worker -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=postgresql -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-worker notes-db -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-worker notes-queue --env-var REDIS_URL -o "$TUTORIAL_ORG" -p examples -e rust

The worker must have its own attachments; the web app’s configuration is not inherited. The process value is a named buildpack process, not a shell command. See the worker source for the job loop.

3. Push and check the worker

Trigger a shared build after both apps have their configuration:

git commit --allow-empty -m "Deploy web and export worker"
git push d2o main

Dashboard: wait for both apps to run, then open notes-worker → Logs and look for Worker ready. CLI: paas watch -o "$TUTORIAL_ORG" -p examples -e rust follows both apps; then use paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust. The web app must still answer /health.

4. Export and recover a queued job

In the browser, click Export notes, wait for the download link, and open the JSON. It must contain your saved note. Logs show Export ready: <id>.

To check queueing while the worker is unavailable, open its dashboard Overview and use − in the Replicas row to reach 0, then confirm the stop, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust. Request an export; it stays queued. Use + in the same row to restore replicas to 1 (or paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust); the same job should complete. If the UI polling times out after 90 seconds, query /exports/<id> and download from /exports/<id>/download once ready, or submit another export.

The worker uses Redis Streams with a consumer group. It acknowledges only after saving the result. A replacement worker claims unacknowledged jobs idle for 30 seconds; writes use the same export ID so a retried job overwrites the same result. Failures remain queued for retry and appear in worker logs. This is at-least-once delivery, not exactly-once delivery. Do not use this loop unchanged for side effects such as charging a payment.

Redis itself is not backed up by the platform. For essential jobs, retain enough information in the primary database to recreate or reconcile them. See durability and recovery and production preparation.

Next: Save exports in object storage.

4. Save exports in object storage

Keep notes in the database and move newly generated JSON exports into a private bucket. The web app streams downloads from S3; browser code never receives bucket credentials.

1. Create the bucket

Dashboard: in rust add Object Storage, name notes-exports, tier Capacity, quota 1 GB. Leave it private and wait until provisioned. Capacity is suitable here because exports can be recreated from notes. Use High availability for irreplaceable files.

CLI:

paas buckets create notes-exports --tier capacity --quota-gb 1 -o "$TUTORIAL_ORG" -p examples -e rust
paas buckets info -a notes-exports -o "$TUTORIAL_ORG" -p examples -e rust

Wait for available: true; keep public: false.

2. Attach the bucket to both apps

Dashboard: open each app’s Config tab, choose bucket notes-exports in the attachment card, leave the credential prefix blank, and click Attach.

CLI:

paas apps attach notes-web notes-exports -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-worker notes-exports -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

The primary attachment injects S3_ENDPOINT, S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. The storage implementation passes the endpoint and region explicitly and uses path-style S3 requests. Do not add these credentials to frontend code, Git, or ordinary config variables. Wait for both apps to restart with the new attachment before testing.

3. Generate a new export

Open the app and request a new export. Exports made before the bucket attachment still live in Redis, so their old download links no longer work while S3 mode is enabled. Download the new JSON and confirm your note appears.

Dashboard: open notes-exports → Files → exports/. The file named <job-id>.json should be present. CLI:

paas buckets ls exports/ -a notes-exports -o "$TUTORIAL_ORG" -p examples -e rust

A direct anonymous object request should return 403; downloading through the app succeeds because its server uses the attachment credentials. The bucket stays private, but the example app itself has no user authentication. Do not enter confidential data.

4. Verify durability and diagnose failures

Restart notes-worker, submit another export, and check that it completes. Restart notes-web and download the completed export again. No result depends on either app’s local filesystem. If a job stays queued, check worker logs, both apps’ attachment lists, and bucket readiness. After fixing a failed S3 write, the unacknowledged job retries after its 30-second idle interval.

Export files and Redis status records have no expiration in this teaching example. Delete unneeded files in the bucket’s Files tab, or clean up the entire isolated Environment when done.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MariaDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects the same SQL notes table, through its MariaDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in rust create Database notes-mariadb, engine MariaDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mariadb --type mariadb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rust
paas dbs info notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rust

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mariadb using DATABASE_URL, then set DATABASE_ENGINE=mariadb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rust
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-web notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-worker notes-mariadb -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=mariadb -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=mariadb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust. Create a new note identifying MariaDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Optional: persist notes in MongoDB

This chapter replaces the primary PostgreSQL attachment. It uses the same web routes, Redis queue, worker, and object-storage integration. The app selects a notes collection with a unique id index, through its MongoDB driver. This is a fresh dataset, not an automatic migration of your PostgreSQL notes.

1. Create the alternative database

Dashboard: in rust create Database notes-mongodb, engine MongoDB, 1 GB storage. Wait until running. CLI:

paas dbs create notes-mongodb --type mongodb --storage-gb 1 -o "$TUTORIAL_ORG" -p examples -e rust
paas dbs info notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rust

2. Pause traffic and change both apps

Finish outstanding exports, then stop using the sample app while changing stores. On the worker’s Overview, use − in Replicas to reach zero and confirm, or run paas scale 0 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust.

Dashboard: for both notes-web and notes-worker, open Config and detach only the current primary database (DATABASE_URL). Attach notes-mongodb using DATABASE_URL, then set DATABASE_ENGINE=mongodb. Keep Redis and bucket attachments.

CLI: list each app’s attachments and copy the ID for its primary database:

paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

Replace the two placeholders below with the attachment IDs, which differ per app and are not the database resource ID:

paas apps detach notes-web <web-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rust
paas apps detach notes-worker <worker-primary-attachment-id> -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-web notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attach notes-worker notes-mongodb -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=mongodb -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas config set DATABASE_ENGINE=mongodb -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

Do not keep a plain DATABASE_URL variable that could override the injected attachment. Changing attachments/config rolls out the app automatically; wait until the web process is running. See attachments and configuration precedence.

3. Initialize and verify

Dashboard: run /cnb/process/migrate in notes-web’s Console.

CLI:

paas run -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust -- /cnb/process/migrate

Expect Schema ready. Restore the worker to one replica using + on Overview or with paas scale 1 -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust. Create a new note identifying MongoDB, restart the web app, and verify it remains. Generate a new export and confirm the new note appears in the JSON. Previously generated export files are snapshots of the old store; they do not change.

To return to PostgreSQL, repeat the attachment change for notes-db and set DATABASE_ENGINE=postgresql on both apps. Your earlier PostgreSQL notes remain there until you explicitly delete that database. Each engine can be followed independently; you do not have to finish the other optional chapter first.

Continue with MariaDB or MongoDB if you want to compare primary stores. Each is optional and starts a separate dataset. Then prepare the app for production or clean up the tutorial resources.

Rust and Axum source walkthrough

The runnable source below is included from the same files packaged in the notes download. Lockfiles, configuration, and the shared browser UI are included in the download.

Database

A notes request reaches this adapter after input validation. DATABASE_ENGINE chooses PostgreSQL, MariaDB, or MongoDB; DATABASE_URL comes from the app’s attachment. SQL uses parameters rather than interpolating note text, and MongoDB uses driver operations. The initialization process creates a table or unique index. Records live in the database, so replacing a web instance leaves them available to its replacement.

#![allow(unused)]
fn main() {
enum Database {
    Postgres(PgPool),
    Maria(MySqlPool),
    Mongo(Collection<Document>),
}
static DATABASE: OnceCell<Database> = OnceCell::const_new();
async fn database() -> Result<&'static Database> {
    DATABASE
        .get_or_try_init(|| async {
            let url = std::env::var("DATABASE_URL").context("Attach a database first")?;
            Ok(match env("DATABASE_ENGINE", "postgresql").as_str() {
                "postgresql" => Database::Postgres(
                    sqlx::postgres::PgPoolOptions::new()
                        .max_connections(5)
                        .connect(&url)
                        .await?,
                ),
                "mariadb" => Database::Maria(
                    sqlx::mysql::MySqlPoolOptions::new()
                        .max_connections(5)
                        .connect(&url)
                        .await?,
                ),
                "mongodb" => {
                    let client = mongodb::Client::with_uri_str(&url).await?;
                    Database::Mongo(
                        client
                            .default_database()
                            .context("DATABASE_URL needs a database name")?
                            .collection("notes"),
                    )
                }
                _ => anyhow::bail!("Unsupported DATABASE_ENGINE"),
            })
        })
        .await
}
pub async fn migrate() -> Result<()> {
    let query = "CREATE TABLE IF NOT EXISTS notes (id VARCHAR(36) PRIMARY KEY, body TEXT NOT NULL)";
    match database().await? {
        Database::Postgres(db) => {
            sqlx::query(query).execute(db).await?;
        }
        Database::Maria(db) => {
            sqlx::query(query).execute(db).await?;
        }
        Database::Mongo(db) => {
            db.create_index(
                IndexModel::builder()
                    .keys(doc! {"id": 1})
                    .options(IndexOptions::builder().unique(true).build())
                    .build(),
            )
            .await?;
        }
    }
    Ok(())
}
pub async fn notes() -> Result<Vec<Note>> {
    Ok(match database().await? {
        Database::Postgres(db) => sqlx::query("SELECT id, body FROM notes ORDER BY id")
            .fetch_all(db)
            .await?
            .into_iter()
            .map(|r| Note {
                id: r.get("id"),
                body: r.get("body"),
            })
            .collect(),
        Database::Maria(db) => sqlx::query("SELECT id, body FROM notes ORDER BY id")
            .fetch_all(db)
            .await?
            .into_iter()
            .map(|r| Note {
                id: r.get("id"),
                body: r.get("body"),
            })
            .collect(),
        Database::Mongo(db) => db
            .find(doc! {})
            .sort(doc! {"id":1})
            .await?
            .try_collect::<Vec<_>>()
            .await?
            .into_iter()
            .map(|d| {
                Ok(Note {
                    id: d.get_str("id")?.into(),
                    body: d.get_str("body")?.into(),
                })
            })
            .collect::<Result<Vec<_>>>()?,
    })
}
pub async fn add_note(body: String) -> Result<Note> {
    let note = Note {
        id: uuid::Uuid::new_v4().to_string(),
        body,
    };
    match database().await? {
        Database::Postgres(db) => {
            sqlx::query("INSERT INTO notes (id, body) VALUES ($1, $2)")
                .bind(&note.id)
                .bind(&note.body)
                .execute(db)
                .await?;
        }
        Database::Maria(db) => {
            sqlx::query("INSERT INTO notes (id, body) VALUES (?, ?)")
                .bind(&note.id)
                .bind(&note.body)
                .execute(db)
                .await?;
        }
        Database::Mongo(db) => {
            db.insert_one(doc! {"id":&note.id,"body":&note.body})
                .await?;
        }
    }
    Ok(note)
}
}

Worker

Creating an export enqueues an ID and returns immediately. This loop reads the notes, writes an export under that ID, records its status, and acknowledges the stream entry. It also reclaims jobs abandoned before acknowledgement. Retrying writes the same export key, so interruption does not create an additional export file; the snapshot can reflect newer notes if they changed before the retry. See worker recovery.

#![allow(unused)]
fn main() {
async fn process(q: &mut Queue, message: Message) -> Result<()> {
    let (message_id, fields) = message;
    let id = fields
        .chunks_exact(2)
        .find(|pair| pair[0] == "id")
        .map(|pair| pair[1].clone())
        .unwrap_or_default();
    if uuid::Uuid::parse_str(&id).is_ok() {
        if status(q, &id).await?.as_deref() != Some("ready") {
            save_export(q, &id, serde_json::to_vec_pretty(&notes().await?)?).await?;
            redis::cmd("SET")
                .arg(format!("export:{id}"))
                .arg("ready")
                .query_async::<()>(q)
                .await?;
        }
        println!("Export ready: {id}");
    }
    redis::cmd("XACK")
        .arg("exports")
        .arg("workers")
        .arg(&message_id)
        .query_async::<i64>(q)
        .await?;
    redis::cmd("XDEL")
        .arg("exports")
        .arg(message_id)
        .query_async::<i64>(q)
        .await?;
    Ok(())
}
async fn next(q: &mut Queue, consumer: &str) -> Result<()> {
    let (_, mut messages, _): (String, Vec<Message>, Vec<String>) = redis::cmd("XAUTOCLAIM")
        .arg("exports")
        .arg("workers")
        .arg(consumer)
        .arg(30000)
        .arg("0-0")
        .arg("COUNT")
        .arg(1)
        .query_async(q)
        .await?;
    if messages.is_empty() {
        let reply: ReadReply = redis::cmd("XREADGROUP")
            .arg("GROUP")
            .arg("workers")
            .arg(consumer)
            .arg("COUNT")
            .arg(1)
            .arg("BLOCK")
            .arg(5000)
            .arg("STREAMS")
            .arg("exports")
            .arg(">")
            .query_async(q)
            .await?;
        messages = reply
            .and_then(|mut streams| streams.pop().map(|(_, messages)| messages))
            .unwrap_or_default();
    }
    for message in messages {
        process(q, message).await?;
    }
    Ok(())
}
async fn run() -> Result<()> {
    let mut q = queue().await?;
    let group = redis::cmd("XGROUP")
        .arg("CREATE")
        .arg("exports")
        .arg("workers")
        .arg("0")
        .arg("MKSTREAM")
        .query_async::<()>(&mut q)
        .await;
    if let Err(error) = group {
        if !error.to_string().contains("BUSYGROUP") {
            return Err(error.into());
        }
    }
    let consumer = uuid::Uuid::new_v4().to_string();
    println!("Worker ready");
    let stop = shutdown();
    tokio::pin!(stop);
    loop {
        tokio::select! {
            _ = &mut stop => return Ok(()),
            result = next(&mut q, &consumer) => {
                if result.is_err() {
                    eprintln!("Export failed; unacknowledged jobs retry after 30 seconds. Check attachments and schema.");
                    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
                    if let Ok(connection) = queue().await { q = connection; }
                }
            }
        }
    }
}
}

Object storage

Without S3 configuration, exports are stored in Redis for the worker checkpoint. With an attached bucket, the worker writes JSON to exports/<id>.json and the web process reads that object for downloads. Both processes need their own bucket attachment. The client uses the supplied endpoint and region with path-style requests. Credentials stay on the server; a private bucket does not add authentication to the example’s public download route.

#![allow(unused)]
fn main() {
async fn storage() -> Result<aws_sdk_s3::Client> {
    let shared = aws_config::defaults(aws_config::BehaviorVersion::latest())
        .region(aws_config::Region::new(std::env::var("S3_REGION")?))
        .load()
        .await;
    let config = aws_sdk_s3::config::Builder::from(&shared)
        .endpoint_url(std::env::var("S3_ENDPOINT")?)
        .force_path_style(true)
        .build();
    Ok(aws_sdk_s3::Client::from_conf(config))
}
pub async fn save_export(q: &mut Queue, id: &str, data: Vec<u8>) -> Result<()> {
    if let Ok(bucket) = std::env::var("S3_BUCKET") {
        storage()
            .await?
            .put_object()
            .bucket(bucket)
            .key(format!("exports/{id}.json"))
            .content_type("application/json")
            .body(aws_sdk_s3::primitives::ByteStream::from(data))
            .send()
            .await?;
    } else {
        redis::cmd("SET")
            .arg(format!("export:{id}:data"))
            .arg(data)
            .query_async::<()>(q)
            .await?;
    }
    Ok(())
}
pub async fn load_export(q: &mut Queue, id: &str) -> Result<Vec<u8>> {
    if let Ok(bucket) = std::env::var("S3_BUCKET") {
        let output = storage()
            .await?
            .get_object()
            .bucket(bucket)
            .key(format!("exports/{id}.json"))
            .send()
            .await?;
        Ok(output.body.collect().await?.into_bytes().to_vec())
    } else {
        Ok(redis::cmd("GET")
            .arg(format!("export:{id}:data"))
            .query_async(q)
            .await?)
    }
}
}

HTTP routes

use axum::{
    Json, Router,
    extract::Path,
    http::{StatusCode, header},
    response::{Html, IntoResponse, Response},
    routing::{get, post},
};
use d2o_notes::*;
use serde_json::{Value, json};

struct Unavailable;
impl From<anyhow::Error> for Unavailable {
    fn from(_: anyhow::Error) -> Self {
        Self
    }
}
impl IntoResponse for Unavailable {
    fn into_response(self) -> Response {
        (
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({"error":"Check attachments, schema, and service availability"})),
        )
            .into_response()
    }
}
async fn list() -> Result<Json<Vec<Note>>, Unavailable> {
    Ok(Json(notes().await?))
}
async fn create(Json(input): Json<Value>) -> Result<Response, Unavailable> {
    let Some(body) = input
        .get("body")
        .and_then(Value::as_str)
        .filter(|s| !s.trim().is_empty() && s.chars().count() <= 2000)
    else {
        return Ok((
            StatusCode::BAD_REQUEST,
            Json(json!({"error":"Enter a note of 1–2000 characters"})),
        )
            .into_response());
    };
    Ok((StatusCode::CREATED, Json(add_note(body.into()).await?)).into_response())
}
async fn export() -> Result<Response, Unavailable> {
    Ok((StatusCode::ACCEPTED, Json(json!({"id":enqueue().await?}))).into_response())
}
async fn export_status(Path(id): Path<String>) -> Result<Response, Unavailable> {
    let state = status(&mut queue().await?, &id).await?;
    Ok((
        if state.is_some() {
            StatusCode::OK
        } else {
            StatusCode::NOT_FOUND
        },
        Json(json!({"status":state.unwrap_or("unknown".into())})),
    )
        .into_response())
}
async fn download(Path(id): Path<String>) -> Result<Response, Unavailable> {
    let mut q = queue().await?;
    if uuid::Uuid::parse_str(&id).is_err() || status(&mut q, &id).await?.as_deref() != Some("ready")
    {
        return Ok((
            StatusCode::NOT_FOUND,
            Json(json!({"error":"Export not ready"})),
        )
            .into_response());
    }
    Ok((
        [
            (header::CONTENT_TYPE, "application/json"),
            (
                header::CONTENT_DISPOSITION,
                "attachment; filename=notes.json",
            ),
        ],
        load_export(&mut q, &id).await?,
    )
        .into_response())
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = Router::new()
        .route(
            "/",
            get(|| async { Html(include_str!("../public/index.html")) }),
        )
        .route("/health", get(|| async { "ok\n" }))
        .route("/notes", get(list).post(create))
        .route("/exports", post(export))
        .route("/exports/{id}", get(export_status))
        .route("/exports/{id}/download", get(download))
        .layer(axum::extract::DefaultBodyLimit::max(16384));
    let listener =
        tokio::net::TcpListener::bind(format!("0.0.0.0:{}", env("PORT", "3000"))).await?;
    println!("Web ready");
    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown())
        .await?;
    Ok(())
}

Review production preparation before adapting these handlers to real users.

Troubleshoot and clean up Rust and Axum

Diagnose a failed checkpoint

Both Cargo.toml and Cargo.lock must be at the source root. Commit rust-toolchain.toml. Set Process type web or worker to match the compiled binary names; /cnb/process/migrate selects the migration binary inside the image.

Dashboard: inspect the app’s Deployments, Logs, and Config tabs. The Process field is also editable under Settings; clearing it restores the buildpack’s default process.

CLI:

paas ps -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas logs -a notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas logs -a notes-worker -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-web -o "$TUTORIAL_ORG" -p examples -e rust
paas apps attachments notes-worker -o "$TUTORIAL_ORG" -p examples -e rust

Do not print connection strings or credentials into logs. The example’s error responses identify the failing checkpoint without exposing a password.

Before deleting the example, review Take an Example to Production if you plan to adapt it. For platform-wide symptoms, see Troubleshooting & FAQ.

Clean up

Keep anything you want to retain by downloading exports first. Deleting this tutorial Environment permanently removes its apps and data resources; it is not a way to pause them.

Dashboard: open Project Examples → Environment rust → Settings → Delete Environment, then confirm its name. Make sure this Environment contains only the tutorial resources.

CLI: review its resources, then confirm deletion:

paas apps list -o "$TUTORIAL_ORG" -p examples -e rust
paas dbs list -o "$TUTORIAL_ORG" -p examples -e rust
paas envs delete rust -o "$TUTORIAL_ORG" -p examples --confirm rust

This removes the web/worker, primary and optional databases, Redis, and tutorial bucket created in this Environment. If you used local services, run docker compose down -v from the example folder to discard that separate local dataset.

Static HTML with NGINX and a public asset

Build a small site from HTML and an NGINX configuration, then display a public image from object storage. Complete Before you start first. For an existing frontend project, use Deploying Static Sites. This path uses no language runtime, database, or background worker.

1. Download and inspect the site

Download the static site ZIP, then run:

unzip static-site.zip
cd static-site

The HTML lives in public/index.html:

<!doctype html>
<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>Hello from d2o</title><h1>Hello from Static Files on d2o!</h1>
<p>Edit this page and push again to deploy an update.</p>
<!-- In the object storage chapter, add an img with your public asset URL. -->
</html>

The buildpack detects the root nginx.conf. Its {{port}} template reads the app’s runtime PORT, while its web root points at the packaged public directory. This example deliberately adds /health; a basic static site can instead use the guide’s default configuration and health path /:

worker_processes 1;
daemon off;
error_log stderr;
events { worker_connections 1024; }
http {
  types {
    text/html html;
    text/css css;
    application/javascript js;
    application/json json;
    image/png png;
    image/jpeg jpg jpeg;
    image/svg+xml svg;
    image/x-icon ico;
  }
  default_type application/octet-stream;
  access_log /dev/stdout;
  client_body_temp_path /tmp/client_body;
  server {
    listen {{port}};
    root /workspace/public;
    location = /health { default_type text/plain; return 200 "ok\n"; }
    location / { try_files $uri $uri/ =404; }
  }
}

To preview just the HTML locally, run python3 -m http.server 3000 --directory public and open http://localhost:3000. This preview does not test NGINX’s template or /health; the deployed image does. Stop it with Ctrl+C before continuing.

2. Create the Environment and app

Dashboard: in Project Examples, create Environment static, type Development, branch main, Automatic deployment on, release source Build. Add a Web Application named site, Framework Static Files, Repository The environment’s shared repository, Directory blank, Process type blank (use the buildpack default), Port 3000, and Health Check Path /health.

CLI:

paas envs create static -o "$TUTORIAL_ORG" -p examples --type development --branch main --release-source build
paas apps create site -o "$TUTORIAL_ORG" -p examples -e static --framework static --shared-source --port 3000 --health-check-path /health

3. Push and verify

git init -b main
git add .
git commit -m "Add static site"

Dashboard path: copy the shared remote command from the Environment’s Git remote panel into this directory, then run its push command. Wait for the app’s successful Deployment and open its public URL.

CLI path:

paas git remote -o "$TUTORIAL_ORG" -p examples -e static
git push d2o main
paas watch -o "$TUTORIAL_ORG" -p examples -e static -a site

Read the public URL in the dashboard, or the url field from paas apps info site --json -o "$TUTORIAL_ORG" -p examples -e static. Open the site, then append /health to its URL; expect ok. A 404 on /health suggests the root NGINX configuration was not packaged or the wrong source directory was selected.

4. Create and upload a public asset

Choose a small image that is safe for anyone to view, saved locally as banner.png. Use a separate bucket containing only public demo assets.

Dashboard: in static, add Object Storage site-assets, tier Capacity, quota 1 GB. Wait for provisioning. In its Files tab upload banner.png. On Overview choose Make public and confirm that every object will be publicly readable. Back in Files, use Copy URL on the image.

CLI: create the private bucket and wait for available: true:

paas buckets create site-assets -o "$TUTORIAL_ORG" -p examples -e static --tier capacity --quota-gb 1
paas buckets info -o "$TUTORIAL_ORG" -p examples -e static -a site-assets

Upload with the CLI, then explicitly make this demo bucket public:

paas buckets put banner.png banner.png --content-type image/png -o "$TUTORIAL_ORG" -p examples -e static -a site-assets
paas buckets visibility public -o "$TUTORIAL_ORG" -p examples -e static -a site-assets
paas buckets url -o "$TUTORIAL_ORG" -p examples -e static -a site-assets

Append /banner.png to the printed public bucket URL. For other S3 tools, see using the AWS CLI.

5. Display the asset

Add this inside public/index.html, replacing the URL with the image’s actual public URL:

<img src="https://your-bucket-host/banner.png" alt="Tutorial banner" width="640">

git add public/index.html
git commit -m "Show public bucket asset"
git push d2o main

Wait for the new Deployment, refresh the site, and confirm the image loads in a private browser window. DevTools should show only the public object URL, with no S3 credentials. There is no need to attach the bucket to the static app. Browser JavaScript must never contain database connection strings or private bucket keys. Use a server-side tutorial when you need authenticated uploads, private downloads, or database queries.

6. Troubleshoot and clean up

If the build cannot detect a web server, check that nginx.conf is at the source root and public/index.html is committed. If the image returns 403, confirm the object key and that this demo bucket is public. If the app fails health checks, confirm Port 3000 and the {{port}} template. View build status in Deployments and runtime errors in Logs, or use paas logs -o "$TUTORIAL_ORG" -p examples -e static -a site.

When done, delete the isolated static Environment in the dashboard’s Environment Settings, or run the command below after confirming it contains only this tutorial. This permanently removes both the site and its bucket data:

paas envs delete static -o "$TUTORIAL_ORG" -p examples --confirm static

Next: Take an Example to Production, including public asset handling and storage recovery.

Take an Example to Production

The tutorials teach deployment, persistence, workers, and object storage. Their notes UI has no authentication, and exports and job records have no retention policy. Complete these steps before using an example with real users or sensitive data.

1. Establish application boundaries

Add authentication and authorization to notes, exports, and downloads. Validate inputs and upload sizes, and add appropriate request limits. Keep private bucket credentials on the server. Decide how long to keep notes, export files, and queue status records, then implement deletion for each storage system.

Read Designing Apps for d2o for stateless instances, temporary files, shared sessions, startup validation, logging, connection pools, graceful shutdown, and safe retries.

2. Create separate deployment environments

Keep tutorial data in its disposable Development Environment. Create the real app’s development, staging, and production Environments separately, each with its own databases, buckets, and secrets. Link the build Environment to your GitHub or GitLab repository, enable Wait for CI, and use promotion to move a tested build through staging into protected production.

Review the provider’s Wait for CI behavior, including what happens when a commit has no checks. If you push from a CI job instead, follow Deploying from CI, including deployment verification.

3. Version settings and migrations

Move process selection, health checks, and the release command into d2o-paas.yaml. The tutorials run schema initialization manually so you can inspect the result. For production, use versioned, repeatable migrations as a release command, rather than starting a migration independently in every replica.

The examples’ migrate process illustrates initialization; it is not a complete schema-evolution system. Adopt your framework’s migration tooling before changing an existing schema. Test migrations while the previous version is still serving, and test a code rollback against the updated database. Follow the safe migration sequence.

4. Choose durability and recovery

Review what survives failures and what is backed up. Use attachments instead of copying database or S3 credentials. Redis-only exports and queue status are disposable: if exports must remain discoverable after Redis loss, store their job metadata in the primary database and add recovery/reconciliation logic.

Choose a suitable object-storage tier and keep independent copies where required. Practise the restore procedure before an incident. High availability does not recover accidental deletion, and deleting a database also deletes its platform backups.

5. Validate availability and operations

Add a fast health check and graceful shutdown, then test replacing both web and worker instances. Use at least two web instances for production availability unless the application requires a singleton; size connection pools and memory for the total replica count. Verify worker retries cannot duplicate business effects.

Follow deploys to Live, inspect logs and metrics, and practise rollback in staging. Finish the production checklist.

6. Remove disposable resources

Download anything you want to keep before deleting a tutorial Environment. Use the language tutorial’s Troubleshooting & Cleanup chapter to review and remove its resources. Deleting an Environment permanently removes its apps and data; stopping local Docker Compose services does not delete hosted resources.

Return to the language tutorials to compare another framework.

Designing Apps for d2o

Build each app so that replacing or adding an instance does not lose data or interrupt work. These principles apply to every supported framework, whether you deploy a web app, a worker, or a static frontend.

Keep durable state outside instances

An instance’s filesystem and memory belong to that instance. Files can disappear when it restarts or is replaced, and another replica cannot see them. Store structured records in a database and uploads, generated exports, and other durable files in object storage. A local SQLite file, upload directory, or in-memory session store is unsuitable as the only copy of production data.

Temporary files are fine for bounded scratch work: unpacking an upload, transforming an image, or preparing an export. Clean them up, limit their size, and copy any result you need to keep into durable storage before reporting success. A singleton app still has an ephemeral filesystem.

Keep sessions and shared coordination outside the web process, or use an appropriate signed-cookie session design. Treat Redis caches as rebuildable. The platform does not back up Redis: a queue surviving a worker restart is different from surviving loss of Redis itself. For essential jobs, retain enough information in a backed-up database to recreate or reconcile them. See the durability comparison.

Read configuration at runtime

Read service addresses, feature flags, and credentials from environment variables. Use secret references for credentials and attachments for managed services. Keep each Environment’s settings separate and commit neither credentials nor local .env files.

Validate required settings at startup. A missing secret reference can leave its variable absent; it does not necessarily prevent the process from starting. Exit with a useful message naming the missing setting, without printing its value.

Build-time settings and runtime settings serve different purposes. Version selection and frontend compilation happen during the build; database connections and application secrets are used by the running process. Do not require a live production database to compile an image. See configuration and build/runtime network access.

Anything embedded in browser JavaScript, HTML, source maps, or other static assets is public, even if the build tool calls its input an environment variable. Keep private API keys and database credentials in a server-side app. A runtime secret cannot make an already compiled frontend asset private.

Listen on the configured port

Web apps must listen on 0.0.0.0 and the injected PORT, rather than a fixed port or loopback-only address. Workers have no public URL; a worker may expose an HTTP health endpoint on its configured port or use a health-check command.

Give web apps a fast, unauthenticated health endpoint that reports successful startup. Avoid restarting every instance because a shared dependency briefly fails: use request timeouts and bounded retries for dependency failures. See health checks and their defaults.

Shut down gracefully and make retries safe

When replacing an instance, d2o sends SIGTERM and allows 30 seconds before force-stopping it. Allow a short drain period while routing catches up, then stop accepting new work, finish in-flight requests or jobs, and exit. Configure your framework’s shutdown handling and keep work within that window.

A worker can stop after making a change but before acknowledging its job. Design jobs to be safe to retry: use stable job IDs, unique database constraints, and repeatable writes. Acknowledge only after the result has been saved. Long jobs should checkpoint or be split into smaller pieces. Do not assume a singleton or a queue provides exactly-once execution.

Share connections and handle dependency failures

Use bounded connection pools per instance. Scaling from two instances to ten also multiplies their potential database connections; allow capacity for workers and release commands too. Set connection and request timeouts, reconnect after failures, and retry transient errors with backoff. Do not blindly retry non-repeatable operations such as charging a customer.

Send logs to stdout and stderr

Print application events and useful errors to standard output or standard error; d2o collects them across instances. Do not depend on log files inside the container. Include request or job identifiers when useful, but redact passwords, tokens, connection strings, and sensitive request data. See Logs.

Prepare for production

Keep process selection, port, health checks, and release commands in versioned app settings. Use backward-compatible database migrations because old and new code overlap during deployment, and rolling back code does not roll back data.

Continue with Take an Example to Production or the production checklist.

Organizations, Projects & Environments

Everything you run on d2o PaaS lives in a three-level hierarchy:

Organization (acme)
└── Project (shop)
    ├── Environment (production)
    │   ├── Web Application (web)
    │   └── Database (shop-db)
    └── Environment (staging)

• An Organization owns everything: projects, members, secrets, and your plan’s usage limits.
• A Project groups related environments — typically one project per application or service.
• An Environment is a deployment target (for example production or staging) that holds the actual Resources: Web Applications, Background Workers, Databases, and Object Storage.

URLs follow the same shape: the shop project in the acme organization lives at /orgs/acme/projects/shop in the dashboard.

Personal and team organizations

The platform is invitation-only. When you accept an invitation and sign in for the first time, a personal organization is created for you automatically — it is marked Personal in the organization switcher and works like any other organization, except that it cannot be deleted and its ownership cannot be transferred.

For shared work, create a team organization: from the dashboard, choose Create Organization and give it a name and a URL slug (lowercase letters, numbers, and hyphens; the slug appears in URLs like /orgs/acme). Every organization has exactly one owner; the owner and admins can invite members and manage projects. See Access Control for what each role can do.

Only the owner can delete a team organization. Deleting it permanently removes every project, environment, and resource it contains, and asks you to type the organization name to confirm.

Projects

Create a project from the organization page with New Project. A project is mostly a grouping: it holds environments, project-scoped secrets, and the permission grants that control who can work in it. There is nothing to deploy at the project level — that happens in environments.

Deleting a project permanently removes all of its environments and everything in them — apps, databases, buckets and their contents, and secrets — protected environments included. Because of that, a project that contains a protected environment can only be deleted by an Owner or Admin of the organization; anyone else with permission to manage the project can delete projects without protected environments.

Environments

Create an environment from a project’s Environments page with New Environment. Names use lowercase letters, numbers, and hyphens (for example production or staging-eu). The name is fixed at creation, and the type cannot be changed from the dashboard or CLI. Automatic deployment, Protected and Release source can be changed later in the environment’s Settings page (switching to promote-only needs every app to have a built image first); the environment also records a Git branch setting (paas envs update --branch), though apps currently build from the main branch of their platform-hosted repository regardless.

Environment types

Each environment is one of three types: Development, Staging, or Production. The type is how the dashboard groups your environments, and it is how your plan accounts for capacity — limits are tracked per environment type, and some plans may not include every type. See Plans, Limits & Usage.

Git branch and Automatic deployment

Each environment records a Git branch setting (main by default). Builds follow each app’s own source configuration: apps deployed with git push build from the main branch of their platform-hosted repository. Automatic deployment (on by default) releases each new build automatically as soon as it finishes. Changes to an environment’s resources and secrets always roll out, regardless of this setting. With Automatic deployment off, new builds still run but wait as Built in the deployment history instead of going live — useful for production environments where you want to release on your own schedule. See How Builds & Deployments Work. Apps linked to a GitHub or GitLab repository deploy from the branch chosen on the link — see Deploy from GitHub or GitLab.

Release source

Each Environment either builds from source (the default: pushes to its branch are built and deployed) or is promote-only (it never builds; apps run whatever image was last promoted into it from the stage upstream). Together the Environments of a Project form a pipeline, ordered development → staging → production. See Pipelines, Promotion & Rollback.

Protected environments

Mark an environment Protected to guard it against accidental destructive actions. A protected environment cannot be deleted at all — attempting it returns an error until you remove protection in the environment’s settings, which only an organization Owner or Admin can do. Promotions into a protected environment ask for confirmation, and only an organization Owner or Admin can delete a project that contains one. Use it for production.

Deleting an unprotected environment permanently removes the environment and all of its resources, and asks you to type the environment name to confirm. This cannot be undone.

High availability

High availability is set per resource, not per environment: run several instances of an app with its scaling settings — see Scaling & Autoscaling — and give a PostgreSQL database a standby copy with high availability.

Visualizing an environment

An environment’s Resources section opens by default in Topology view: a diagram of every resource in the environment — Web Applications, Background Workers, Databases, and Object Storage — as nodes colored by their current status. When the environment has at least one Web Application, a single public entry point appears with a line to each of them, showing how many are running. A line from an app or worker to a database or bucket appears when it’s attached. A line between two apps appears when one app’s plain environment variable names the other — its name (API_HOST=api) or its public address — labelled with the variable’s name; secrets are never read for this. Resources that share an environment but aren’t wired together have no line between them. It’s a quick way to see everything running in an environment and how it’s actually connected. Switch to Cards or List with the toggle above the diagram for a plainer view of the same resources.

Working from the CLI

The paas CLI mirrors the hierarchy with the -o, -p, and -e context flags:

paas orgs list
paas projects list -o acme
paas envs list -o acme -p shop

paas orgs set-default and paas projects set-default save a default context so you can omit the flags. Each group also has info, create, update, and delete subcommands — run any of them with --help for the exact flags, for example paas envs create --help.

Next steps

• Resources — what you can run inside an environment
• How Builds & Deployments Work — branches, builds, and Automatic deployment in detail
• Inviting People — bring your team into an organization
• Access Control — roles, groups, and project permissions

Favourite organizations

Use the star beside an organization on the dashboard or in the organization switcher to add it to Favourites. Favourites appear above the remaining organizations and are saved to your account across devices. Search includes both sections. Favouriting an organization does not grant access to it.

Resources

Resources are the things you run and store on the platform. Every resource lives inside an Environment (see Organizations, Projects & Environments), and there are four types:

Every resource has a name made of lowercase letters, numbers, and hyphens. Pick it carefully — for apps it is used in URLs and DNS.

Web Application

A Web Application is a service that speaks HTTP. You choose a framework (Ruby on Rails, Node.js, Python, Go, Rust, or Static Files — see Supported Frameworks for caveats), a listening port, and a health-check path; the platform builds your code with buildpacks and runs it.

The platform hosts a Git repository for your app. After creating it you get a remote to push to — pushing to the main branch triggers a build and deployment. Push to it directly, or link a GitHub or GitLab repository so pushes there deploy automatically — see Deploy from GitHub or GitLab.

You control how many instances run, and CPU and memory limits per instance. Guides:

• Creating a Web Application
• Deploying with Git Push
• Scaling & Autoscaling
• Custom Domains & TLS

Background Worker

A Background Worker is a long-running process without HTTP — queue consumers, schedulers, bots. It builds and deploys exactly like a Web Application (same frameworks, same git-push flow, same scaling, logs, and console access); it just has no public URL, and its optional health check can be a command run inside the instance as well as an HTTP path.

• Creating a Background Worker
• Logs
• Console & One-off Commands

Database

A Database is a managed database instance. Four engines are available: PostgreSQL, Redis, MariaDB, and MongoDB.

You don’t manage credentials by hand: attach a database to an app and the platform injects a connection-string environment variable (named DATABASE_URL by default) into that app.

PostgreSQL and MariaDB databases are backed up automatically; restoring from a backup requires contacting support.

• Databases
• Attaching a Database
• Database Backups

Object Storage

An Object Storage resource is an S3-compatible bucket for files and images, with an optional size quota (in GB). The High availability storage tier may not yet be offered in Production-type Environments on your installation; the default Capacity tier is. Each bucket gets its own public URL, assigned shortly after creation; making the bucket public lets anyone read its objects at that URL, while a private bucket refuses public reads. The CLI can print S3-compatible credentials for use with standard S3 tooling (paas buckets creds).

• Object Storage Buckets

Creating resources

In the dashboard, open the Environment (for example acme → shop → production) and choose Add Resource. The form asks only for what the selected type needs: source and sizing for apps, an engine for databases, an optional quota for buckets.

From the CLI, apps and databases have their own command groups:

paas apps list -o acme -p shop -e production
paas apps create --help    # flags for creating a web app or worker
paas dbs create --help     # flags for creating a database

paas buckets works with the Object Storage resource selected with -a (-a media) — see the Object Storage Buckets guide for the full flow.

Next steps

• Quickstart: Deploy Your First App
• How Builds & Deployments Work
• Secrets & Configuration
• Plans, Limits & Usage

How Builds & Deployments Work

Every Web Application and Background Worker on d2o PaaS goes through the same pipeline: your source code is turned into a runnable image by Cloud Native Buildpacks, and that image is then deployed into the Environment. This page explains each stage and the knobs you control.

The pipeline at a glance

1. Source — new code arrives on the platform-hosted repository’s main — pushed by you, your CI, or a linked GitHub/GitLab branch.
2. Build — buildpacks build a version of your app from that commit using the framework you declared for the app. No Dockerfile is required.
3. Release — if the app has a release command, it runs once against the new version before anything else starts.
4. Deploy — new instances start and must pass their health check before they take traffic. With Automatic deployment on (the default) this happens automatically; with it off, the build waits until you deploy it yourself. A version that never becomes healthy is rolled back automatically. See Deployments, Health Checks & Rollback.

Each deployment is pinned to the exact image produced from your commit — the platform records the image by its digest, so what runs never silently drifts from what was built.

Where your code comes from

The platform hosts a git repository for every app — or one per Environment that several apps share. Code reaches it in one of three ways: you push to it (below), your CI pushes with a deployment token, or you link a GitHub or GitLab branch and every push there is deployed. Pointing an app at an arbitrary git URL isn’t supported.

The app’s Deployments tab in the dashboard shows ready-to-paste push commands (the remote URL embeds an access token), or the CLI configures a paas remote for you:

paas git remote -o acme -p shop -e production -a web
git push paas main

The CLI’s paas remote uses SSH by default — register a key first with paas keys add — or pass --https for an HTTPS remote whose push token is kept by git’s credential helper. See Deploying with Git Push.

Apps always build from the platform-hosted repository’s main, wherever the code came from.

Apps that share an Environment’s repository and have the same source directory and framework share one build: the image is built once per push and deployed to each of them, each running its own process.

Builds and frameworks

Builds use Cloud Native Buildpacks: the platform builds an image straight from your source using the buildpack for your app’s framework. Every Web Application and Background Worker declares its framework when you create it — it must be one of the supported frameworks, and an app without one is rejected up front rather than deployed broken. An app whose build produces more than one process type can choose which one to start (the app’s Process setting).

Build and runtime connectivity differ; see Network access.

While a build is running, the app’s status and log views tell you the image is still building; a failed build shows as Failed in the deployment history, and the Organization’s owner gets an email about it (once per failure, when email is configured on the installation), so a broken push never goes unnoticed.

Network access

Blocked private ranges include 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, and 100.64.0.0/10. An authenticated registry still needs a publicly reachable address for a build. Vendor a dependency if it cannot be served from a reachable endpoint; do not query a live database during compilation.

Use attachments for managed service addresses and credentials. Do not construct internal database hostnames yourself or expect a local machine to reach them. Run diagnostics from the app’s console. For a public web service, use its displayed HTTPS URL or custom domain, not a guessed hostname. Workers have no public URL.

An unreachable dependency is different from an invalid credential: first check the address and Environment, then connection timeouts and authentication. Applications should use bounded timeouts, reconnect, and back off when retrying transient failures; see Designing Apps for d2o.

Automatic deployment

Automatic deployment is a per-Environment setting, on by default. While it’s on, every successful build of new code is deployed automatically.

Turn it off when you want to control exactly when code ships (a production Environment, say). The platform still builds every push — the build simply waits, showing as Built (waiting to be deployed) in the deployment history, until you deploy it.

You set Automatic deployment when creating an Environment, and change it later in the dashboard under Environment Settings → Deployment. The Environment’s overview shows whether it is currently enabled.

Deploying manually

When Automatic deployment is off (or you just want to force a rollout), trigger a deployment from the CLI:

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

This ships the newest successful build — even in an Environment with Automatic deployment off — and rolls the app out. Triggering a deployment requires the deploy permission on the project. In a promote-only Environment, promote into it instead — paas deploy is refused there.

Build and promote-only Environments

An Environment either builds from source (the default) or is promote-only: it never builds, and its apps run the versions promoted into it from another Environment. Pushes to a promote-only Environment are refused. See Pipelines, Promotion & Rollback.

Tracking what’s deployed

The Deployments tab of an app lists that app’s deployments, newest first — click Load more for older ones. Each entry shows the deployment number, commit message, short SHA, branch, who pushed it, whether it was a build, a promotion or a rollback, and its stage (Received, Queued, Building, Built, Running release command, Releasing, Starting, Live, Failed, Rolled back, Rollback failed, or Replaced), with the newest Live entry marked current. A shared build also names the other apps it deployed. For every app at once, open the Environment’s Deployments tab.

From the CLI:

paas releases -o acme -p shop -e production   # recent deployments
paas status   -o acme -p shop -e production -a web   # current sync/health status

paas deploys list (alias paas releases) shows 25 deployments per page; add -a web for one app’s deployments, and follow the More: paas deploys list --before <n> hint (or pass --limit, up to 100) for older ones.

Next steps

• Deploying with Git Push
• Deployments, Health Checks & Rollback
• Supported Frameworks
• Logs

Secrets & Configuration

Your app’s configuration comes in two forms:

• Environment variables — plain KEY=VALUE pairs set on an app (a Web Application or Background Worker) or inherited from its Environment or Organization. Use them for non-sensitive settings: feature flags, log levels, public URLs.
• Secrets — encrypted values (API keys, passwords, tokens) stored by the platform and injected into apps by reference. Secret values are write-only: once saved, nobody can read them back through the dashboard or the API — you can only replace them.

Both reach your code the same way: as environment variables in the running instance. The difference is how they are stored and who can see them.

Environment variables

Plain configuration inherits from Organization → Environment → app, with the more specific value winning. There is no Project-level plain-variable scope. For example, an app’s LOG_LEVEL=info overrides its Environment’s LOG_LEVEL=debug; removing the app value restores inheritance.

Inherited values never override automatic public URL variables or variables supplied by attachments. An app may explicitly override PAAS_PUBLIC_URL and PAAS_PUBLIC_HOST; avoid reusing attachment variable names for unrelated settings. The platform sets PORT from the app’s port setting.

Use the Environment Variables guide for dashboard and CLI commands, key rules, automatic variables, and permissions. Plain values are visible to people with access to that scope; credentials belong in secrets.

Runtime variables configure the running app. Buildpack settings configure image construction; see runtime selection and static frontend builds. Browser assets expose any values compiled into them; see Designing Apps for d2o.

Secrets

Secrets store encrypted, write-only values. Their names start with an uppercase letter, followed by uppercase letters, digits, or underscores, don’t end with an underscore, and are at most 253 characters. A few endings (_S3, _REDIS_CONN, _MONGODB_PASSWORD, _MARIADB_PASSWORD) are reserved for credentials the platform creates. An app variable key also starts with an uppercase letter, and need not match the secret name.

For example, an app variable PAYMENT_KEY may reference a secret named STRIPE_PAYMENT_KEY. The value reaches the process as PAYMENT_KEY. See Managing Secrets for creation, permissions, rotation, and deletion.

Secret scopes

Secrets live at one of three levels, matching the platform hierarchy:

• Organization — for values shared across the whole organization.
• Project — for values shared by a project’s environments.
• Environment — for values specific to one environment, such as production credentials that staging must never see. This is the most common scope, managed from the environment’s Secrets page.

Choose the narrowest scope that works. A production database password belongs on the production environment, not on the organization.

How a secret reaches your app

A secret reaches an app only through a variable referencing it. The platform resolves the secret name from the nearest scope: Environment → Project → Organization. Creating a reference fails if no visible secret exists. Your code then reads an ordinary environment variable; it needs no platform SDK.

The binding instructions show both interfaces. Binding or rotating a secret rolls out new instances automatically; deleting and re-creating a referenced secret can require a manual restart. The authoritative timing rules are in When changes reach your app.

Next steps

• Environment Variables — the full guide to per-app configuration
• Managing Secrets — step-by-step secret creation and rotation
• Attaching a Database — connection strings injected for you
• Access Control — who can manage secrets

Access Control

Access on d2o PaaS works in two layers. Your organization role decides what you can do to the organization itself — its members, groups, projects, and settings. Your project capabilities, granted through groups, decide what you can do inside individual projects and their environments.

You manage all of this in the dashboard. The paas CLI can manage organizations, projects, and resources, but membership, groups, and invitations are dashboard features.

Organization roles

Every member of an organization has exactly one role:

The personal organization created for you when you join the platform is one you own. In a team organization, most people are Members whose actual project access comes from groups.

Project capabilities

Within a project, access is a set of individual capabilities — each one is granted separately, and you can hold any combination of them:

Deployment tokens and GitHub/GitLab repository links follow the same capabilities: an Environment’s need Manage environments, and an app’s own need Manage web apps or Manage workers. Connecting a GitHub or GitLab account to the organization is limited to its Owners and Admins.

The dashboard offers presets — Viewer, Release manager, Developer, Maintainer, Admin — that select common combinations of these capabilities, so you don’t need to pick them one by one. A Release manager (View plus Promote & roll back) can move releases between Environments and undo them, without pushing code or touching running instances.

Owners and Admins automatically hold every project capability in the organization, apart from any capabilities the platform has reserved for its own operators. Members get capabilities only through groups.

Groups

A group is a named set of organization members plus a set of project grants. You create groups in the dashboard under your organization’s settings, add members to them, and then grant each group a set of capabilities on the projects it should reach (or start from a preset).

If you belong to several groups, your effective access to a project is the union of everything those groups grant you.

Per-environment overrides

A group’s grant applies to the whole project by default, but it can be overridden for specific environments. This lets you shape access per environment — for example, treating production differently from the project’s other environments — without splitting the project up.

Project guests

Sometimes you want to give one person access to one project without adding them to your organization at all — a contractor, or a collaborator from another company. That is a project guest.

Guests are added by inviting them directly to a project. The invitation carries the set of capabilities they will hold (organization invitations carry a role instead). A guest:

• has the granted capabilities on that one project, and nothing else in the organization;
• does not appear in the organization’s member list and cannot see organization-level pages — at most the organization’s name;
• is not affected by per-environment overrides — a guest’s grant is project-level only.

You cannot send a project invitation to an email address that already belongs to an organization member; existing members get access through groups instead. Project invitations can be sent by an organization Owner or Admin, or by someone who holds the Manage project capability on that project.

Because the platform is invitation-only, inviting someone who has never used d2o PaaS also creates their account — they receive an email that walks them through setting a password and accepting the invitation.

Next steps

• Groups & Project Permissions — create groups and grant project access step by step
• Inviting People — organization and project invitations in detail
• Managing Your Organization — members, roles, and ownership transfer
• Organizations, Projects & Environments — how the hierarchy fits together

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.

Next steps

• Designing Apps for d2o

• Deploying with Git Push

• Environment Variables

• Scaling & Autoscaling

• Custom Domains & TLS

Deploying Go

Choose Go (--framework go). Commit a Go modules project with go.mod at the selected app root, plus go.sum when your dependencies require it.

This is a quick guide for an existing project. For a complete hello → database → worker → storage walkthrough, follow the Go tutorial.

Here is a minimal web server:

package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "ok")
    })
    log.Fatal(http.ListenAndServe(":"+os.Getenv("PORT"), nil))
}

go mod init example.com/service
go mod tidy
paas apps create service --framework go --health-check-path /health

Commit and push your code. The builder compiles the main packages and provides a web process for a single-binary app. Add a Procfile when you need a different command or multiple process types; compiled binaries are on the launch process’s PATH. For example:

web: service

For several main packages, the buildpack’s // +heroku install comment in go.mod can select which package paths to compile. Keep the Procfile’s binary names consistent with those packages.

Declare the compiler requirement in go.mod; see runtime selection for exact pins, ranges, and the toolchain distinction. The catalog lists the deployed builder’s available releases and verified versions.

The platform disables Go’s VCS stamping during builds because the build sandbox does not expose a normal writable Git checkout. This does not change module dependency resolution. For build failures, check the requested compiler version, module files, and package paths. For health failures, bind to all interfaces and read the injected PORT, then ensure your configured health endpoint succeeds.

Deploying Static Sites

Choose Static Files (--framework static) to serve HTML, CSS, JavaScript, and other public assets with nginx. This supports prebuilt files and frontend projects that compile to files. Server-side rendering needs a server framework such as Node.js instead.

For a first deployment with a downloadable site and a public bucket asset, follow the static tutorial. This guide covers configuring your own frontend.

Prebuilt files

Commit your site under public/, including public/index.html, and create a web app:

paas apps create site --framework static --health-check-path /

Push it using the app’s Git remote. nginx listens on the platform’s injected PORT. The home page is the health endpoint; the API, CLI, and dashboard default new Static Files web apps to / when no explicit path is provided. Existing app settings are preserved.

Build a frontend project

Define a package script in package.json, for example a Vite project’s build script. Commit the package manager’s lockfile. The npm and Yarn build workflows are verified; pnpm is not part of this Static Files build path.

At the app root, add project.toml:

[_]
schema-version = "0.2"

[[io.buildpacks.build.env]]
name = "BP_NODE_RUN_SCRIPTS"
value = "build"

[[io.buildpacks.build.env]]
name = "BP_WEB_SERVER_ROOT"
value = "dist"

The builder installs dependencies and runs the named package script, then serves dist/ with nginx. BP_NODE_RUN_SCRIPTS takes script names, not shell commands; put the command in package.json. Change dist to your tool’s output directory (for example build). These paths are relative to the selected app source directory. Shared apps with the same framework and source directory share this build configuration and output.

Use engines.node to select a build-time Node.js version. Paketo’s version inventory differs from the Node.js application builder; see version selection and the catalog. The deployed builder’s Yarn versions and bundled npm version are part of its frontend toolchain; a package-manager pin outside that inventory can fail a build. For the verified Yarn Classic workflow, commit yarn.lock and use engines.yarn in package.json to request a catalog version. npm comes bundled with the selected Node engine. A successful build is separate from upstream maintenance; check both columns in the catalog when choosing a toolchain.

Single-page applications

For client-side routes, add:

[[io.buildpacks.build.env]]
name = "BP_WEB_SERVER_ENABLE_PUSH_STATE"
value = "true"

This serves index.html for client-side routes. Leave it unset for a conventional site where missing pages should return 404. Only publish files intended to be public; build-time variables compiled into JavaScript are visible to visitors.

Configuration and troubleshooting

project.toml configures the build. d2o-paas.yaml configures the running app, such as health checks and process selection. Dashboard environment variables configure the running container; do not rely on them as build-time settings. The platform supplies BP_WEB_SERVER=nginx; no custom nginx configuration is needed for these examples.

If a build fails, inspect dependency installation and the named script in the build log. If deployment health fails, check that the configured output directory contains index.html and that the health path points to a real file. A /health path is not automatically created. For a custom nginx configuration, ensure it listens on the injected port and serves the intended document root.

See Paketo Web Servers for the upstream build settings, and deployments for health checks and rollback.

Pinning nginx

The catalog lists nginx versions from the deployed builder. To select one, set BP_NGINX_VERSION in project.toml using the same build-env syntax above. The currently deployed nginx buildpack 1.3.0 also needs a buildpack.yml file when a version is explicitly selected:

nginx: {}

This works around its missing-file error during detection; the version in BP_NGINX_VERSION still takes precedence. The default server version needs neither setting. This workaround is covered by the catalog’s smoke tests.

Creating a Background Worker

A Background Worker is a long-running process without a public web endpoint. It is built and deployed exactly like a Web Application — you push code, the platform builds it with buildpacks and runs it — but it gets no public URL. It can declare an optional health check — see Health checks.

When to use a worker

Choose a worker when your process does its job without serving web requests:

• consuming a queue or processing jobs
• running a bot or a long-lived connection to an external service
• periodic or streaming data processing

For an application HTTP service, create a Web Application. A worker may still listen on a port solely to answer its health check.

Running a bot that must never run twice, such as a chat bot? Make it a singleton.

Before you begin

You need an Environment to create the worker in, and permission to manage workers in that Project (see Access Control). Workers count toward your plan’s limits like any other Resource — see Plans, Limits & Usage.

Create a worker in the dashboard

1. In the dashboard, open the Environment (for example production in the shop project) and create a new Resource.
2. Select the Background Worker resource type.
3. Enter a Name — up to 50 lowercase letters, numbers, and hyphens, starting with a letter (for example jobs).
4. Pick the Framework that matches your code — Ruby on Rails, Node.js, Python, Go, Rust, or Static Files (see Supported Frameworks).
5. Set Process type to the name your build declares, such as worker. Leave it blank only when the build’s default process is the worker. This selects a buildpack process, not a shell command; the same field is editable later in Settings.
6. Optionally adjust Replicas (how many instances run; default 1), CPU Limit, Memory Limit, and Max egress per replica (Mbps) (outbound bandwidth per instance; unlimited when left blank).
7. Click Create Resource.

There is no Networking section for a worker — no port, since it takes no public traffic. A worker’s health check, if you set one, lives under its own settings instead — see Health checks. Or set it, along with the worker’s process, in d2o-paas.yaml in your repository — see d2o-paas.yaml Reference.

The platform hosts a git repository for your worker’s source. After creating it, you get a remote to push to; pushing to the main branch triggers a build and deploy.

Create a worker with the CLI

paas apps create creates a Web Application by default; add --worker to create a Background Worker:

paas apps create jobs --worker \
  -o acme -p shop -e production \
  --framework nodejs

Useful options for workers:

• --framework <FRAMEWORK> — the buildpack framework for your code
• --process <PROCESS> (alias --start-command) — select a named process such as worker
• --replicas <REPLICAS> — how many instances to run
• --cpu <CPU> / --memory <MEMORY> — per-instance resource limits
• --health-check-path <PATH> or --health-check-command <COMMAND> — optional; without either, a new instance just has to run for 30 seconds without restarting to count as healthy (see Health checks)
• --git-repo <GIT_REPO> / --git-branch <GIT_BRANCH> — reserved for building from an arbitrary git URL, which isn’t supported; push to the platform-hosted repository (see Deploying with Git Push), or deploy from GitHub or GitLab
• --autoscaling-min, --autoscaling-max, --autoscaling-cpu-target — enable CPU-based autoscaling (see Scaling & Autoscaling)

A worker never gets a public URL. If you give it a health check path, it must answer on the port in $PORT — 8080 unless you set --port.

Deploy your code

From your worker’s source directory, configure the paas git remote and push:

cd my-worker
paas git remote -o acme -p shop -e production -a jobs
git push paas main

The push triggers a build and deployment. Follow along with:

paas status -o acme -p shop -e production -a jobs
paas logs -a jobs --tail

See How Builds & Deployments Work for what happens between the push and your worker running.

Several apps from one repository? Create them with --shared-source and use the Environment’s remote instead — see One remote for several apps.

What a worker doesn’t have

Because a worker serves no HTTP traffic, there is no public URL and no custom domain. A health check is optional — see Health checks — and without one the platform just waits for a new instance to stay up for 30 seconds. Everything else works the same as for a Web Application: environment variables, secrets, database attachments, scaling, restarts, logs, metrics, and the console.

Next steps

• Designing Apps for d2o — shutdown and retry-safe jobs

• Environment Variables — configure your worker

• Attaching a Database — give it a database connection

• Logs — watch what it’s doing

• Scaling & Autoscaling — run more instances

For complete web and worker examples sharing one build, follow the language tutorials.

Environment Variables

Environment variables configure a single Resource — one app in one Environment. The same app in production and staging keeps separate sets, so you can point each at different services without touching code.

Settings that many apps share don’t have to be repeated on each one: set them once on the Organization or the Environment and every app there inherits them — see Organization and environment variables.

Keys must start with an uppercase letter and contain only uppercase letters, digits, and underscores (DATABASE_URL, NODE_ENV). The dashboard normalizes what you type automatically; the CLI and API reject invalid keys.

Setting, changing, or deleting a variable requires the manage capability on the project (see Access Control) and triggers a new deployment of the app so running instances pick up the change.

In the dashboard

Open your app’s Config tab and find the Environment Variables section, then click Add Variable. Each variable takes one of three value sources:

• Plain value — stored and displayed as-is. Good for non-sensitive settings like NODE_ENV.
• Secret value (hidden) — the value is stored as an encrypted secret in this Environment, named after the variable’s key, and linked to it. Your app receives it like any other variable; nobody can read it back afterwards. Because it creates or replaces a secret, it needs the Manage secrets capability on the Environment, not just permission to manage the app. A name that’s already a secret here is refused: another app’s linked secret, one made on the Secrets page, or a Project secret (and, for organization owners and admins, an Organization secret). Writing it would change or override that secret for every app here, so link the variable to it instead, or pick another name.
• Link to secret — the variable takes its value from a platform-managed secret you pick from a list. If no secret is available to link, the form links you to create one.

Existing variables can be edited or deleted inline. Deleting asks for confirmation, since it also redeploys the app. A hidden variable stays hidden: saving a plain value over it is refused, so delete it first if you want to store a plain one.

The section also lists the variables the app inherits from its Organization and Environment, showing where each one comes from and whether the app overrides it.

With the CLI

paas config manages variables for the app selected with -a, scoped by -o/--org, -p/--project, and -e/--env.

List the current variables:

paas config list -o acme -p shop -e production -a web

Set one or more variables. Pairs are applied in order, and the command stops at the first failure:

paas config set NODE_ENV=production LOG_LEVEL=info -o acme -p shop -e production -a web

Store a hidden value with --hidden: the CLI’s version of Secret value (hidden), with the same rules and capability. KEY=- reads the value from stdin, so it stays out of your shell history:

printf %s "$API_TOKEN" | paas config set --hidden API_TOKEN=- -o acme -p shop -e production -a web

Remove a variable (one key per command):

paas config unset LOG_LEVEL -o acme -p shop -e production -a web

paas config list also shows the variables the app inherits; --json prints the raw API response for the app’s own variables only.

Linking a variable to a secret

Select Link to secret for a sensitive value. A variable key can differ from the secret name; the referenced secret must already exist in a visible scope. Follow Binding a secret to an app for the dashboard and CLI commands.

Organization and environment variables

Besides its own variables, every Web Application and Background Worker inherits plain variables set on its Organization and on its Environment. Use them for settings that many apps share — a log level for the whole staging Environment, a region or company-wide feature flag for every app in the Organization — instead of copying the same value onto each app.

The app overrides its Environment, which overrides its Organization. There is no Project-level plain-variable scope. See configuration precedence for the complete rules and an example.

A few things to know:

• Plain values only. Organization and Environment variables are stored and shown as-is, and can’t link to a secret. Anyone who can view the Organization or Environment can read them, so keep passwords and API keys in secrets and link them from the app.
• Automatic and attachment variables win. Variables the platform sets for an app — PAAS_PUBLIC_URL, PAAS_PUBLIC_HOST, and the variables an attached database or bucket injects — are never replaced by an inherited variable. An inherited variable with one of those keys is skipped for that app and shown as overridden.
• Referencing inherited values. An app’s own variables can use an inherited one, just as they can use the automatic variables — for example API_URL set to $(API_BASE)/v2.
• Changes roll out on their own. Setting or removing an Organization or Environment variable redeploys every app it applies to, so their instances pick up the new value. There is nothing to restart by hand.

Keys follow the same rules as app variables, and a value can be up to 10,000 characters.

Who can change them

An Environment’s capabilities come from the Project unless a per-environment override changes them. See Access Control.

In the dashboard

• Organization variables — open the Organization, go to Settings, then Variables.
• Environment variables — open the Environment, go to Settings, then Variables.

Add, edit, or remove variables there. The app’s own Environment Variables section shows what it inherits from both levels.

With the CLI

paas config takes --scope org|env|app (default app). With --scope org it needs only the Organization (-o); with --scope env it needs the Organization, Project, and Environment (-o, -p, -e); the default app scope also needs -a.

# Every app in the Organization
paas config set --scope org LOG_LEVEL=warn -o acme

# Every app in the staging Environment
paas config set --scope env LOG_LEVEL=debug -o acme -p shop -e staging
paas config list --scope env -o acme -p shop -e staging

# Remove an inherited variable
paas config unset --scope org LOG_LEVEL -o acme

--secret-ref works with the app scope only, since Organization and Environment variables are plain values.

Automatic variables

Apps with a public hostname (Web Applications) get two variables injected automatically:

• PAAS_PUBLIC_URL — the app’s full public URL, e.g. https://dzijyc9c.cx.<your-platform-domain> — an eight-character random label under the app domain your platform’s operators configured
• PAAS_PUBLIC_HOST — the hostname alone

Because public hostnames are randomly generated, your app cannot guess its own address at build time; use these wherever the app needs to name itself — an OAuth redirect URL, absolute links in email, a webhook it registers. Other variables you define can reference them, for example CALLBACK_URL set to $(PAAS_PUBLIC_URL)/oauth/callback.

If you define your own PAAS_PUBLIC_URL or PAAS_PUBLIC_HOST on the app — say, behind a proxy or on a custom domain — your value wins and the platform’s is not injected. (An Organization or Environment variable with one of these keys does not; see above.) Background Workers and Databases have no public hostname, and Object Storage buckets don’t run your code, so none of them receive these variables.

Every Web Application and Background Worker also gets PORT, set to the app’s port: 3000 unless you chose another, and 8080 for a worker without one. Bind your server to it.

When a restart is needed

Variable changes and secret rotation roll out automatically. The delete-and-recreate exception and its restart command are documented in When changes reach your app. Configuration rollouts are not numbered code deploys and do not provide automatic rollback; try changes in staging first.

Next steps

• Managing Secrets — create and update the secrets your variables link to
• Attaching a Database — connection details injected as an environment variable
• Secrets & Configuration — how configuration flows through the platform
• Deployments, Health Checks & Rollback — the deployments your changes trigger

Scaling & Autoscaling

Web Applications and Background Workers run as one or more identical instances. You can set the instance count yourself, or turn on CPU autoscaling and let the platform adjust it within a range you choose. This page covers both, plus the CPU and memory settings that apply to each instance.

Databases and Object Storage buckets are not scaled this way: a Database’s instances are managed by the platform, and a bucket has no instances at all.

Scale manually

Scaling needs the deploy permission on the project (see Access Control).

In the dashboard, open the app’s Overview page. The Replicas row shows the current count with + and − buttons next to it. Scaling down to zero stops the app entirely, so the dashboard asks you to confirm first. You can also set the replica count on the app’s Settings tab — that save goes through the same form as CPU and memory, so it needs the manage permission rather than deploy.

With the CLI, use paas scale:

paas scale 3 -o acme -p shop -e production -a web

Scaling to 0 stops the app; scale back up to start it again. Check the running instances with:

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

The change rolls out automatically — you do not need to trigger a deployment.

Scaling is checked against your Organization’s plan limits, since each added instance consumes capacity. If a scale request would exceed them, it is rejected with a limit-exceeded error; see Plans, Limits & Usage. An app stopped by the monthly transfer cap can’t be scaled until the allocation is raised or the month rolls over — see Monthly transfer allocation.

Running on more than one server

Run two or more instances (or autoscale) and the platform spreads them evenly across its servers, so a server failure leaves the others serving; maintenance moves one instance at a time. A single-instance app is unavailable while its one instance is moved — run at least two if that matters.

CPU and memory per instance

Every instance of an app runs with the same CPU and memory limits. Set them on the app’s Settings tab in the dashboard (this needs the manage permission):

• CPU Limit — for example 500m (half a CPU core) or 1 (one full core).
• Memory Limit — for example 512Mi or 1Gi.

Saving rolls the change out to all instances automatically. Like replicas, these sizes count against your plan’s capacity, so raising them for a heavily scaled app can hit a limit.

Autoscaling

Instead of picking a fixed count, you can have the platform scale the app on CPU usage. Autoscaling is opt-in and per app, and is available for Web Applications and Background Workers.

On the app’s Overview page, the Autoscaling row shows the current state. Click Enable… and set:

• Min replicas — the count the app never drops below (at least 1).
• Max replicas — the ceiling; must be greater than or equal to the minimum.
• Target CPU % — the average CPU use (1–100) the autoscaler aims for, as a percentage of each instance’s baseline of 0.1 core (100m, or the CPU Limit if that is lower), not of its CPU Limit. For example, 70 adds instances once they average 70m. When instances run hotter than the target, more are added, up to the max; when they run cooler, instances are removed, down to the min.

While autoscaling is on, the Replicas row is marked (managed by autoscaler) and the manual +/− buttons disappear. To see how many instances are actually running, check the running instances (for example with paas ps). Plan limits are enforced against the configured max, since that is the real peak the app can reach.

To go back to a fixed count, click Disable on the Autoscaling row. Your previous min/max/target values are remembered, so re-enabling later does not reset them.

With the CLI, passing any of --autoscaling-min, --autoscaling-max or --autoscaling-cpu-target to paas apps update (or paas apps create) turns autoscaling on; an unset target means 70:

paas apps update web --autoscaling-min 2 --autoscaling-max 6 --autoscaling-cpu-target 70 -o acme -p shop -e production

To turn it off, pass --autoscaling false; the app goes back to its fixed instance count:

paas apps update web --autoscaling false -o acme -p shop -e production

Manual scaling conflicts with autoscaling

While autoscaling is on, the autoscaler owns the replica count — a manual value would just be overwritten. A paas scale (or a scale request from any other client) is therefore rejected with a conflict:

$ paas scale 5 -o acme -p shop -e production -a web
Error: CONFLICT: autoscaling is enabled; disable it to set a fixed replica count

Disable autoscaling first, then scale manually.

Singleton apps

A singleton app runs at most one instance. Deployments and restarts stop the old instance before starting the new one, so expect a few seconds of downtime. Use it for bots and other apps that must never run twice.

Normally a deployment starts the new instance before stopping the old one, so the app stays up throughout — but for a moment two copies run side by side. For most apps that is harmless. For a bot that keeps one live connection per token to a chat service, two copies mean two sessions on the same token: duplicate replies, or the service disconnecting both.

A singleton never overlaps. Every rollout — a deployment, a restart, or a configuration change — stops the old instance first and only then starts the new one. The cost is a gap while the old instance stops and the new one starts, so leave it off for Web Applications that need to stay up through deployments. How long the gap lasts depends on how quickly your app shuts down: the platform sends it SIGTERM and waits for it to exit. An app that exits promptly on SIGTERM is down for a few seconds; one that ignores it is force-stopped after 30 seconds, so its gap is about 30 seconds longer.

Singleton is off by default and available for Web Applications and Background Workers. A singleton app:

• can’t autoscale — turn off autoscaling first (click Disable in the app’s Autoscaling row, or paas apps update <app> --autoscaling false);
• runs at most one instance — the replica count can be 1, or 0 to stop the app. Scaling a singleton above 1 is rejected with a conflict:

$ paas scale 2 -o acme -p shop -e production -a bot
Error: CONFLICT: singleton apps run at most one instance; turn off singleton to scale out

In the dashboard, open the app’s Overview page and tick Run at most one instance in the Singleton row. It applies right away (this needs the manage permission). If the app is autoscaling or running more than one instance, the box stays disabled until you turn off autoscaling or scale down to one.

With the CLI, pass --singleton true to paas apps update (or to paas apps create):

paas apps update bot --singleton true -o acme -p shop -e production

Add --replicas 1 if the app runs more than one instance today. Pass --singleton false to turn it off again; paas apps info shows whether an app is a singleton.

Or set singleton: true in d2o-paas.yaml; the checkbox then shows as set by your code.

Next steps

• Metrics — watch CPU and memory usage to pick sensible limits and targets
• Restarting an App — roll all instances without changing the count
• Plans, Limits & Usage — how scaling counts against your Organization’s capacity

Deployments, Health Checks & Rollback

Every push, promotion, and rollback is a deployment — a numbered record you can follow from the moment it starts to the moment it’s serving traffic, or fails with a reason you can act on. This page covers the stages a deployment goes through, how to follow one live, health checks, the release command, and rolling back.

What happens after git push

A deployment that doesn’t reach Live ends in one of these instead:

A build that doesn’t start within 30 minutes of the push, stops reporting for 5 minutes, or runs longer than 3 hours is marked Failed with the reason; push again. (A 3-hour build that does eventually finish is still deployed.) A promotion or rollback that isn’t applied within 10 minutes is marked Failed too.

See Health checks and Release command for what can make a deployment fail.

Following a deployment

A push prints its deployment number, a link to watch it live, and the paas watch command to run:

remote: Deploy #42 started for abc1234 → web, worker
remote:   Follow live: https://d2o.io/orgs/acme/projects/shop/envs/production/deploys/42
remote:   Or run:      paas watch --deploy 42

The push returns as soon as the deployment is created — it doesn’t wait for the build.

In the dashboard, the printed link opens the deployment page: a stepper for the current stage, one row per app with its health-check progress (or the reason it’s waiting), live build and release logs, and — if it fails — the failure reason and a Roll back button. While a deployment is in flight, the app and environment pages, and the project’s pipeline board, show a live “Deployment #42 · Building” chip that links to the same page. The app’s Deployments tab lists that app’s deployments (a shared build also names its other apps); the Environment’s Deployments tab lists every app’s.

From the CLI, paas watch follows a deployment stage by stage and streams its build and release logs until it finishes:

paas watch --deploy 42

Without --deploy, it follows the newest deployment for the app or Environment inferred from your paas git remote. Useful flags:

• --quiet — print stage changes only, without the log output.
• --timeout <SECONDS> — how long to wait before giving up (default 1800).

paas watch only exits once the deployment is final — including after an automatic rollback finishes — and retries on a network blip rather than giving up. It exits 0 when the deployment reaches Live, 1 when it ends Failed, Rolled back, Rollback failed, or Replaced (a newer deployment took over), and 2 on a timeout or a usage/connection problem — so it’s a reasonable gate in a CI pipeline:

git push paas main && paas watch

Like paas logs --tail, it streams, so it rejects --json. Watching requires an account API token; a Git deployment token cannot authenticate it. See CI deployment verification.

Health checks

With a health check configured, a new version must pass it before taking traffic.

Choose a path your app actually serves; framework conventions such as Rails’ /up are not selected automatically. An explicit path or repo-declared setting overrides the creation default. Probed instances must remain Ready for 10 seconds before the rollout treats them as available.

• Web Applications use the health check path you configure (--health-check-path, or the equivalent dashboard field). The platform requests it from each new instance and waits for a successful response before sending it traffic. A Web Application with no health check path set gets no HTTP check: a new instance counts as healthy once it has run for 10 seconds.
• Background Workers have no public URL, so a health check is optional. Set either a path (checked over HTTP on the port in $PORT — 8080 unless you set one) or a command (--health-check-command) that exits 0 when the worker is healthy. Without either, a new instance just has to run for 30 seconds without restarting to count as healthy.

A health check can also live in your repository’s d2o-paas.yaml instead of the dashboard or CLI. A version that sets it that way locks the field — it shows as read-only until a later version stops setting it. See Move Settings Into Your Repo.

The check keeps running after the deployment, too: an instance that fails it for about 15 seconds stops receiving traffic, and one that keeps failing for about 30 seconds is restarted.

What makes a good check: answer within a second, don’t put it behind login or any authentication your health checker won’t have, and report whether your app has started and can serve. Don’t make it fail just because a dependency is briefly unreachable — if the check queries your database and the database is down for half a minute, every instance fails at once and all of them are restarted together. See Designing Apps for d2o.

When a new version isn’t healthy

A rollout fails after 5 minutes without progress toward healthy new instances. The platform fails it sooner, without waiting out the full 5 minutes, when:

• the container cannot start because its required configuration is unavailable — failed right away. App secret references are optional at container startup: a deleted secret can leave a variable absent instead. Validate required settings in your app;
• it keeps exiting, after 3 restarts — reported as “Your app keeps exiting (exit code N)”, along with its recent log output — or, when the health check is what keeps failing, the check’s own result, e.g. “Health check /health returned 503”;
• it can’t be loaded, or there isn’t enough free capacity on our servers to start it — after 2 minutes of that. A capacity failure is a problem on our side, not in your app.

Automatic rollback is an app setting — the Automatic rollback checkbox under the app’s Settings → Deployments, or --auto-rollback — on by default. When a new version fails, the platform deploys the last version that reached Live instead, and health-gates that rollback too — it has to become healthy in turn:

• If it does, the deployment is marked Rolled back.
• If even the previous version doesn’t come up healthy, the deployment is marked Rollback failed and the platform stops — it never flip-flops between two broken versions — and emails the organization’s owner.

Turn automatic rollback off for an app that should never silently revert on its own; an unhealthy new version then stays Rollback failed, with the previous version still running. Either way, the deployment page and paas deploys info show what happened and why.

Apps set to run at most one instance (singletons) are briefly down during a rollback: the broken instance has to stop before the previous version can start in its place.

Release command

A release command runs once against the new version, before any new instance starts — the place for a versioned migration before the app starts. Make it safe to retry; see the execution rules below.

Set it as release.command in d2o-paas.yaml, as a release: line in your app’s Procfile, or as the Release command app setting (--release-command). When more than one is present, the file wins over the Procfile, and the Procfile wins over the app setting — whichever is set furthest up that list is the one that runs, and the deployment timeline says so when the Procfile overrides the app setting:

Your app's release command setting is ignored because the Procfile defines `release:`

It runs under bash, with the same environment variables and secrets as the app itself.

• If it exits non-zero or runs longer than 15 minutes, the deployment fails at Running release command, and the previous version keeps running, untouched.
• It runs once per new version — a deployment, promotion, or manual rollback that changes the running version. An automatic rollback doesn’t run it again: the previous version already ran it when it went live. A deployment triggered only by a setting or environment-variable change doesn’t run it either, since the version hasn’t changed. Still, write it to be safe to run more than once: a migration tool that skips migrations it already applied is safe this way; a script that unconditionally inserts a row is not.
• For a shared build (several apps built from one repo), it runs once — for one app, before the others start — not once per app.
• A promotion runs the release command in the target Environment, against the target’s database.

Database migrations and rollbacks

Rollbacks restore code, not data. If a deployment’s release command already ran a migration before the deployment was rolled back, that migration is not undone — the previous code keeps running against the new schema. Write migrations so that’s safe:

• Add first, remove later. Add a new column or table in one deployment and start writing to it; only drop the old one in a later deployment, once nothing reads it anymore.
• Widen before you narrow. Add a new enum value (or loosen a constraint) in a deployment before any code writes it, so a rollback to the previous code isn’t left looking at a value it doesn’t understand.
• Never edit a migration that already ran. Write a new one instead — an edited migration can behave differently on an Environment that already applied the old version of it.

For apps with a PostgreSQL database attached, every deployment whose release command runs records a data restore point — the moment right before the command started — shown on the deployment page. It marks a point you could restore the database to; restoring is a separate, deliberate action, not something a rollback does for you.

Rolling back by hand

A deployment that failed can be rolled back manually too — useful when automatic rollback is off. You need the Promote & roll back capability on the Environment.

In the dashboard, open the failed deployment’s page and click Roll back.

From the CLI:

paas deploys rollback 42

Without a number, it rolls back the Environment’s most recent deployment, if that one ended Failed or Rollback failed; when a newer deployment is live, it stops and asks for a number instead. A manual rollback of deployment N goes back to the version that was live before N. It asks for confirmation; skip that with --yes. Only the most recent deployment can be rolled back this way — for an earlier one, push a fix (or revert the commit and push that) in a build Environment, or promote the version you want in a promote-only one.

This is different from paas rollback --to <id>, which re-pins a promote-only Environment to any earlier version it has run, healthy or not — see Pipelines, Promotion & Rollback.

Build and release logs

Build and release logs stream live on the deployment page (and through paas watch, unless you pass --quiet) while they’re running; seeing them needs Deploy & operate or Promote & roll back. Afterwards, each deployment keeps its build log (the last 1 MB) for the Environment’s 1,000 most recent deployments, and its release log alongside it:

paas logs --build 42
paas logs --build 42 --release

When the deployment covers more than one app (a shared build or a push to an Environment remote), pass -a <APP> to pick whose build or release log to print — it’s required. If a log wasn’t saved and is older than 30 days, or the underlying log store is unreachable, the platform says so rather than showing nothing: “This log is no longer available.”

These are separate from your running app’s own logs — see Logs.

Next steps

• How Builds & Deployments Work
• Pipelines, Promotion & Rollback
• Creating a Background Worker — worker health checks
• Logs
• Restarting an App
• d2o-paas.yaml Reference and Procfile — move these settings into your repository

Deploying from CI

A deployment token lets a CI pipeline (GitHub Actions, GitLab CI, or any other) push to d2o without anyone’s personal credentials. Each token can push to exactly one remote: an environment’s remote, or one app’s own remote. It keeps working when the person who created it leaves your organization.

Create a token

In the dashboard, open the environment’s Settings → Deployment tokens (or an app’s Settings for the app’s own remote) and choose Create deployment token. Copy the token straight away: it is shown once. With the CLI:

paas deploy-tokens create ci-main -e production
paas deploy-tokens create ci-admin -e production -a admin --expires 90

A token never expires unless you choose 30, 90 or 365 days when creating it.

Creating or revoking an Environment’s tokens requires manage access to the Environment; an app’s tokens require manage access to the app. App tokens are listed and revoked with -a <app> too. An app that builds from the Environment’s shared remote has no token of its own: create the token on the Environment instead.

Save the token in your CI as a secret named D2O_DEPLOY_TOKEN.

GitHub Actions

on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: git push "https://x-access-token:${{ secrets.D2O_DEPLOY_TOKEN }}@push.d2o.io/sources/acme/shop/production.git" HEAD:main

GitLab CI

deploy:
  stage: deploy
  variables:
    GIT_DEPTH: 0
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - git push "https://x-access-token:${D2O_DEPLOY_TOKEN}@push.d2o.io/sources/acme/shop/production.git" HEAD:main

Use the remote shown when you create the token. GIT_DEPTH: 0 and fetch-depth: 0 give the push the full history it needs.

Verify the deployment

Run your application’s tests before the push step and limit production credentials to the intended branch and job. A successful git push means d2o accepted the source; the build or rollout can still fail afterward. Inspect the Deployment until it reaches Live.

For a scripted gate, supply a separate account API token through your CI secret store (PAAS_API_URL and PAAS_API_TOKEN), then watch the deployment:

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

A deployment token authenticates Git only and cannot run paas watch or paas manifest check. Account API tokens act with their owner’s permissions; see API Access & Automation. If several jobs can push concurrently, use paas watch --deploy DEPLOY_NUMBER for the specific push instead of following whichever deployment is newest. See deployment tracking.

When a repository is linked directly to GitHub or GitLab, d2o reports deployment status on the commit and can wait for the commit’s CI results. That is another option when you do not want a CI job to hold an account API token.

Rotate or revoke

To rotate, create a new token, update the CI secret, then revoke the old one. Revoking stops the token immediately:

paas deploy-tokens list -e production
paas deploy-tokens revoke ci-main -e production

Deployments made with a token show it as the pusher, for example “deployment token ci-main”. Promote-only environments don’t accept pushes, so they don’t offer deployment tokens.

Deploy from GitHub or GitLab

Link an Environment or an app to a repo and branch on GitHub or GitLab, and every push deploys it automatically — no CI pipeline or deployment token required.

Connect a provider

Connections are made per Organization, in Organization Settings → Integrations. Connecting requires being an owner or admin of the Organization. From the CLI, paas connections connect -o acme prints the Integrations page link; connecting itself happens in the browser.

GitHub

1. Click Connect GitHub. GitHub asks you to install the d2o PaaS app on an account or organization and choose which repositories it can see.
2. Only an owner of that GitHub account or organization can connect it — the app requests read access to organization members to confirm this. If someone who isn’t an owner installs it, GitHub holds the installation for an owner to approve; connect again once it’s approved.
3. You’re returned to the Integrations page with a “GitHub connected” message, and the connection shows as Active.

A broken connection shows Reconnect; every connection also has a Disconnect button. Disconnecting in d2o removes the connection and its repo links, but does not uninstall the app from GitHub. To remove its access there too, uninstall it on GitHub: for a personal account, Settings → Applications; for an organization, the organization’s Settings → GitHub Apps.

GitLab.com

Click Connect GitLab and authorize d2o on GitLab’s consent screen. You’re returned to the Integrations page with a “GitLab connected” message, and the connection shows as Active.

Self-managed GitLab

Self-managed instances use an OAuth application you register yourself, in this order — GitLab only issues the Application ID and Secret once the application exists, so registration comes first:

1. Click Connect self-managed GitLab. The form shows the Redirect URI to register with a Copy button.
2. On your GitLab instance, go to User Settings → Applications (or Admin → Applications for an instance-wide application) and create a new application with that Redirect URI, Confidential checked, and the api and read_api scopes.
3. Fill in Host, Client ID (GitLab’s Application ID) and Client secret (GitLab’s Secret), then click Continue.
4. Authorize on GitLab.

Your GitLab instance must be reachable over HTTPS from the internet for d2o to exchange tokens and deliver webhooks.

An application registered with only the api scope still deploys, but nobody can choose a repository through it: add the read_api scope to the application on your GitLab instance (no need to reconnect).

Link a repo to an Environment or app

Linking makes a repo and branch the source of truth for a deployment target. Whether you link the Environment or an app depends on how the app builds:

• An app that builds from its own remote — link the app, in the app’s Settings.
• An app that builds from the Environment’s shared remote — link the Environment instead, in the Environment’s Settings → Deploy from GitHub/GitLab tab.

Linking the Environment needs at least one app that builds from its shared remote (created with paas apps create NAME --shared-source); until one exists, a repo linked there would never deploy, so linking it is refused with “No app in this environment builds from its shared source”. Link the app instead, or create the shared-source app first. Don’t link the same repo to both the Environment and an app that builds from its own remote — only the app’s link can deploy it.

The same repo and branch can feed several Environments or apps at once — for example a staging and a production Environment both deploying from main.

In the dashboard:

1. Open the Environment’s Settings → Deploy from GitHub/GitLab tab (or the app’s Settings for an app’s own remote — it’s the same editor).
2. Pick a Connection, then search for the repo in Repository and pick a Branch.
3. Review Wait for CI (enabled by default) and Allow direct pushes (disabled by default), then click Save. The summary shows Provider, Repository, Branch, Wait for CI and Direct pushes, one per line.

Linking a GitLab repository uses your own GitLab account. The picker shows only projects where you are a Maintainer, and linking a project needs Maintainer access to it. The first time, click Choose with your GitLab account (for a target that is already linked, click Edit settings first); GitLab asks you to authorize d2o to read your projects, and the verification lasts about two hours. Deploys still run through the organization’s GitLab connection, so its account needs access to the project too. Changing only the branch or options of an existing link needs no verification.

To change the connection, repository, branch or either option, choose Edit settings. Save changes applies the form together; Cancel discards it. Saving settings does not start a deployment by itself. Disabling Wait for CI can release requests already waiting for checks when you save.

If settings save but automatic updates cannot be connected, the page says so and offers Retry. Your saved settings remain visible.

With the CLI:

paas connections list
paas links set --connection <id> --repo acme/shop --branch production -e production
paas links set --connection <id> --repo acme/shop --branch production -e production -a web
paas links get -e production

--connection <id> is the ID from paas connections list. --repo takes owner/name or a numeric repo id. paas links get prints the same “Deploys from …” line, plus whether direct pushes are allowed, whether it waits for CI, and a “Last push” line for the most recent push’s state.

What happens on a push

Pushing a commit to the linked branch deploys it — the same deployment that a direct push to d2o’s own remote would trigger. There’s nothing else to configure.

• Branch deletions and tags are ignored.
• A force-push deploys the branch’s new head, even if it rewrites history.
• If two pushes land close together, only the later commit deploys — the one it replaces is simply superseded, not deployed.

Wait for CI

Wait for CI is enabled by default, including on existing links. A push waits for the commit’s checks before deploying:

• On GitHub: the commit’s check runs and commit statuses. Skipped or neutral checks count as passed; cancelled, timed-out or action-required ones count as failed.
• On GitLab: the commit’s job statuses on the linked branch, plus any statuses other tools post, using each job’s latest run. Jobs allowed to fail, and skipped jobs, never block. A manual job that isn’t allowed to fail blocks the deployment until someone runs it; after 2 hours the push is refused. A commit pushed with [skip ci] has no checks, so it deploys after 10 minutes.
• d2o’s own d2o: … checks never count.

If the commit has no checks at all, d2o waits 10 minutes and then deploys it anyway, with a “No checks found; deployed without waiting” note. If checks are still running after 2 hours, the push is refused instead of deploying.

If a newer push arrives on the same branch while an earlier one is still waiting on checks, the earlier push is dropped and never deployments, even if its checks later succeed: its check on the commit shows “Replaced by a newer push”, while inside d2o the push itself shows “A newer push replaced this one.”

To change it in the dashboard, choose Edit settings, change Wait for CI, then Save changes. You can also set it explicitly with the CLI:

paas links set --connection <id> --repo acme/shop --branch production -e production --wait-for-ci true

The current CLI replaces the whole link and sends an explicit value for this option. Include --wait-for-ci true when saving through the CLI to keep it enabled.

set replaces the whole link, so --wait-for-ci must be repeated on every set to keep it on (the same as --allow-direct-push).

Status on your commits

Every push to a linked branch gets its own check on the commit, named d2o: production for an Environment link or d2o: production/web for an app link.

• On GitHub, it shows up among the commit’s checks, and on any pull request whose head is that commit.
• On GitLab, it’s a commit status, and it also shows in the pipeline view.

The check moves through the same stages as the deployment — queued, then in progress, then a final state (success, or failure/cancelled on GitHub and failed/canceled on GitLab) — with a summary such as “Waiting for checks”, “Building”, “Rolling out”, “Live”, a deployment failure reason, a checks-failed or timed-out detail, or “Replaced by a newer push”. Clicking it opens the deployment on d2o, or — before a deployment exists yet — the Environment’s Deployments page.

On GitHub, the check’s heading names the outcome and the deployment — for example “Live in production — deployment #12” — and its details say what happened (where each app is live, or which app failed at which step, with a link to its logs), followed by a table of the deployment, project / environment, commit, who pushed it and, once live, how long it took from push to live. GitLab shows only the short summary.

A push that ends without deploying for a reason other than a failure — replaced by a newer push or deployment, built but waiting for you to deploy it (“Built — deploy it from d2o to go live”, when the Environment’s Automatic deployment is off), or unlinked (“Unlinked from d2o”) — ends as neutral on GitHub.

GitLab counts d2o’s status as part of your pipeline, so it differs in three ways:

• No status is added while d2o waits for your checks, so it never holds your pipeline open. It appears once the build starts. A push replaced, unlinked or timed out before that gets no status at all — its entry in d2o’s Deployments page still says why.
• A build waiting for you to deploy it shows as success: the build itself succeeded.
• A deployment replaced by a newer one, or unlinked partway, ends as canceled, which also marks that pipeline canceled.

Direct pushes

Once a target is linked, direct pushes to its d2o remote are blocked by default, so what’s running always matches the linked repo. A blocked push is refused with:

This environment deploys from GitHub acme/shop@production. Push there instead, or allow direct pushes in the environment's settings.

(An app-linked target says “This app deploys from … in the app’s settings.”)

Cloning and fetching from the d2o remote are never blocked — only pushes.

To allow direct pushes alongside the linked repo, choose Edit settings, turn on Allow direct pushes, and Save changes on the same settings tab, or re-run paas links set with --allow-direct-push (it replaces the whole link, so the flag must be repeated):

paas links set --connection <id> --repo acme/shop --branch production -e production --allow-direct-push

Deploy latest

Deploy the branch’s current head on demand, without waiting for a new push — useful right after reconnecting a broken connection, or if a push’s webhook never arrived.

With Wait for CI on, Deploy latest waits for the commit’s checks too. It answers “Deploying abc1234”, “Waiting for checks on abc1234”, or “Already deployed abc1234” when that commit is already live.

In the dashboard: open the linked target’s settings (the same Deploy from GitHub/GitLab editor) and click Deploy latest.

With the CLI:

paas links deploy-latest -e production

Troubleshooting

Connecting fails. After GitHub or GitLab sends you back to the Integrations page, you may see:

• “Only an owner of the GitHub account or organization can connect it. If you are an owner, ask GitHub to approve the app’s updated permissions, then try again.”
• “Your GitHub account can’t access that installation.” — you don’t have access to the GitHub installation that was used; connect with an account that does, or pick a different installation.
• “This GitHub installation is already connected to another organization.” — each GitHub installation can only back one d2o Organization; disconnect it from the other one first, or install the app again for a different account/organization.
• “The connection took too long. Start again.” — the attempt expired before you finished on GitHub/GitLab’s side; click Connect GitHub/Connect GitLab again.
• “Couldn’t finish connecting. Try again.” — a generic failure; retrying usually works.

The connection shows “Broken”. Click Reconnect on it in Organization Settings → Integrations. Reconnecting repairs the connection in place — your repo links are kept, and nothing needs relinking.

A self-managed GitLab connection shows “Not finished”. The GitLab sign-in was started but never completed. Either Disconnect it, or click Reconnect: the form reopens with the host locked, and leaving Client ID and Client secret blank keeps the current ones.

A push doesn’t deploy. Check its state on the dashboard’s Deployments page or with paas links get, or on the Environment’s Deployments page under “Pushes not yet deployed” (it lists pushes waiting for checks and ones that failed checks, timed out or couldn’t be fetched; replaced pushes, and failures already followed by a successful deployment, aren’t listed). If two pushes land close together, only the later commit deploys — that’s expected, not a failure. With Wait for CI on, the “Last push” line shows why, and on GitHub so does the commit’s check:

• “Not deployed: checks failed (…)” — one of the commit’s checks failed; fix it and push again, or, if the check was flaky, re-run it and then use Deploy latest to re-check the same commit without a new push.
• “Not deployed: checks were still running after 2 hours” — the checks never finished in time; this also covers a GitLab manual job nobody ran — run it, then push again or use Deploy latest.
• “No app in this environment builds from its shared source, so this push wasn’t deployed” — the Environment is linked, but none of its apps builds from the shared remote. Link the repository to the app instead (and unlink the Environment), or create an app that builds from the shared source.

Otherwise, try Deploy latest; if it keeps failing, reconnect the provider in Integrations.

Unlinking: click Unlink on the linked target’s settings and confirm Unlink repository, or run paas links unset -e production. Direct pushes are allowed again immediately.

Follow a requested deployment

Deploy latest opens the deployment request immediately. You can see whether it is waiting for checks or importing the commit. When the deployment starts, the page opens its numbered details automatically. If that commit is already deployed, it opens the existing deployment instead.

Failed checks, timeouts, import errors and requests replaced by a newer request remain visible with their reason. The request keeps the repository and branch it started from, even if you later change the settings.

While direct pushes are blocked, the deployment-token page keeps existing tokens visible so you can revoke them. It hides token creation until you enable direct pushes.

Pipelines, Promotion & Rollback

A Project is a pipeline: its Environments are stages, ordered development → staging → production. Promotion moves the image an app already built in one stage into the next stage, without rebuilding it. This page explains how a stage gets its images, how to promote and roll back, and what the platform refuses and why.

Build stages and promote-only stages

Every Environment has a release source:

New Environments always start as Builds from source. Switch an Environment to promote-only in the dashboard under the Environment’s Settings → General → Release source, or from the CLI:

paas envs update production -o acme -p shop --release-source promote

A stage is either one or the other, never both. The usual shape is one build stage (development) feeding one or more promote-only stages (staging, production).

What the switch does

Switching to promote-only removes the Environment’s build machinery. It is refused with UNPINNED_APPS if any app in the Environment has never been built or promoted — such an app would have no image to run. Build or promote it first, then switch.

Switching back to builds from source recreates the build machinery: the platform rebuilds every app from the branch and deploys the new builds, replacing whatever had been promoted. The dashboard asks you to confirm before it does this.

Creating an app in a promote-only stage

You can create an app in a promote-only Environment as long as an app with the same name exists in the stage upstream. The new app starts with the upstream app’s current image. If there is no upstream image yet, the app is created but nothing runs until the first promotion; the pipeline board shows it as awaiting first promotion.

The pipeline board

Open a Project’s Pipeline tab. The Project Overview lists its environments. Application cards line up across environments; a placeholder shows when an application is missing.

Databases and Object storage have separate sections with their status and configured size, version or storage tier. They link to resource details and are not promoted. Build stages show Built here or Awaiting first build instead of comparing themselves with an upstream stage.

The Pipeline page shows one column per stage. Each app card shows the running image’s short digest and, where the platform knows it, the commit it was built from, plus one of:

Promoting

Promotion copies the image digest from the same-named app in the source stage into the target stage. Databases, buckets, secrets and environment variables are per-Environment and are never copied.

You need the Promote & roll back capability on the target Environment and View on the source. The target must be promote-only; promoting into a build stage is refused with BUILD_ENV.

From the dashboard: each stage column has a Promote all apps to next button that promotes every app present in both stages. For one app, open its card’s actions menu and choose Promote to next. If the stage’s button is disabled, the reason shows under it (“production builds from source — set its release source to promote-only first”, or “Requires promote on production”), and the per-card buttons are hidden.

From the CLI:

# one app
paas promote web --from staging --to production -o acme -p shop

# every app that exists in both stages
paas promote --all --from staging --to production -o acme -p shop

The result is a table with one row per app:

The CLI exits 1 when any row errored, or when you named a single app and it was skipped for any reason other than ALREADY_CURRENT. paas promote --all with everything already current exits 0.

Protected targets

Promoting into a protected Environment asks you to type the Environment’s name to confirm. The CLI does the same, or skips the prompt with --yes; without a terminal and without --yes it refuses before sending anything. Every promotion is recorded in the Organization’s audit log.

Rolling back

On a promote-only stage you can re-pin an app to any earlier image it has run in that Environment. Rolling back needs the Promote & roll back capability on that Environment.

From the dashboard: open the app and click Rollback… in its header. The picker lists this app’s earlier releases, newest first, from its last 100 deployments, excluding the one currently running.

From the CLI: find the deployment id (id) with paas releases --json -a web, then:

paas releases --json -a web -e production -o acme -p shop
paas rollback web --to 6f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c00 -e production -o acme -p shop

Rollback is refused with BUILD_ENV on a build stage (push a fix or re-deploy instead), with ALREADY_CURRENT when the app already runs that image, and with a 404 when the id belongs to another app.

This re-pins to any earlier version this app has run, healthy or not. To roll back a deployment that failed its health check, in any Environment, use paas deploys rollback instead — see Deployments, Health Checks & Rollback.

What a promote-only stage refuses

Reading the history

Deployment history marks each entry as a build, a promote or a rollback — promote entries read “promoted from source by name”. paas deploys list --json includes the same kind and each deployment’s id, which is the argument paas rollback --to takes.

Next steps

• Deployments, Health Checks & Rollback
• Organizations, Projects & Environments
• Access Control
• CLI Command Reference

Checking dependencies before promotion

Before promotion, d2o checks the selected applications’ database and object-storage attachments and known connections to other applications. A target service can have a different name if the application has the same compatible binding there.

If dependencies are missing, review the warning and explicitly confirm before continuing. A protected environment also requires its name in the same confirmation. If the dependency warnings change before the request is applied, you must review them again.

If the CLI reports missing dependencies, attach the required services first or review and confirm the promotion in the dashboard.

This check covers known attachments and application connections; it cannot infer dependencies hidden in secrets or external services. Promotion only moves application images. It does not create dependent services or copy databases, objects, secrets or environment-variable values.

Restarting an App

A restart replaces the running instances of a Web Application or Background Worker with fresh ones. It does not rebuild your app, pull new code, or change any configuration — the same release comes back up, just in new instances.

What a rolling restart does

Restarts are rolling: the platform starts a replacement instance and stops an old one only once the replacement is ready, so with a Health Check Path set the app keeps serving throughout — even with a single instance. Without a health check, the rollout only requires the replacement to stay running for 10 seconds (web apps) or 30 seconds (workers); this does not prove the app can serve requests. See Health checks. A singleton app is the exception: its old instance stops before the new one starts, so it is briefly down.

When you need one

Most changes on the platform roll out on their own — a git push triggers a build and deployment, and a deployment already brings up fresh instances. Reach for a restart when the instances themselves are the problem:

• Picking up a deleted and re-created secret. Binding a secret or changing its value already rolls out new instances. Creating a replacement for a deleted secret does not; restart if an instance started while that secret was absent. See the secret lifecycle.
• Clearing bad in-memory state. A wedged connection pool, a memory leak, a stuck background job — a restart gives every instance a clean start.

A restart will not fix a broken build or bad code. If the app is failing because of what was deployed, fix the code and push again, or roll forward with a new deployment — see Deployments, Health Checks & Rollback.

Restart from the dashboard

1. In the dashboard, open your Organization, then the Project, then the Environment (for example acme → shop → production).
2. Open the app (for example web).
3. Click Restart and confirm.

Restarting requires deploy access. A stopped app (scaled to 0) can’t be restarted — scale it up instead. An app blocked for going over its monthly transfer allocation can’t be restarted either.

The app’s instance list updates as old instances are replaced by new ones.

Restart from the CLI

paas restart restarts the app you point it at with the usual context flags:

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

Options:

• -o, --org, -p, --project, -e, --env, -a, --app — select the app to restart
• --json — print the raw API response instead of a table
• --host <HOST> — target a specific platform address (overrides PAAS_API_URL and the configured current host)

Watch the restart complete by listing the app’s instances:

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

or check the app’s deployment status:

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

Restart vs. deploy

• Restart (paas restart): fresh instances of the current release. Use it to re-read secrets or clear state.
• Deploy (paas deploy): triggers a deployment of the app, applying whatever is currently configured. Use it when you changed what should be running, not just how it’s running.

Next steps

• Logs — confirm the app came back healthy after a restart
• Managing Secrets — automatic rollout and the re-created-secret exception
• Deployments, Health Checks & Rollback — when a restart isn’t enough
• Scaling & Autoscaling — run more instances, spread across servers

Logs

Every Web Application and Background Worker has a log view: a live stream while the app is running, and a snapshot of the most recent lines when it is not. Reading the log snapshot requires view access; streaming logs live (the dashboard’s live view and paas logs --tail) requires Deploy & operate or Promote & roll back — see Access Control.

In the dashboard

Open your app’s Resource page and go to the Logs tab.

While the app is running, logs stream in live automatically — the footer shows a Live indicator, and the Pause button stops the stream and becomes Stream to resume it. If the stream is interrupted (for example, an instance restarts), it reconnects on its own and continues from the new instance.

The viewer also gives you:

• Level filter — narrow the view to Errors, Warnings, Info, or Debug. Levels are detected from the text of each line, so they are best-effort.
• Auto-scroll — the view stays pinned to the newest line. Scroll up to read something older and auto-scroll pauses so new lines don’t pull you back down; the Jump to latest button re-pins it.
• Line buffer — the live view keeps roughly the last 1,000 lines.
• Instance filter — when the app runs more than one instance, each line shows which instance wrote it, and the Instance menu narrows the view to one of them (or All instances).

When the app is not running — it crashed, failed to boot, or was stopped — the live stream can’t open. The Logs tab falls back to a snapshot of the last log lines, marked Snapshot — resource not running, which is exactly what you want for a post-mortem.

Snapshot logs with the CLI

paas logs prints a snapshot of recent log lines. Select the app with the usual scope flags:

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

Add --json to get the raw API response instead of plain log lines. The remaining examples assume the same -o/-p/-e scope flags.

Live streaming with the CLI

Add --tail to follow logs live:

paas logs -a web --tail

The stream follows every running instance of the app, starting from each one’s last 200 lines, and picks up new instances as they start; once more than one instance has logged, each line is prefixed with [instance]. Pass --instance to follow just one. Combining --tail with --container, -n, or --json is a usage error. Press Ctrl+C to stop.

Viewing one instance

By default the snapshot and the stream show every running instance. To see just one, list the app’s instances first:

paas ps -a web

Then pass an instance name to --instance:

paas logs -a web --instance web-6f7c9d4b8-xkq2n -n 200

-n, --num (default 500) controls how many lines the snapshot returns, and --container narrows it within an instance — most apps never need it. These two work only with snapshots; --instance works with both.

While a build is in progress

Right after a deployment there may be no app logs yet, because your new image is still being built. Instead of failing with a bare “no logs” error, the log stream reports the build state:

• the build hasn’t started yet,
• the image is still building,
• the build failed (with the build’s error message),
• or the image is built but no instance is running yet (rollout pending).

Once the first instance is running, logs flow as usual. To check build and deploymentment status, use paas releases — it lists the environment’s recent deployments and their states — or the deployment history in the dashboard, which refreshes automatically — see Deployments, Health Checks & Rollback.

To read a finished build’s output, open the deployment in the dashboard (its Logs section), or run paas logs --build 42 (add --release for the release command’s log, -a web when the deployment built several apps). Build logs are kept for the Environment’s last 1,000 deployments.

Next steps

• Console & One-off Commands — open a shell in a running instance
• Deployments, Health Checks & Rollback — track builds and releases
• Restarting an App — roll all instances when logs show a wedged process
• Troubleshooting & FAQ

Console & One-off Commands

Sometimes you need to get inside a running app: poke at the filesystem, open a framework console, or run a migration script. The platform gives you three ways in, for Web Applications and Background Workers:

• an interactive Console in the dashboard,
• paas exec for an interactive terminal from your own shell,
• paas run for one-off, non-interactive commands.

Consoles are only available for resources that run your code. Databases and Object Storage buckets have no console — manage databases through attachments and buckets through the Files tab or paas buckets.

To open a console or run a command you need the deploy permission on the project, and the app needs at least one running instance — the dashboard’s Connect button is only enabled while the app’s status is running. See Access Control.

List running instances

Each app runs as one or more instances (set by its replica count or autoscaling). paas ps lists them:

$ paas ps -o acme -p shop -e production -a web
INSTANCE             PHASE    READY  CONTAINERS
web-7d9f6c5b48-2xqkm Running  true   web

If no instance is ready because a build is still in progress (or a build failed), paas ps prints the reason below the table. Add --json for the raw API response.

Inside a repository with a d2o (Environment) or paas (app) git remote, the CLI infers -o/-p/-e from it — and -a from the paas remote, or from the directory you’re in for apps built from the Environment’s remote — so a bare paas ps works. Elsewhere, pass the flags, or set defaults with paas orgs set-default and paas projects set-default (environment and app must always come from the flag or the remote).

Console in the dashboard

1. In the dashboard, open the environment and click the app.
2. Open the Console tab.
3. Pick an instance from the dropdown — the first ready one is pre-selected.
4. Click Connect.

You get a shell (/bin/sh by default — change the command field before connecting if you want something else, like a framework console). Run commands as you would in any terminal; press Ctrl+D or click Disconnect to end the session.

The session stays alive if you switch to another tab of the same app — for example to glance at Logs — and is still connected when you come back.

If the tab shows “Resource must be running to connect to console”, the app has no ready instance yet; check its status on the Overview tab and its deployments.

Interactive terminal with paas exec

paas exec opens the same kind of session from your own terminal:

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

You land in /bin/sh on a running instance. Exit with exit or Ctrl+D.

Options:

• --command <COMMAND> — start something other than /bin/sh.
• --instance <INSTANCE> — connect to a specific instance, by the name shown in paas ps. Without it, the first running instance is used.
• --container <CONTAINER> — only needed if an instance runs more than one named process; normally leave it out.

paas exec requires a real terminal: it refuses to start when stdin/stdout is not a TTY (a script, CI), and --json is not supported — there is nothing to render as JSON in an interactive session. For scripted work, use paas run.

One-off commands with paas run

paas run executes a single command on a running instance and prints its output. The -- before the command is required, so its flags aren’t parsed as paas run’s own:

paas run -o acme -p shop -e production -a web -- ls -la
paas run -a web -- ./bin/rails db:migrate

The command runs without an interactive terminal, so it must not expect input. paas run prints the command’s standard output; its error output is shown only when it printed nothing else (and paas run then exits 1). The command’s own exit status is not relayed, so check the output to see whether it worked. --instance and --container work the same as for paas exec, and --json returns the raw API response.

Next steps

• Logs — snapshot and live-streamed app output
• Restarting an App — roll all instances without a deployment
• Scaling & Autoscaling — control how many instances run
• Command Reference — every paas command and flag

Metrics

Every Web Application and Background Worker shows live resource usage in the dashboard, so you can see what your app is actually consuming without leaving the page you deploy from.

What is measured

• CPU — processor usage in cores, summed across all of the app’s running instances.
• Memory — working-set memory in bytes, summed across all running instances.
• Throughput (Web Applications only) — HTTP requests per second arriving at the app’s public endpoint.
• p95 latency (Web Applications only) — the response time that 95% of requests beat, in milliseconds.

Throughput and latency are measured at the platform’s edge, so they reflect real traffic to your app’s URL. They only appear for Web Applications, and only once the app has received some traffic — a Background Worker has no public endpoint, so it shows CPU and memory alone.

Where to find them

1. In the dashboard, open your Organization, then the Project and Environment (for example acme → shop → production).
2. Click the app — say web.
3. You land on the Overview tab. The usage panel sits inside the Deployment Status card at the top of the page.

Each metric shows its latest value with a small trend sparkline next to it. If the app has CPU or memory limits configured, the panel also shows usage against the limit — for example 128Mi / 256Mi · 50% — with a bar that changes color as you approach the limit. That makes it easy to spot an app that needs a bigger memory allowance or more instances before it becomes a problem.

For a longer view, open the app’s Usage tab: Live metrics shows the same meters over the last 1 hour, 6 hours or 24 hours (pick the range at the top of the card), next to the app’s bandwidth this month.

Time range and freshness

The Overview panel shows the last hour of data at roughly one-minute resolution (the Usage tab’s 6-hour and 24-hour ranges use 5- and 15-minute steps). While the page is open it refreshes automatically every 30 seconds, so you can watch the effect of a deployment, a scale change, or a traffic spike as it happens.

When metrics are missing

• “Resource metrics unavailable” — the installation you are using has no metrics backend configured. Ask your platform operator.
• “No recent samples” — the panel is working but has nothing to show yet. A freshly deployed app takes a short while to produce its first samples, and a stopped app (zero instances) produces none.
• No throughput or latency meters — either the resource is a Background Worker, or the Web Application has not yet received any HTTP traffic.

A metric that temporarily fails to load shows as an empty series rather than an error; the rest of the panel keeps working.

Metrics and the CLI

There is no paas command for usage metrics today — they live in the dashboard. From the CLI you can still check on a running app:

paas status -o acme -p shop -e production -a web # deployment status and health
paas ps -o acme -p shop -e production -a web   # list the app's running instances
paas logs -o acme -p shop -e production -a web --tail

Using metrics to act

• Memory climbing toward its limit on every instance: raise the app’s memory limit or add instances — see Scaling & Autoscaling.
• CPU pinned high while p95 latency grows: add instances, or turn on autoscaling so the platform does it for you.
• Throughput at zero when you expect traffic: check Logs and the app’s public URL on its Overview tab.

Next steps

• Scaling & Autoscaling — act on what the meters show
• Logs — pair usage numbers with what the app is printing
• Deployments, Health Checks & Rollback — correlate a change in the graphs with a deployment
• Plans, Limits & Usage — how per-app limits are set

Custom Domains & TLS

Every Web Application gets a generated address on the platform the moment it is created. When you are ready to serve traffic on your own domain, you attach one — and prove that it is yours. Once ownership is proved, the platform routes the domain to your app and issues a TLS certificate for it automatically.

Custom domains apply to Web Applications only. Background Workers and Databases are not reachable over HTTP and have no domains to attach.

The default app URL

Each Web Application is assigned a generated hostname — a random subdomain under the platform’s app domain — with HTTPS enabled from the start. You’ll find it on the app’s page in the dashboard and on its Domains tab, under Platform Endpoint.

This address always works, TLS included, and it keeps working after you add custom domains: custom domains are aliases for it, not replacements. That makes the platform endpoint a reliable fallback for health checks and for verifying a deployment while a new domain is still being set up.

The flow, end to end

Attaching a domain takes four steps:

1. Add the domain to your app. This creates a claim on the name. Nothing is routed and no certificate is requested yet.
2. Create the ownership record — a TXT record at your DNS provider that carries a token unique to your organization and that domain.
3. Verify. The platform looks the record up and, when it matches, marks the domain verified.
4. Point the traffic record (CNAME, or ALIAS for a root domain) at your app’s platform endpoint. The certificate is issued automatically, and the domain goes live.

Steps 2 and 4 are two separate DNS records, and both are shown to you when you add the domain. You can create them at the same time — the order does not matter.

Add the domain

In the dashboard:

1. Open your Web Application (for example the web app in the production environment of the shop project) and go to the Domains tab.
2. Under Custom Domains, enter the hostname you want — for example app.example.com — and click Add Domain.
3. The domain appears as Not verified, with both DNS records to create listed next to it.

With the CLI:

paas domains add app.example.com -o acme -p shop -e production -a web

paas domains add prints both records:

Added app.example.com to web. It is not served yet — the platform needs proof that you own it.

Create these DNS records at your DNS provider:

 TYPE   NAME                         VALUE
 TXT    _d2o-verify.app.example.com  d2o-verify=0123456789abcdef0123456789abcdef
 CNAME  app.example.com              k3j2h1.cx.d2o.io

Adding a domain requires the manage_web_apps permission on the project (organization Owners and Admins have it automatically). See Access Control.

The ownership record

The TXT record is the proof:

The token is unique to your organization and that one domain. Never share it: it is what proves the name is yours.

Some DNS providers want the name relative to the zone rather than fully qualified — in the example.com zone, enter _d2o-verify.app instead of _d2o-verify.app.example.com. If in doubt, create it and check with dig TXT _d2o-verify.app.example.com before verifying.

The traffic record

Point the domain itself at your app’s Platform Endpoint hostname, shown on the app’s Domains tab and printed by paas domains add:

• CNAME for a subdomain such as app.example.com.
• ALIAS for a root (apex) domain such as example.com, where a CNAME is not allowed. Some DNS providers call this an ANAME record. If yours supports neither, serve the app from a subdomain such as www.example.com instead.

DNS changes can take anywhere from minutes to hours to propagate, depending on your provider and record TTLs.

Verify

Once the TXT record is live, verify the domain:

paas domains verify app.example.com -o acme -p shop -e production -a web

In the dashboard, click Check now next to the domain on the Domains tab.

If the record has not propagated yet, verification fails and says so — nothing is lost, just try again in a few minutes. The platform also re-checks unverified domains on its own in the background, so a domain you added and then forgot about will verify itself once its record shows up.

Unverified claims are not kept forever: a domain left unverified for 7 days is dropped, and you’ll have to add it again. That only affects unverified claims — a verified domain stays until you remove it. An organization can have at most 25 unverified domains at a time, and 50 custom domains in all; verify or remove one before adding more.

Statuses

Each domain is in one of four states. The Domains tab shows it as a badge, paas domains list prints it in words, and --json returns the raw value:

A claim you have added but not yet proved usually reads error, not unverified: the platform re-checks unverified domains in the background, and once it has looked for a record that is not there yet, it records “We have not seen the verification record for <domain> yet.” against the claim. That is expected — create the TXT record and verify.

paas domains list -o acme -p shop -e production -a web

 DOMAIN            STATUS                ADDED
 app.example.com   verified, setting up  2026-09-20
 shop.example.com  error                 2026-09-22

shop.example.com: We have not seen the verification record for shop.example.com yet.

A domain marked "not verified" is not served: create its ownership record, then
run `paas domains verify <domain>`. "Verified, setting up" means the certificate
is still on its way.

Every hostname is verified on its own

Proving example.com does not cover www.example.com, api.example.com, or any other subdomain. Each hostname you want to serve is added and verified separately, with its own TXT record. There is no wildcard support.

When a domain is already in use

A domain can be attached to only one app in your organization; adding it to a second app fails with “domain is already added to one of your apps” — remove it from the other app first.

Adding a domain that another organization has already verified fails:

That domain is already in use on the platform.

In the dashboard the same rejection offers a Release it button, which runs the release below for you. The platform will not say who holds it, and it will never hand a verified domain over automatically — not even to an organization that later proves ownership. This is deliberate: it is what stops someone from taking a live domain away from the app that is serving it.

Several organizations can each hold an unverified claim on the same name at once. Only the first to verify it gets it; the others stop being checked, show error with the same “already in use” message, and expire.

Releasing a domain you own

If a domain of yours is being served by an organization that should no longer have it — an old team account, a contractor’s organization, a project that moved — you can free it by proving you own the name:

paas domains release example.com -o acme

The platform asks for the same kind of TXT record, using your organization’s own token for that name. Create it, run the command again, and on success:

• the domain is detached from the app that was serving it, and stops routing there straight away;
• both organizations get an entry in their audit log;
• the owners of the organization that held it are emailed.

Releasing a domain does not attach it to your app. Once it is free, add it and verify it the normal way:

paas domains add example.com -o acme -p shop -e production -a web
paas domains verify example.com -o acme -p shop -e production -a web

If nobody is serving the domain, there is nothing to release — just add it.

In the dashboard you do not need the CLI for this: whenever a domain is refused because another organization holds it — when you add it, and when you choose Check now on a claim that lost the race — the Domains tab offers a Release it button that runs the same release and tells you which record to add if it is missing. Once it succeeds the name is yours to verify: released from the add form, the domain is added for you; released from a claim you already hold, choose Check now again.

Releasing needs organization Owner or Admin — see Access Control. Adding and verifying the freed domain afterwards needs manage_web_apps on the project, as usual.

Automatic certificate issuance

Once a domain is verified and its traffic record resolves to the platform, a TLS certificate is requested and issued automatically. There is nothing to upload and no renewal to manage.

Both halves are needed: the certificate authority checks the domain over the public internet, so it cannot be issued until the CNAME or ALIAS record is in place.

Remove a domain

On the Domains tab, click Remove next to the domain and confirm — or, with the CLI:

paas domains remove app.example.com -o acme -p shop -e production -a web

This detaches the domain from the app and removes its certificate and routing — requests to that hostname will no longer reach your app, and the name becomes available for anyone to claim again. The app’s platform endpoint is unaffected.

Removing a domain does not touch your DNS records; clean those up at your DNS provider separately.

Domains added before verification existed

Domains that were already attached when verification was introduced are treated as verified and keep serving traffic exactly as before — they read verifying / Verified, setting up until their certificate is ready, like any other proved domain. Their ownership record is still shown in the dashboard and the CLI, so you can create it at your leisure — worth doing, because it is what lets you re-verify the name later if it is ever released.

Troubleshooting

Verification keeps failing. Check the record with dig TXT _d2o-verify.<your domain> (or your provider’s DNS lookup tool). The answer must contain d2o-verify=<token> exactly as shown for that domain. The most common causes are a record created in the wrong zone, a provider that appended the zone name twice (_d2o-verify.app.example.com.example.com), and a TTL that has not expired yet.

Verified, but the domain does not load. The traffic record is the other half. Confirm dig app.example.com returns the app’s platform endpoint, then give issuance a few minutes. Until the certificate is ready the domain reads Verified, setting up (verifying in --json).

The status says error. The reason is shown next to the domain in the dashboard and under the table in paas domains list. Fix what it names and verify again.

Reserved names. Some names cannot be attached — platform-managed domains and a handful of names the operator has set aside. Adding one is rejected with a message saying so; use a domain you control.

Next steps

• Creating a Web Application
• paas domains command reference
• Access Control
• Troubleshooting & FAQ

Move Settings Into Your Repo

Some app settings depend on the code: a health check path only makes sense once your app answers it, a release command only makes sense once the migration it runs exists. Moving those settings into a d2o-paas.yaml file in your repository means they travel with the version they belong to — a rollback restores the code and the settings it needs together, instead of leaving an old version running against a health check or release command meant for the version after it.

This walks through moving a web app’s health check and release command, and a worker’s process, out of the dashboard and into the repository.

1. See what’s set today

paas apps info -o acme -p shop -e production -a web

This prints the app’s current settings, including its health check and release command — whatever you’ve set in the dashboard or with paas apps update up to now. Note down the values you want to move; you’ll write the same ones into the file.

2. Write them into d2o-paas.yaml

Create d2o-paas.yaml at the root of your repository (or the app’s --source-dir, if it has one):

release:
  command: bin/migrate

health_check:
  path: /health

apps:
  worker:
    process: worker

This example moves a top-level health check path and release command — both shared by every app built from this repository — and gives the worker app an explicit process, matching a worker: line in its Procfile. Your own file only needs the fields you’re moving; see d2o-paas.yaml Reference for every field and how apps.<name> overrides the top-level defaults.

3. Check it before you push

paas manifest check -o acme -p shop -e production

$ paas manifest check -o acme -p shop -e production
d2o-paas.yaml is valid for production

This catches a typo’d field name or an out-of-range value before it reaches a build. See d2o-paas.yaml Reference for what an invalid file’s errors look like.

4. Push

git add d2o-paas.yaml
git commit -m "Move health check and release command into d2o-paas.yaml"
git push paas main

After the deployment

Once this version is live, the fields it sets show “from d2o-paas.yaml” in the dashboard and can’t be edited there — paas apps update on one of them fails with a message telling you to change it in the file instead. This is expected: the file is now the source of truth for those fields, for as long as a deployed version sets them.

Handing a field back

To give a field back to the dashboard or CLI, delete it from d2o-paas.yaml and push. Once the new version with the field removed is live, the dashboard and CLI setting applies again — including whatever value it already held, so set it to what you want first if you plan to keep using it.

Next steps

• d2o-paas.yaml Reference — every field, merging rules, errors and warnings
• Procfile — process selection and the release line
• Deployments, Health Checks & Rollback — health checks and the release command in full

Databases

A Database is a managed resource that lives inside an Environment, next to the apps that use it. The platform provisions it, keeps it running, and generates its credentials for you — you never install or operate the database engine yourself.

Four engines are available:

Creating a database requires database-management permission in the project — see Access Control.

Create a database in the dashboard

1. Open the Environment (for example acme › shop › production) and click Add Resource.
2. Choose the Database resource type.
3. Give it a name, such as shop-db. Names use lowercase letters, numbers, and hyphens, and must be unique within the Environment.
4. Under Database Configuration, pick the Database Type: PostgreSQL, Redis, MariaDB, or MongoDB. Choosing PostgreSQL shows a High availability checkbox — see High availability.
5. Set Size (GB): the size of its storage, 1 GB unless you change it. It can’t be changed after the database is created.
6. Click Create Resource.

The dashboard creates the database with the platform’s default version. To choose the version yourself, use the CLI.

Create a database with the CLI

paas dbs create shop-db --type postgresql --storage-gb 20 \
  -o acme -p shop -e production

Created database shop-db

Flags:

• --type (required): postgresql, redis, mongodb, or mariadb.
• --storage-gb: size of the database’s storage volume in GB. If omitted, the database gets 1 GB. The size is fixed once the database is created.
• --version: engine version. Currently honored for MongoDB; PostgreSQL, Redis, and MariaDB run the platform’s standard version regardless of this flag.
• --ha: turn on high availability. PostgreSQL only.

When you run the CLI inside a repository that has a d2o (or paas) git remote, the organization, project, and environment are inferred and you can drop the -o/-p/-e flags. By default a database runs as a single instance; PostgreSQL databases can opt into high availability — see below.

Size, CPU and memory

Every database counts against your plan’s capacity pools for its environment type, like an app — see Plans, Limits & Usage:

• Storage: the size you choose, or 1 GB when you don’t. It can’t be changed after creation, so pick a size with room to grow.
• CPU and memory: each database runs with up to 500m CPU (half a core) and 512 MiB of memory, and counts that much against your plan’s CPU and memory pools.

A database with high availability counts all three twice. A create that doesn’t fit your plan is rejected with the usual LIMIT_EXCEEDED error. The database’s Settings page shows its size, CPU and memory.

Status lifecycle

A database moves through these statuses:

• pending — just created; its configuration is being written.
• provisioning — the engine is being set up and is not yet ready to accept connections.
• running — the database is ready. The platform re-checks readiness continuously, so a database that becomes unhealthy drops back to provisioning until it recovers.
• deleting — being torn down.

Check status from the CLI:

paas dbs list -o acme -p shop -e production

NAME     ENGINE      VERSION  STATUS
shop-db  postgresql  -        running

paas dbs info <name> shows one database in detail:

$ paas dbs info shop-db
shop-db (7c9e6679-7425-40de-963d-a1b2c3d4e5f6)
type: database
status: running
engine: postgresql
version: -
storage: 20 GB
created: 2026-08-31 14:02:11.482193 UTC
high availability: on

The high availability line only appears for PostgreSQL databases.

Add --json to either command for the raw API response.

High availability

PostgreSQL databases can opt into high availability. Off by default, it runs a second, continuously synchronized copy of your database on a different server. If the server running your database fails, the copy takes over automatically within seconds — connections drop briefly and reconnect, which most database drivers and connection pools already handle on their own. While the copy is healthy, writes wait for it to confirm before returning; if the copy is temporarily unavailable, your database keeps accepting writes on its own rather than blocking. Planned maintenance on our side no longer interrupts an HA database beyond a brief switchover.

Turn it on when creating a database — the dashboard’s High availability checkbox, or --ha on the CLI:

paas dbs create shop-db --type postgresql --storage-gb 20 --ha \
  -o acme -p shop -e production

You can also turn it on or off for a database you already have, with no change to its connection string or attachments:

• Dashboard: open the database’s Settings page and use the High availability toggle.

• CLI:

  paas dbs update shop-db -o acme -p shop -e production --ha true
  

Enabling it on an existing database copies the data to the new standby in the background with no downtime; how long that takes depends on the database’s size. Disabling it removes the standby copy; the primary keeps running unaffected.

The database’s Overview page in the dashboard shows High availability: On or Off, and paas dbs info shows the same as high availability: on or off.

Cost: a high-availability database counts twice against your plan’s CPU, memory, and storage pools, since it runs two full copies. A create or update that would exceed your plan’s limits is rejected with the usual LIMIT_EXCEEDED error — see Plans, Limits & Usage.

High availability is available for PostgreSQL only; Redis, MongoDB, and MariaDB databases always run as a single instance for now.

Credentials and connecting

You never copy passwords out of the dashboard. To use a database from an app, you attach it: the platform injects a ready-made connection-string environment variable (by default DATABASE_URL) into the app. See Attaching a Database.

Backups

PostgreSQL and MariaDB databases are backed up automatically. Restoring from a backup requires contacting support. Redis and MongoDB are not backed up — treat Redis as ephemeral, and export MongoDB data yourself if you need copies. See Database Backups.

Delete a database

Deleting a database destroys its data permanently: the database stops, its storage is removed, and its backups are deleted within about an hour. There is no undo. In the CLI:

paas dbs delete shop-db -o acme -p shop -e production

Type "shop-db" to confirm deletion: shop-db
Deleted database shop-db

In scripts, skip the prompt by passing the name back explicitly. Without a matching --confirm, a non-interactive session refuses to delete:

paas dbs delete shop-db -o acme -p shop -e production --confirm shop-db

If you create a new PostgreSQL database with the name of one you just deleted in the same environment before its backups are gone, creation is refused with BACKUPS_PENDING_REMOVAL — wait a little and try again, or pick another name.

Next steps

• Durability and recovery — compare data stores and backup coverage

• Network access — runtime connections and build restrictions

• Attaching a Database — inject the connection string into an app

• Database Backups — what is backed up and how to restore

• Environment Variables — how injected configuration reaches your app

• Plans, Limits & Usage — how many databases your plan allows, and how high availability counts against them

Attaching a Database

Attaching a Database to a Web Application or Background Worker injects a connection-string environment variable into the app — DATABASE_URL by default, or any name you choose. The platform wires the database credentials directly into the variable, so you never copy a password or store the connection string yourself.

Attachments work for all four engines: PostgreSQL, Redis, MongoDB, and MariaDB. If you haven’t created a Database yet, start with Databases.

The same card also attaches Object Storage buckets, which inject a set of S3 credential variables instead of a single connection string — see Object Storage Buckets.

How attachments work

• The Database and the app must live in the same Environment. The dashboard only offers databases from the app’s environment as attach candidates.

• Each attachment injects one environment variable holding a ready-to-use connection string for that engine:

  Engine	Connection string
  PostgreSQL	postgresql://…
  Redis	redis://default:<password>@<host>:6379
  MongoDB	mongodb://… (the standard connection string)
  MariaDB	mysql://<user>:<password>@<host>:<port>/<database>

• The variable is managed by the platform. It does not appear in the app’s editable environment-variable list, and detaching removes it.

• Attaching and detaching require the database-management permission on the project. Organization Owners and Admins have it; other members get it through group permissions.

Attach in the dashboard

1. Open your app — for example Organization acme → Project shop → Environment production → the web application.
2. Go to the Config tab. Below the environment variables you’ll find the Attached Resources card.
3. Pick a database from the dropdown — say shop-db (PostgreSQL).
4. Optionally type a variable name. Leave it blank to use DATABASE_URL.
5. Click Attach.

The attachment appears in the list with the variable name next to the database. The platform updates the app’s deployment configuration so its instances receive the variable.

Choosing the variable name

The default DATABASE_URL is fine when an app uses a single database. When you attach more than one — a PostgreSQL database and a Redis cache, for instance — give each attachment a distinct name so your code can tell them apart, such as DATABASE_URL and REDIS_URL. Names are uppercased automatically as you type.

Attach from the CLI

With CLI 0.9.0 or later, select the app and database explicitly:

paas apps attach web shop-db -o acme -p shop -e production
paas apps attach worker shop-db --env-var REPORTING_DB_URL -o acme -p shop -e production
paas apps attachments web -o acme -p shop -e production

--env-var defaults to DATABASE_URL. The attachment list shows the ID used for detaching, without displaying credentials. To connect Redis alongside the primary database, attach it under --env-var REDIS_URL. See app attachment commands.

Older CLIs support paas attach shop-db -a web and --as REPORTING_DB_URL; these aliases remain available. Their detach command takes a resource name and optional --as, whereas paas apps detach takes an attachment ID.

Verify from your app

After the app rolls out, check that it received the variable without printing the connection string:

paas run -o acme -p shop -e production -a web -- sh -c 'if [ -n "$DATABASE_URL" ]; then echo "DATABASE_URL is set"; else echo "DATABASE_URL is missing"; exit 1; fi'

Look for the explicit confirmation; the one-off command guide explains remote exit-status limitations. Presence alone does not prove connectivity. Exercise a database-backed app endpoint, or run your framework’s connection check and report only success or a redacted error. See network access if the connection times out.

Detaching

In Attached Resources, click Detach, or find the attachment ID and remove it:

paas apps attachments web -o acme -p shop -e production
paas apps detach web ATTACHMENT_ID -o acme -p shop -e production

Replace ATTACHMENT_ID with the ID from the list. Detaching removes that injected variable and rolls out the app; it does not delete the database. Update code that depends on the connection first. Deleting a database is a separate, destructive operation; review backup and deletion behavior.

Next steps

• Databases — create and manage database resources
• Database Backups — what’s backed up for PostgreSQL and MariaDB
• Environment Variables — app configuration you manage yourself
• Access Control — who can manage databases

Database Backups

The platform backs up PostgreSQL and MariaDB databases automatically. There is nothing to enable or configure — backups are set up automatically as soon as the database is created.

What is backed up

• PostgreSQL — a full backup is taken as soon as the database is created, then every night, and every change in between is archived continuously.
• MariaDB — a full backup every night.

Backups are kept for 14 days. They are stored on the platform’s own storage, separate from the database itself, so they survive problems with the database’s instances.

Deleting a database deletes its backups too, usually within an hour — there is nothing to restore afterwards.

You don’t manage backups yourself: there is no backup command in the CLI and no backup panel in the dashboard. If you want to confirm which databases you have and which engine each one runs, list them:

paas dbs list -o acme -p shop -e production

What is not backed up

Redis and MongoDB databases are not backed up today.

• Treat Redis as disposable — a cache or queue whose contents you can afford to lose.
• For MongoDB, don’t keep data you can’t recreate without making your own copies. If you need an export, take one yourself from your application (for example with a one-off command — see Console & One-off Commands).

Durability and recovery

High availability and backups solve different problems. Replication can replicate an accidental deletion too. Keep independent copies of irreplaceable objects; the platform does not offer an object-restore workflow. See bucket tiers.

Before deleting a database or Environment, export anything you need and verify the copy. Database deletion also deletes its platform backups; Environment deletion removes all its resources. A code rollback never restores database contents.

Restoring from a backup

Restores are not self-serve. To restore a database, contact your platform’s support. There is no restore button in the dashboard and no restore command in the CLI.

When you get in touch, include:

• the Organization, Project, and Environment (for example acme / shop / production),
• the database’s name (for example shop-db),
• the point in time you want to get back to — PostgreSQL can be restored to a point in time within the last 14 days; MariaDB is restored from the nearest nightly backup.

Next steps

• Databases — creating and managing database Resources
• Attaching a Database — wiring a database to an app
• Object Storage Buckets — durable file storage
• Troubleshooting & FAQ

Object Storage Buckets

An Object Storage resource is an S3-compatible bucket for files your app stores and serves — uploads, images, exports, static assets. Like every resource, a bucket lives inside an Environment. You work with it three ways: a Files browser in the dashboard, the paas buckets CLI commands, and any standard S3 client using credentials the CLI hands you.

Creating and managing buckets requires the object-storage management permission on the project. Organization Owners and Admins have it; other members get it through group permissions.

Create a bucket

1. Open the Environment — for example Organization acme → Project shop → Environment staging — and click Add Resource.
2. Choose Object Storage, and give it a name, such as media. The platform’s S3 bucket name combines the environment and this name and must fit in 63 characters, so a very long name is refused with the longest one that fits.
3. Pick a Storage tier:
   • Capacity (the default) — large, low-cost, single-node storage. Durable against disk failure, but not against a whole node being lost, and not backed up. A good fit for assets you can regenerate or re-upload.
   • High availability — replicated storage that survives node loss. Use it when service must survive node loss. Replication does not recover accidental deletion; review durability and recovery and keep independent copies of irreplaceable files. The tier decides which of your plan’s two object-storage pools the bucket’s quota counts toward (see Plans, Limits & Usage). You aren’t locked into this choice — see Moving a bucket to a different tier below.
4. Optionally set a Bucket Quota (GB) — a cap on the total data the bucket can hold. Leave it blank for the 10 GB default.
5. Click Create Resource.

Provisioning takes a moment; until it finishes, the bucket’s pages show “Bucket is still being provisioned.” The underlying S3 bucket name is generated by the platform — you’ll find it on the resource’s Overview tab or via paas buckets info.

The High availability tier may not yet be offered in Production-type Environments on your installation, and either tier can be unavailable; creating one fails with a clear error.

From the CLI, paas buckets create does the same thing:

paas buckets create media -o acme -p shop -e staging --tier ha
paas buckets list -o acme -p shop -e staging
paas buckets delete media -o acme -p shop -e staging --confirm media

--tier capacity|ha picks the starting tier, same as the dashboard’s Storage tier field (default capacity) — see Moving a bucket to a different tier to change it later; --quota-gb is the same as the dashboard’s Bucket Quota (GB) field. --public makes the bucket public immediately instead of leaving it private until you flip visibility separately — for an ha bucket, whose storage isn’t ready the instant it’s created, the CLI retries for a few seconds and tells you to run paas buckets visibility public by hand if it’s still not ready. paas buckets delete asks you to type the name to confirm; pass --confirm <NAME> in scripts.

Moving a bucket to a different tier

The tier you pick at creation isn’t permanent. Move a bucket between Capacity and High availability at any time from its Settings tab — Change storage tier — or from the CLI:

paas buckets migrate media --tier ha -o acme -p shop -e staging

The CLI asks you to type the bucket’s name to confirm; pass --yes in a script, and add --wait to have the CLI poll until the move finishes instead of returning right away.

What happens. The move runs in the background:

1. Objects are copied to the new tier while the bucket keeps serving normally.
2. Near the end, writes to the bucket are paused for a few minutes (reads keep working) while the final copy is checked; uploads during that window are rejected, so retry them afterwards.
3. The bucket switches over to the new tier, and any app attached to it restarts automatically to pick up the new connection details.
4. A last check confirms the move.

The bucket’s name and public URL never change. The Overview and Settings tabs show the move’s progress (copying, finishing up, switching over, verifying) while it runs; paas buckets list/info show it as <tier> -> <target tier> (<phase>) in the tier column. Capacity and High availability draw from separate pools in your plan’s object-storage quota (see Plans, Limits & Usage) — once a move finishes, the bucket’s quota counts against its new tier’s pool instead of its old one. A move is refused up front (the same “limit exceeded” error as creating a bucket) if the bucket’s quota doesn’t fit in the target tier’s pool. A bucket can’t be deleted, and a second move can’t be started, while one is already in progress.

If a move fails, the bucket keeps serving from its current tier — nothing is lost. In the dashboard, an alert on the bucket’s Overview and Settings tabs offers a way to resolve it:

• If the move hadn’t switched over yet: Try again retries the same move, or Keep on <current tier> gives up and cleans up the partial copy.
• If the move had already switched over and only the final check failed: Retry final check re-runs just that check — the bucket is already on the new tier.

From the CLI, re-run paas buckets migrate with the same --tier to retry, or with the bucket’s current tier to give up (only possible before it has switched over).

Browse files in the dashboard

The bucket’s Files tab is an object browser:

• Folders come from key prefixes — click a folder to descend, and use the breadcrumb trail to jump back up. Click Load more if a listing is truncated.
• Upload puts a file (one at a time) into the current folder. Uploads go straight to storage over a short-lived signed link.
• Download opens the object in a new tab, also via a short-lived link, so it works whether the bucket is public or private.
• Copy URL appears on each file when the bucket is public — it copies the object’s permanent public URL.
• Delete permanently removes the object after a confirmation.

Anyone who can view the project can browse and download; uploading and deleting require the object-storage management permission.

The CLI lists objects too, optionally under a prefix:

$ paas -o acme -p shop -e staging buckets ls -a media
KEY          SIZE   MODIFIED
avatars/     -      -
banner.png   48213  2026-08-30T14:02:11Z
$ paas buckets ls avatars/ -a media

For bucket commands, -a names the Object Storage resource. If a listing has more results than one page, the CLI prints a note (pagination is not yet supported there — use the dashboard’s Load more).

paas buckets put and get move files the same way the dashboard’s Upload and Download buttons do — straight between your machine and storage, over a short-lived signed link:

$ paas buckets put ./banner.png -a media
Uploaded ./banner.png to banner.png (image/png)
$ paas buckets get banner.png ./local-banner.png -a media
Downloaded banner.png to ./local-banner.png
$ paas buckets rm avatars/old.png -a media
Deleted avatars/old.png

put guesses the object’s content type from the file’s extension (text/html, image/png, and so on, falling back to application/octet-stream); pass --content-type to set it explicitly, which matters most for a public bucket serving a website — the wrong type can make a browser download an .html file instead of rendering it. get’s destination defaults to the key’s base name (banner.png for a key of avatars/banner.png); pass - to write the object’s bytes straight to stdout instead of a file. A download that fails partway never touches an existing file at the destination.

To upload into a folder, give put a key: paas buckets put ./alice.png avatars/alice.png -a media stores it under that key; without one, the key is the file’s name.

Public URL and visibility

Every bucket gets a generated public hostname of its own. Buckets start private: nothing is readable without credentials. Flip visibility on the resource’s Overview tab — Make public asks you to confirm, because anyone with the URL can then read every object in the bucket. Making a bucket public never allows writes, and it does not let anyone anonymously list the bucket’s contents — objects are fetched by their exact key.

While public, an object is served at the bucket URL plus its key: <bucket-url>/avatars/alice.png. The Files tab’s Copy URL button builds these links for you.

From the CLI:

$ paas -o acme -p shop -e staging buckets url -a media
https://<generated-name>.<storage-domain>
$ paas buckets visibility public -a media
public: true
Warning: anyone with the URL can read every object in this bucket.
$ paas buckets visibility private -a media

paas buckets url exits with an error if no public hostname has been assigned yet. Visibility changes are recorded in the organization’s audit log.

If the bucket (or its Organization, Project or Environment) goes over its monthly transfer allocation, public access is switched off until usage is back under budget: Visibility reads Private — blocked, and the CLI shows private (blocked; public once unblocked) — see Troubleshooting.

S3 credentials via the CLI

To use your own S3 tooling — sync scripts, backups, an S3 GUI — paas buckets creds prints the bucket’s credentials as shell export statements (it requires the object-storage management permission, and each read is audit-logged):

$ paas buckets creds -a media
export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export S3_ENDPOINT='https://...'
export S3_BUCKET='...'
export S3_REGION='us-east-1'
# eval "$(paas buckets creds -a media)" then use any S3 client with --endpoint-url "$S3_ENDPOINT"

Load them into your shell and point any S3 client at the endpoint:

eval "$(paas buckets creds -a media)"
aws s3 ls "s3://$S3_BUCKET" --endpoint-url "$S3_ENDPOINT"

The only --format supported is env (the default). Add --json to any paas buckets command for machine-readable output, and use paas buckets info -a media for a one-screen summary (availability, bucket name, endpoint, region, tier, visibility, URL).

Attaching a bucket to an app

Attach a bucket to a Web Application or Background Worker in the same Environment from the app’s Config tab: the attach card lists both Databases and buckets (each type-labeled), and attaching a bucket requires the object-storage management permission. See Attaching a Database for the shared card — the same flow works for buckets, except the second field is a credential prefix rather than a variable name.

A bucket attached with no prefix — the app’s primary bucket — injects five SDK-standard environment variables, which most S3 client libraries pick up directly. Capacity buckets work with default client settings. HA buckets need path-style addressing (see Configuring your S3 client):

Configuring your S3 client

Path-style addressing for HA buckets. Capacity buckets accept both forms, so SDK defaults work. HA buckets need the bucket in the path (https://<endpoint>/<bucket>/<key>), not in the host name. Many AWS SDKs default to the host-name form when the endpoint is a name, which fails with “host not found” for HA buckets. Turn path-style on:

Checksum settings. An app with a capacity bucket attached also gets AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED and AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED. Capacity storage now accepts every SDK’s default checksums, so these are only a compatibility default. A value you set yourself (paas config set) takes precedence.

To attach a second bucket to the same app, give it a prefix (say ASSETS): the five variables are then injected as ASSETS_ENDPOINT, ASSETS_BUCKET, ASSETS_REGION, ASSETS_ACCESS_KEY_ID, and ASSETS_SECRET_ACCESS_KEY, so they can’t collide with the primary bucket’s. An app has at most one prefix-less bucket, and each bucket attaches once per app.

Every attachment also injects a status link — STATUS_URL for the primary bucket, <PREFIX>_STATUS_URL otherwise — a public, unauthenticated URL that reports the bucket’s status and stays fixed for the bucket’s lifetime. It returns {"state": "active" | "read_only", "tier": …} — read_only while writes are paused during a tier move, so your app can check it rather than fail uploads.

You can confirm the variables reached the app with a one-off command:

paas -o acme -p shop -e production -a web run -- printenv S3_ENDPOINT

Use CLI 0.9.0 or later to select the app explicitly. Omit --prefix for the primary bucket; use a distinct bucket and prefix for a second attachment:

paas apps attach web media -o acme -p shop -e production
paas apps attach web assets --prefix ASSETS -o acme -p shop -e production
paas apps attachments web -o acme -p shop -e production
paas apps detach web ATTACHMENT_ID -o acme -p shop -e production

Replace ATTACHMENT_ID with the ID from the attachment list. Detaching leaves the bucket intact. See app attachment commands and the older CLI aliases.

Next steps

• Attaching a Database — the same attachment model, for databases
• Managing Secrets — keep credentials out of your code
• Plans, Limits & Usage — how quotas count against your plan
• Access Control — who can manage object storage

Managing Secrets

Secrets hold sensitive values — API keys, passwords, tokens — that the platform stores encrypted and injects into your apps by reference. Their values are write-only: after you save a secret, nobody can read the value back through the dashboard or the API. You can only replace it.

Every secret has three parts:

• Name — uppercase letters, numbers, and underscores, starting with a letter and not ending with an underscore (e.g. STRIPE_API_KEY). The dashboard normalizes what you type. Names are at most 253 characters. Names ending in _S3, _REDIS_CONN, _MONGODB_PASSWORD or _MARIADB_PASSWORD are reserved for the credentials the platform creates for your buckets and databases. The name is what apps reference; it need not match the app variable key.
• Value — entered once, then hidden.
• Description — optional, shown in the secrets list so teammates know what the value is for.

Creating, editing, and deleting Project and Environment secrets requires the manage-secrets capability on the project (see Access Control). Organization secrets can only be managed by the Organization’s Owner and Admins. Secrets are managed in the dashboard; the CLI links apps to them but does not create them.

Choosing a scope

Secrets live at one of three levels:

• Organization — shared across the whole Organization.
• Project — shared by all of a Project’s Environments.
• Environment — specific to one Environment. This is the most common scope: production credentials that staging must never see.

Pick the narrowest scope that works. A production database password belongs on the production Environment, not on the Organization.

Creating a secret

Each scope has its own secrets page in the dashboard:

• Environment — open the Environment’s Secrets page and click Add Secret.
• Project — open the Project’s settings and go to the Secrets tab (Project Secrets).
• Organization — open the Organization’s settings and find Organization Secrets.

In each case, enter a name, the value, and an optional description. The value field is masked as you type; each form has a Show toggle if you need to double-check it before saving.

Editing a secret

Environment secrets have an Edit action in the list; because values are write-only, its value field starts empty — enter a complete new value (there is no way to view or append to the old one), or leave it blank to keep the current value and change only the description, and save. Project and Organization secrets have no Edit action in the dashboard yet. To change one, send the new value to the API with PUT /api/v1/organizations/<org>/projects/<project>/secrets/<name> (Project) or PUT /api/v1/organizations/<org>/secrets/<name> (Organization) and a body of {"value": "<new value>"}; see API Access & Automation. The CLI can’t change secrets. In every scope, the name is fixed: to rename a secret, create a new one, move the links to it, then delete the old one.

This is also how you rotate a credential: edit the secret with the new value. The new value reaches your Environments within seconds, and every app that links to the secret restarts on its own to pick it up — a rolling restart, so a multi-instance app keeps serving traffic (a singleton app is stopped and started again, so it is briefly unavailable).

Deleting a secret

Click Delete on the secret and confirm. Deletion is permanent and cannot be undone. An Environment or Project secret that an app still links to can’t be deleted — remove those links first. An Organization secret can be deleted while apps link to it, and those links then lose their source, so update or remove them first.

Binding a secret to an app

A secret does nothing on its own — an app picks it up through an environment variable that references the secret instead of holding a literal value.

In the dashboard, open the app’s Environment Variables section, add a variable, and choose Link to secret, picking the secret from the list. The list shows the Environment’s secrets, then the Project’s, then the Organization’s. Organization secrets appear only for the Organization’s Owner and Admins. A name that a nearer scope also has appears once, in the nearer scope.

With the CLI, use paas config set --secret-ref with the secret’s name followed by the variable key to create on the app:

paas config set --secret-ref STRIPE_API_KEY STRIPE_API_KEY \
  -o acme -p shop -e production -a web

The variable key doesn’t have to match the secret’s name — you can point PAYMENT_KEY at STRIPE_API_KEY. Both start with an uppercase letter. The secret must already exist in the Environment, the Project or the Organization. Only the Organization’s Owner and Admins can link an Organization secret. See secret resolution. Your app reads the result as an ordinary environment variable.

See Environment Variables for the full guide to per-app configuration.

When changes reach your app

Secret values are read when an instance starts. Use this lifecycle table to decide whether a manual restart is necessary: