Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 35 ยท App Platform and Functions

App Platform Workers, Jobs, Cron Schedules and Environments

Run background work on App Platform: workers, pre-deploy migrations, post-deploy jobs, scheduled cron jobs, logs, alerts, rollbacks, and staging versus production apps.

A web service answers requests, but real applications also need work that happens outside a request: sending emails, resizing images, running database migrations, generating nightly reports. App Platform handles this with two component types, workers and jobs. This lesson shows when to use each, how scheduling works, and how to run staging and production versions of the same app safely.

Workers: always-on background processes

A worker is just like a service, but without a public HTTP port. It starts, stays running and pulls work from somewhere: a queue in a Valkey or PostgreSQL database, a message broker, or a polling loop. Typical examples: a Celery or RQ worker (Python), Sidekiq (Ruby), BullMQ (Node.js), Laravel queue workers (PHP).

YAML
workers:
  - name: mailer
    github:
      repo: acme/shop
      branch: main
    source_dir: /worker
    environment_slug: node-js
    run_command: node dist/mailer.js
    instance_count: 1
    instance_size_slug: apps-s-1vcpu-0.5gb
    envs:
      - key: QUEUE_URL
        scope: RUN_TIME
        type: SECRET
        value: "<secret>"

Because workers are processes that must keep running, they are billed like services. Scale them by instance count: two workers consume the queue twice as fast as one, provided your jobs can run in parallel safely (use idempotent handlers and unique job IDs).

Design rules for workers:

  • Handle SIGTERM. On deploys the platform sends a termination signal; finish or requeue the current task and exit within the grace period.
  • Be idempotent. A job may be delivered twice after a crash; processing it twice must not charge a customer twice.
  • Retry with backoff and move permanently failing jobs to a dead-letter list instead of looping forever.

Jobs: run to completion

A job runs a command and exits. The kind decides when:

Kind When it runs Example
PRE_DEPLOY Before new code receives traffic; a failure cancels the deploy Database migrations
POST_DEPLOY After a successful deploy Warm caches, send a "deployed" notification
FAILED_DEPLOY After a deploy fails Alert, collect diagnostics
SCHEDULED On a cron schedule Nightly report, cleanup
YAML
jobs:
  - name: migrate
    kind: PRE_DEPLOY
    github:
      repo: acme/shop
      branch: main
    run_command: node dist/migrate.js
    instance_size_slug: apps-s-1vcpu-0.5gb
  - name: nightly-report
    kind: SCHEDULED
    run_command: node dist/report.js
    schedule:
      cron: "0 3 * * *"
      time_zone: Europe/Berlin

The pre-deploy job is the safest place for migrations: if the migration fails, the old version keeps serving. Make migrations backward compatible (add columns before using them; remove columns in a later release), because old and new code overlap briefly.

You can also trigger a job by hand from the panel or with doctl apps create-deployment when you need a one-off task such as a data repair.

Cron expressions

A cron schedule has five fields: minute hour day-of-month month day-of-week.

Expression Meaning
0 3 * * * Every day at 03:00
*/15 * * * * Every 15 minutes
30 8 * * 1-5 08:30 on weekdays
0 0 1 * * Midnight on the first of each month

Set time_zone explicitly; cron defaults to UTC, and daylight-saving changes can cause surprises for local times. A scheduled job must finish before its next run, or you will have overlapping executions, so add a lock or a guard to jobs that take a long time.

Logs, alerts and rollbacks

  • Logs: build, deploy and run logs per component in the panel, or doctl apps logs <app-id> mailer --type run --follow. Forward them to an external service using log destinations when you need retention beyond the platform's window.
  • Alerts: configure alerts for deployment failures, CPU or memory above a threshold, restarts, and domain problems; send them to email or Slack.
  • Rollback: the panel lists past deployments; choose one and roll back. This redeploys the older image, which does not undo database migrations, so keep them reversible.

One app, several environments

Do not test in production. Keep an app for each environment, created from the same spec with small differences:

Terminal
doctl apps create --spec app.staging.yaml
doctl apps create --spec app.production.yaml

Differences usually include the branch (staging versus main), instance size and count, database (a small separate cluster for staging), and the environment variables (API keys for sandbox services in staging). In the repository you can use a template and a script to generate both files so they never drift apart. Staging apps can be small, and you can destroy them when not needed to save money.

flowchart LR
  F["feature branch"] --> S["staging app<br/>branch: staging"]
  S -->|"tests pass"| P["production app<br/>branch: main"]
  P --> J["pre-deploy job:<br/>migrate"]

Promote through environments instead of editing production directly.

Stand-in: cron matcher and environment diff

Real cron parsing has many features. This stand-in supports *, single numbers, lists, ranges and */n steps, enough to read the table above and understand schedules. It uses datetime only.

Python Stand-in: when does this cron expression fire?

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: diff staging and production settings

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where is the safest place to run database migrations on App Platform?

    A failed pre-deploy job cancels the deployment, so the old version keeps serving traffic.
  2. 2. What is the difference between a worker and a job?

    A worker stays up and processes work; a job starts, finishes and exits.
  3. 3. What does the cron expression '*/15 * * * *' mean?

    */15 in the minute field means every 15th minute.
  4. 4. Why should worker tasks be idempotent?

    At-least-once delivery means duplicates happen; handlers must be safe to repeat.

Summary

  • Workers are always-on background processes; jobs run to completion before deploy, after deploy, after failure or on a cron schedule.
  • Run migrations in a pre-deploy job, keep them backward compatible, and handle SIGTERM and retries in workers.
  • Use five-field cron expressions with an explicit time zone and guard against overlapping runs.
  • Keep separate staging and production apps built from the same spec, and use logs, alerts and rollbacks for operations.

Next: Functions: Serverless on DigitalOcean