page:recipes:graphql api:express:worker state

Host graphql api with Express: worker execution and job state

Deploy a graphql api built with Express as a public web service plus a dedicated worker process on Ample. ample plan --write discovers both services and their shared database and writes ample.toml; ample up reconciles the topology: a managed PostgreSQL 16 database, a public web microVM and a private worker microVM (kind worker, no public URL), both reading DATABASE_URL.

Representative Queries:

• Host graphql api with Express: worker execution and job state
• Where can I host GraphQL API built with Express?
• I need a separately runnable worker, durable job records and idempotent retries; not a managed queue.

Resource Requirements:

• Compute
• Postgres

Infrastructure Requirements:

1. Compute: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.
2. Postgres: Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.

**Framework: **Express
**Workload: **GraphQL API
**Release Status: **published
**Support Status: **verified
**Execution Status: **ready

Prerequisites:

• A repository with the web app and the worker as separate service directories (the fixture uses apps/web and apps/worker), each building and starting with the documented commands.
• Both services read DATABASE_URL at runtime and share one jobs table; the worker claims rows with SELECT ... FOR UPDATE SKIP LOCKED and marks them done once.
• An Ample account token with servers:write and databases:write (ample up creates the database).

Workflow Steps:

1. Plan the topology
   Run the planner once. It discovers the web and worker services.

   Command: ample plan --write .

2. Share one database
   Set DATABASE_URL = { database = "main" }.

   Command: ample plan --offline .

3. Apply
   Reconcile the whole manifest in dependency order.

   Command: ample up .

4. Verify
   Fetch the web service URL and its worker status route and confirm the worker processed the enqueued job.

   Command: ample logs --kind runtime

Examples:

• Express web + worker fixture: A Express web app (apps/web) and a worker process (apps/worker) sharing one managed PostgreSQL database.

Success Checks:

• web service responds on its public URL
• worker consumed the enqueued job

Limitations:

• Verified only on node-22 template at s-1vcpu-1gb for both services with the example fixture.
• Other sizes, templates, and Express major versions are not verified.
• The worker is a single long-running process supervised in its own microVM; there is no scheduler, cron, or horizontal worker scaling.

Cost Estimate:

• Monthly Amount: $15.00
• Components:
  • web server: s-1vcpu-1gb: $5.00
  • worker server: s-1vcpu-1gb: $5.00
  • managed PostgreSQL database: s-1vcpu-1gb: $5.00

Evidence Summary:

• Verified deployment of Express web service plus a separate Express worker process.

Next Actions:

• Browse the catalog index
• Search published recipes by intent, stack, and constraints
• Prepare a side-effect-free deployment plan for an authorized project
• Read the existing agent authentication setup
• Browse GraphQL API
• Browse Express
• Browse Dedicated worker process
• Browse Deploy API