How to horizontally scale a Wasp backend (Express + PgBoss)
Hi! I’d like to get your advice on the best way to horizontally scale the backend of a Wasp application — including both the Express server and PgBoss jobs.
For example, one option could be to use a Cloudflare load balancer with multiple instances running on a VPS provider like Hetzner, and then modify wasp.main so that only one instance initializes the PgBoss jobs (at least until there’s support for running them in an isolated instance).
What do you think about this approach? Do you see any potential issues with it? And are there any recommended approaches or official guidelines from the Wasp team regarding this?
Thanks!
1 Reply
Hi @Ramon. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
Wasp doesn’t yet have official, detailed “best practices” docs for production scaling or job workers, so there are no formal guidelines beyond what’s implied by the current jobs implementation and a few roadmap issues. [Production advice; Jobs docs]
Here’s what is known and what that means for your setup:
1. Scaling the Express backend
Wasp compiles to a standard Node/Express server, so horizontally scaling the HTTP API is conceptually the same as scaling any Node/Express app behind a load balancer. The Wasp team has explicitly reassured users that for scaling you “can use the same tools you could use directly from the JS ecosystem,” even if Wasp doesn’t yet ship built‑in scaling primitives. [Production advice]
So: Cloudflare load balancer + multiple app instances (e.g. on Hetzner) is in line with how Wasp is expected to be used today.
2. PgBoss jobs and horizontal scaling
The key constraints from the current jobs design:
- Jobs (pg-boss) are started “alongside your web server’s application, where both are simultaneously operational,” and they share CPU with the rest of the server logic. [pg-boss considerations]
- Wasp “does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads.” [pg-boss considerations]
PgBoss itself is used as the only job executor right now and is described as suitable for “low-volume production use cases” and not for CPU-heavy workloads. [Jobs docs]
So, from Wasp’s perspective today:
- It is expected that each app instance will run pg-boss alongside Express.
- There is no first-class, supported way in Wasp to run pg-boss in a separate worker-only process or to selectively disable it per instance.
- The team explicitly calls out the lack of independent scaling as a current limitation.
3. Your idea: only one instance initializes PgBoss
Modifying
wasp.main (or other generated code) so that only one instance initializes pg-boss is not described or supported in the docs or issues, and there’s no guidance on how safe that is across upgrades. The knowledge sources don’t document:
- A supported hook for “turn off jobs on this instance”.
- A recommended pattern for dedicating one instance as a worker and others as API-only.
Given that, I can’t confidently say this is safe or stable across Wasp versions; it would be an unsupported customization.
4. Current “official” stance and roadmap direction
From issues and comments, it’s clear that:
- There is interest in documenting “Production / Scaling” and giving clearer guidance, but that page does not yet exist. [Production advice; Perf issue]
- Jobs via pg-boss are intentionally a simple, low‑infrastructure solution (Node + PostgreSQL, no extra infra) with tradeoffs, including that you can’t scale workers independently. [Background jobs RFC; Jobs docs; pg-boss considerations]
- Future directions under discussion include:
- Better control of pg-boss DB usage and options via PG_BOSS_NEW_OPTIONS. [PgBoss DB usage; Jobs docs]
- Support for multiple servers / microservices and more advanced queueing & scaling patterns, but this is still at the “idea / design” stage. [Multiple servers]
There is no documented “recommended architecture” for splitting API and jobs today.
5. Practical implications for you
Based on the available information:
- Horizontally scaling the HTTP API behind Cloudflare (or any load balancer) is aligned with Wasp’s model; you just treat it as a normal Node app.
- Horizontally scaling PgBoss is limited:
- The intended current mode is: each instance runs both API and jobs; PgBoss and Postgres handle multi‑instance coordination.
- Offloading jobs to a single, special instance by hacking generated code is not documented and may break with Wasp upgrades.
If you’re pushing into higher‑volume or more complex job workloads (e.g. heavy CPU or separately scaled workers), that’s exactly the space Wasp’s roadmap mentions as future work (multiple servers, more sophisticated queueing), but there isn’t an officially blessed pattern yet. [Multiple servers; pg-boss considerations]
So the safest “supported” setup right now, strictly based on the docs, is:
- Use your load balancer + N identical Wasp instances.
- Let each instance run both Express and PgBoss as generated.
- Keep jobs non‑CPU‑intensive and “low‑volume,” and tune PgBoss via PG_BOSS_NEW_OPTIONS if needed. [Jobs docs; pg-boss considerations]
For anything beyond that (like a dedicated jobs instance), the knowledge sources don’t provide an endorsed pattern, so you’d be in “advanced / unsupported customization” territory.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------
Sorry @Ramon, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist:
Perhaps try again in 15mins?