Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 35 ยท App Platform and Functions

The App Platform App Spec: Configure Your App as YAML

Write a DigitalOcean App Platform app spec: services, static sites, source, build and run commands, ports, routes, health checks, environment variables, secrets, and doctl deploy commands.

Every App Platform app is described by an app spec, a YAML document that lists its components and how to build and run them. The control panel edits this document for you, but writing it yourself gives you repeatable, reviewable deployments: you store app.yaml in Git, change it through pull requests and apply it with doctl. This is infrastructure as code for apps.

A complete example

YAML
name: shop
region: fra
services:
  - name: api
    github:
      repo: acme/shop
      branch: main
      deploy_on_push: true
    source_dir: /api
    environment_slug: node-js
    build_command: npm ci && npm run build
    run_command: npm start
    http_port: 8080
    instance_count: 2
    instance_size_slug: apps-s-1vcpu-1gb
    health_check:
      http_path: /healthz
    routes:
      - path: /api
    envs:
      - key: NODE_ENV
        value: production
        scope: RUN_TIME
      - key: DATABASE_URL
        scope: RUN_TIME
        type: SECRET
        value: "<set in the console or encrypted by doctl>"
static_sites:
  - name: web
    github:
      repo: acme/shop
      branch: main
    source_dir: /web
    environment_slug: html
    build_command: npm ci && npm run build
    output_dir: dist
    routes:
      - path: /

Walking through the important fields:

  • name, region: the app name and its region slug (App Platform uses short ones such as fra, nyc, ams, sfo).
  • services, static_sites, workers, jobs, functions, databases: the component lists. Each component has a unique name.
  • github (or gitlab, bitbucket, git, image): where the source lives. deploy_on_push redeploys on every push to that branch.
  • source_dir: the sub-directory for monorepos.
  • environment_slug: the build environment (for example node-js, python, php, go, html). If the repo has a Dockerfile, use dockerfile_path instead.
  • build_command and run_command: override the defaults.
  • http_port: the port your process listens on. The process must bind to 0.0.0.0 (not localhost) and the port in the spec, or health checks fail. Many frameworks read a PORT environment variable which App Platform sets.
  • instance_count and instance_size_slug: how many copies and how big.
  • health_check: an HTTP path the platform polls; a failing check blocks the rollout and restarts unhealthy instances.
  • routes: which URL paths go to which component. The platform strips or keeps the prefix depending on the settings, so check your framework's routing (preserve_path_prefix).
  • envs: environment variables, discussed below.

Environment variables and secrets

Each variable has a scope:

Scope Available Typical use
BUILD_TIME While building Public build flags, registry tokens for npm install
RUN_TIME While running Database URLs, API keys
RUN_AND_BUILD_TIME Both Values the build and the app share

A variable with type: SECRET is encrypted; after saving, the value is never displayed again. Do not put real secrets into app.yaml in Git. Keep placeholders in the file and set the values in the panel, or let your CI inject them when it applies the spec.

Bindable variables let components refer to each other without hard-coding values. A service can use ${db.DATABASE_URL} for an attached database component named db, or ${APP_URL} for its own public URL, and the platform fills them in.

Applying a spec

Terminal
doctl apps create --spec app.yaml
doctl apps list --format ID,Spec.Name,DefaultIngress
doctl apps update <app-id> --spec app.yaml
doctl apps create-deployment <app-id> --force-rebuild
doctl apps logs <app-id> api --type run --follow
doctl apps spec get <app-id> > app.yaml        # export what the console built

doctl apps spec validate app.yaml checks a spec before you apply it. A good habit is to build the app once in the panel, export the spec with spec get, commit it, and manage it from then on as code.

flowchart LR
  PR["Pull request edits app.yaml"] --> CI["CI: doctl apps spec validate"]
  CI --> M["Merge to main"]
  M --> U["doctl apps update --spec"]
  U --> D["Platform builds and deploys"]

The spec lives in Git, so every change is reviewed and reversible.

Common mistakes

  • Listening on 127.0.0.1 instead of 0.0.0.0.
  • Using a different port than http_port.
  • Forgetting that the disk is ephemeral.
  • Overlapping routes, such as / on a service and / on a static site.
  • Putting secrets into the repository.
  • Missing health check path returning a non-200 status code.

Stand-in: validate a spec in Python

The doctl apps spec validate command runs on DigitalOcean's side. This program is a stand-in that checks a few of the same rules locally. It uses a tiny parser instead of a YAML library, so the spec is written as a Python dictionary, which has the same structure.

Python Stand-in: validate an app spec structure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: resolve which component serves a URL path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last path, /apiary, does not match /api, because the prefix must end at a path boundary.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which address must your app listen on inside App Platform?

    The platform's router connects from outside the container, so the process must bind all interfaces on the configured port.
  2. 2. What does environment variable scope RUN_TIME mean?

    BUILD_TIME is for the build step, RUN_TIME for running instances, RUN_AND_BUILD_TIME for both.
  3. 3. Where should a real database password live?

    Secrets are encrypted by the platform; the spec in Git keeps only placeholders.
  4. 4. How do you export a spec that you built in the panel?

    Export it, commit it and manage the app as code from then on.

Summary

  • The app spec is a YAML description of components: source, build, run command, port, size, routes, health checks and environment variables.
  • Bind to 0.0.0.0:$PORT, set http_port, add a health check, and keep secrets out of Git.
  • Apply specs with doctl apps create and update, validate before applying, and export with spec get.
  • Path routing uses the longest matching prefix, and component names must be unique.

Next: Workers, Jobs and Environment Management