Why template sprawl became a real platform issue

I inherited the classic Coder setup: several templates that were “mostly the same” but had just enough differences to hurt.

Quick context: Coder is a platform for provisioning cloud development workspaces from infrastructure templates. In this article, “template” means the infrastructure definition used to create a workspace. Convex and Nhost are optional backend platforms teams can run from that workspace. S3 refers to object storage used for files and artifact flows. The core problem here was keeping one reliable template experience while still supporting those optional paths.

Each template started with good intent. One for a specific IDE. One for a team with database defaults. One for an experimental backend. Months later, we had drift:

• a fix in one template not copied to others
• startup scripts with different assumptions
• subtle security and capacity defaults diverging across teams

This was not just untidy repo structure. It slowed onboarding, increased support load, and made infra behavior unpredictable.

I decided to collapse the set into one parameterized template with explicit options.

Consolidation principle: one template, intentional choices

The core idea was simple: a single baseline template with configuration switches for meaningful differences.

I exposed parameters for:

• IDE selection
• optional Convex and Nhost services
• PostgreSQL enablement
• S3 integration
• workspace cloning behavior

I did not try to make everything configurable. Too many knobs just recreates chaos inside one file. I limited options to paths teams actually used and that we could test reliably.

Hardening had to be central, not copied

Before consolidation, the same operational fixes kept reappearing in different branches of template code.

The top recurring issues were:

• startup race conditions where dependent services were “up” but not ready
• unsafe default capacity settings
• node placement/affinity mismatches in clustered environments

Putting hardening in one template meant each fix landed once and became the default for everybody.

This reduced the hidden tax of “remember to backport that infra fix to four other templates.”

Workspace cloning changed the design constraints

Cloning sounds like convenience, but it raises the bar for determinism.

If clone + startup behavior is unstable, cloning multiplies bad state quickly.

So I treated cloning as a first-class path and tightened provisioning order:

• create base environment
• validate optional dependencies and compatibility
• initialize services in predictable order
• run readiness checks before handing workspace to user

This removed a lot of “works on second restart” behavior.

Optional services without optional discipline

Convex/Nhost, database, and object storage options can drift into untested branches if you are not strict.

I avoided that by keeping compatibility logic explicit and centralized. If a combination was unsupported, provisioning failed early with a clear message.

Silent partial enablement is worse than hard failure. It gives users a broken environment that looks healthy for ten minutes.

I also made dependency expectations obvious in parameter docs. Ambiguous toggles are support tickets waiting to happen.

The UX side of template parameters

Infrastructure engineers like parameters. Most users do not want fifteen of them.

I grouped options into a small set with sane defaults:

• quick-start profile for common use
• advanced profile for teams with custom backend/storage needs

That reduced decision fatigue and kept the template approachable for first-time users.

If every workspace creation starts with a long questionnaire, people pick random defaults and hope. That is not a platform strategy.

Tradeoffs and maintenance reality

Consolidation did not eliminate complexity. It changed where complexity lives.

The tradeoffs are clear:

• one template has more conditional logic than any old single-purpose template
• compatibility tests matter more because one mistake affects everyone
• release notes and docs must stay accurate or trust drops fast

I still prefer this model because complexity is now visible and maintainable instead of duplicated and drifting.

What improved after consolidation

The practical wins showed up quickly.

• onboarding became faster because there was one documented path
• operational fixes reached all users by default
• support issues were easier to reproduce because environments were less fragmented
• teams could still choose IDE and backend options without forking template code

The biggest improvement was predictability. People stopped asking, “Which template should I use this time?”

What I would improve next

If I keep pushing this system, I want stronger automated validation around the parameter matrix. Right now it is good, but I still rely on targeted manual checks for less common combos.

I also want better telemetry from provisioning phases so we can see where failures cluster by parameter set. That helps us simplify the template over time instead of just adding toggles.

Finally, I would formalize deprecation policy for options. Consolidation only stays healthy if old flags are removed deliberately rather than kept forever.

Takeaway

Template consolidation is not a “clean up the repo” project. It is platform reliability work.

One parameterized template gave us shared defaults, shared hardening, and a clearer operational model. It still requires discipline, but it replaced a scattered system where every improvement had to be rediscovered in multiple places.

For teams running AI-enabled developer workspaces, that trade is worth it. Consistency is a feature, and it compounds.