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.

textCopy code
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.

bashCopy code
# 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.

yamlCopy code
# .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:

bashCopy code
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:

bashCopy code
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.

bashCopy code
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.

Managed Databases

Use the Managed Database product for Postgres/MySQL/Valkey — DO handles patching, failover, and backups.

• Provision sizing: managed Postgres starts ~$15/mo single node; HA (primary+standby) from ~$30/mo; read replicas available for read scaling.
• Connect over the VPC private host, not the public one. Same-region Droplets and Managed DBs talk over the VPC with no bandwidth charge and sub-ms latency, and the private host keeps the DB off the public internet. Add the app's Droplet/App as a trusted source so only it can connect.
• Connection pooling (PgBouncer) is built in. Use a pool when many short-lived clients (serverless, lots of App Platform instances) would otherwise exhaust connections — a cluster supports up to ~21 pools / up to ~1,000 connections depending on size, and the pool listens on a separate pool port from the raw DB port. Point your app at the pool connection string, not the raw one.
• For schema design, indexing, query tuning, migrations → that's ../postgresdb/SKILL.md, not here. This skill only provisions and wires the cluster.

Spaces (S3-compatible object storage + CDN)

Spaces is S3-API-compatible object storage with a built-in CDN.

• $5/mo includes 250 GiB storage + 1 TiB outbound transfer; inbound is free; the CDN is included at no extra cost across 200+ edge locations.
• Spaces keys are NOT your API token. Generate a separate Spaces access key + secret; the doctl/API token does not work for S3 operations.
• Use any S3 SDK or aws-cli/s3cmd against the regional endpoint:

pythonCopy code
# boto3 against DO Spaces (nyc3 region/endpoint)
import boto3
s3 = boto3.client(
    "s3",
    endpoint_url="https://nyc3.digitaloceanspaces.com",
    region_name="nyc3",
    aws_access_key_id="<SPACES_KEY>",       # Spaces key, not the DO API token
    aws_secret_access_key="<SPACES_SECRET>",
)
s3.upload_file("photo.jpg", "my-bucket", "photo.jpg", ExtraArgs={"ACL": "public-read"})

Serve public assets through the bucket's CDN edge URL; set CORS on the bucket if a browser fetches it cross-origin, and a lifecycle rule to expire/transition old objects.

Basic ops + cost gotchas

• Set alerts on the app/DB (deploy failures, CPU, restart count) so you hear about trouble before users do. App-level dashboards/alerting strategy is ../monitoring.
• Scale by editing instance_count/instance_size_slug in the spec and re-applying; capacity strategy that's host-agnostic is ../scaling.
• App Platform data transfer overage is $0.02/GiB, billed separately from Droplet transfer — a chatty media app can run up a bill; front heavy static assets with Spaces+CDN.
• An unassigned reserved IP is billed. Release reserved IPs you're not using.

Anti-patterns