Digitalocean

DigitalOcean — Droplet vs App Platform, doctl, Managed DBs, Spaces

You own one decision: where on DO does this run, and how do I ship it. Host-agnostic CI/CD, release gating and rollback strategy are ../deployment/SKILL.md; authoring the Dockerfile is docker; DNS records and the registrar are domains-dns; a bare Hetzner box and its economics are hetzner. Pick the compute model first, then wire data and storage, then the ops that bite in production.

workload → [Droplet | App Platform | Functions] → Managed DB (VPC private host) → Spaces (S3 + CDN)
              raw VPS    managed PaaS   event fn        Postgres/MySQL/Valkey         object store

The core decision: Droplet vs App Platform vs Functions

Settle this before writing a single command. Most web apps want App Platform; reach for a Droplet only when you need the box itself.

Rules of thumb:

• Stateless web service or API from a Git repo → App Platform. It builds, deploys, gives you TLS and a URL, and re-deploys on push. No box to patch. Static frontend → App Platform static site (free, up to 3); don't run a Droplet to serve HTML.
• You need root, a long-lived stateful daemon, custom ports, or a cron host → Droplet.
• A managed Postgres/MySQL/Valkey → always the Managed Database product, never a DB you hand-install on a Droplet, unless you have a hard reason.

doctl setup

doctl is the official DO CLI; it drives everything below.

# macOS
brew install doctl
# Linux: download the release tarball from github.com/digitalocean/doctl/releases, then:
#   tar xf doctl-*.tar.gz && sudo mv doctl /usr/local/bin

# Authenticate with a token from cloud.digitalocean.com/account/api/tokens
doctl auth init                       # pastes a token, validates, stores a context
doctl auth init --context prod        # a named context per account/env
doctl auth switch --context prod      # switch the active context
doctl account get                     # verify the token works

Never commit the token. It is a full-account credential. Keep it in your shell keychain, a secret manager, or CI secret — never in the repo, never in an app spec. Why: a leaked dop_v1_… token lets anyone create/destroy your whole account.

App Platform via app spec

App Platform deploys from an app spec (YAML or JSON). Treat the spec as the source of truth, version it, and apply it with doctl.

# .do/app.yaml — minimal web service + managed Postgres
name: my-api
region: nyc
services:
  - name: web
    github:
      repo: me/my-api
      branch: main
      deploy_on_push: true
    instance_size_slug: apps-s-1vcpu-1gb   # ~$5/mo basic; sizes go up to dedicated
    instance_count: 1
    http_port: 8080
    envs:
      - key: NODE_ENV
        value: production
        scope: RUN_TIME              # RUN_TIME | BUILD_TIME | RUN_AND_BUILD_TIME
      - key: DATABASE_URL
        value: ${db.DATABASE_URL}    # injected from the managed DB below
        scope: RUN_TIME
      - key: API_SIGNING_KEY
        value: ${API_SIGNING_KEY}
        type: SECRET                 # encrypted at rest; never plaintext
        scope: RUN_TIME
databases:
  - name: db
    engine: PG
    production: true

Lifecycle — validate, then create or update:

doctl apps spec validate .do/app.yaml          # structural lint, no deploy
doctl apps create --spec .do/app.yaml          # first deploy; prints the app id
doctl apps update <app-id> --spec .do/app.yaml # apply changes (and to roll back: re-apply the prior spec)
doctl apps list                                # find the id

Env scoping that matters:

• type: SECRET encrypts the value at rest and hides it in the dashboard. Use it for every key, token, password. Plain value: is readable.
• scope: BUILD_TIME for things only the build needs; RUN_TIME for runtime; don't leak build-only secrets into the running container.
• ${db.DATABASE_URL} (and ${db.HOSTNAME}, ${db.PORT}, etc.) are auto-injected when the service references a databases: entry — you never paste the connection string.

Operate:

doctl apps logs <app-id> --type run --follow     # run | build | deploy
doctl apps logs <app-id> <component> --type run  # one component

Rollback = re-apply the previous spec (git-revert .do/app.yaml and doctl apps update), or redeploy a prior deployment from the dashboard. There is no magic rollback verb — your git history of the spec is the rollback mechanism.

For multi-component apps (web + worker + static_site + job + db, health checks, ingress routes, autoscaling, instance-size table, alerts) see references/app-spec.md.

Droplets

A Droplet is a Linux VPS. Bootstrap it declaratively, lock it down with a cloud firewall.

doctl compute droplet create web-1 \
  --region nyc3 --size s-1vcpu-1gb --image ubuntu-24-04-x64 \
  --ssh-keys <fingerprint> \
  --vpc-uuid <vpc-uuid> \
  --user-data-file cloud-init.yaml \
  --wait

• Cloud firewall, not just ufw. A cloud firewall filters at DO's edge before traffic reaches the box, and applies to a tag/group of Droplets. Use it as the real perimeter; host ufw is defense-in-depth, not the only line. Why: a misconfigured ufw after a reboot still leaves the edge firewall protecting you.
• Reserved IP is free while assigned to a Droplet (you pay only when it's unassigned). Assign one so you can re-point it to a replacement Droplet without DNS changes — that's your failover handle.
• Snapshots/backups are your restore path; enable automated backups or snapshot before risky changes.
• Per-second billing since 2026-01-01 (min 60s or $0.01): short-lived Droplets are cheap to spin up and destroy, but a powered-off Droplet still bills for storage — destroy, don't just power off, to stop charges.

Cloud-init recipes, firewall inbound/outbound rule sets, snapshot cadence + restore, reserved-IP failover, and the VPC + private-DB layout live in references/droplet-ops.md.