GREEN PACKAGE SKILL · DIGITALOCEAN · TEMPORAL

Temporal Package Skill

A production-oriented single-machine Temporal deployment with PostgreSQL, all four server roles, a reference TypeScript worker and API, Caddy HTTPS, backups, and an external durability test.

Production server, not a development shortcut. The stack invokes Temporal Server’s production roles and keeps every Temporal and PostgreSQL port private on the Docker network.

Install and preview

npx skills add getcolors/temporal
cp .agents/skills/package-temporal-green/green ./green
chmod +x green
./green build
./green create --dry-run

Build and dry-run are credential-free. They validate desired state, render the deployment, and walk the complete graph without touching DigitalOcean or Cloudflare. Real creation, reboot acceptance, and deletion require explicit authorization.

Architecture

Infrastructure

OpenTofu discovers the configured region’s default VPC, provisions one guarded Ubuntu Droplet and firewall, and creates the Cloudflare apex record. Desired state contains no VPC identifier.

Temporal

Docker Compose runs PostgreSQL, schema setup, all four Temporal Server roles, private admin tools, the reference application, and Caddy. It never invokes Temporal’s development server.

Network

Cloud and host firewalls admit restricted SSH plus HTTP and HTTPS. PostgreSQL, Temporal frontend and internode traffic, admin tools, and the worker stay inside the Docker network.

Persistence

PostgreSQL data lives under /data/postgresql. Containers restart after service, Docker, or Droplet restarts; logical dumps and DigitalOcean backups provide recovery options.

Temporal Server 1.31.2 and TypeScript SDK 1.22.0 are pinned exactly from the stable releases discovered on 2026-08-15.

Reference workflow

The TypeScript API starts workflows under caller-supplied IDs, reports status, and returns deterministic results. Each workflow uses a durable timer, deliberately fails its activity twice, and eventually returns TEMPORAL:<workflow-id>:OK with the successful attempt number. Duplicate IDs are rejected rather than silently creating parallel work.

The acceptance command exercises that behavior entirely through the public HTTPS boundary:

./green create
./green acceptance
./green acceptance --reboot

The reboot variant starts a workflow, reboots the whole Droplet during its durable delay, waits for recovery, and verifies the original execution and retry result. It is the complete persistence test and must run only against an authorized deployment.

Desired state and safety

colors.yml is flat, kebab-case, non-secret desired state. It selects compute, firewall sources, DNS, backend, Temporal and SDK versions, application host, workflow timing, backup policy, and acceptance behavior. Consult the configuration reference before changing it.

Credentials belong only in matching COLORS_PAR_* environment variables in an ignored .envrc.private.
Never set COLORS_PAR_PROFILE; the profile determines remote-state identity.
Never edit or commit generated .colors/.
Keep compute-prevent-destroy: true and treat deletion as a separate authorization.

Operations

ssh SERVER 'cd /opt/temporal && docker compose ps'
ssh SERVER 'cd /opt/temporal && docker compose logs --since 1h temporal'
ssh SERVER 'cd /opt/temporal && docker compose logs --since 1h application'

Inspect the private stack over SSH rather than publishing admin ports. Re-running create converges the existing deployment and preserves PostgreSQL state.

Backups, restoration, and upgrades

Daily logical dumps are retained for seven days under /data/temporal/backups, and the desired Droplet enables DigitalOcean backups. Local dumps are useful for operator recovery but disappear with a lost disk; provider backups reduce that risk without eliminating it.

Restore onto a fresh compatible stack with an operator-controlled pg_restore or psql import. Verify schema compatibility, workflow status, and new execution before directing traffic to the replacement. Never import over a running live database.

For upgrades, review Temporal Server and schema compatibility guidance, change exact versions, inspect generated and golden diffs, run build and dry-run, take a backup, then converge and run acceptance.

One machine is one failure domain. There is no service redundancy, database replica, cross-region failover, or zero-downtime host maintenance. Workloads requiring high availability need a multi-node Temporal topology and an external highly available database.

Development and source

bb test
bb golden
./scripts/launcher.sh

Source on GitHub. Inspect every golden diff; launcher pins are managed only after a clean pushed package commit.