The boring glue: scaffolding a new service in one script

The logic of a new service is usually the small part. You can write the actual thing it does in an afternoon. What eats the week is the glue: the Dockerfile, the build spec, the task definition, the secret, the health check, the twelve small correct decisions that have nothing to do with what the service does and everything to do with whether it deploys. Get one of them subtly wrong and you lose a morning to a build that fails for a reason that has nothing to do with your code.

The teams who add services cheaply have made this glue disappear. Not by having fewer moving parts, but by never writing them by hand twice. One script, one template, and the boring parts are correct before you’ve typed a line of logic.

The cost of doing it by hand every time

Every hand-built service is a fresh opportunity to get the base image wrong, forget a build step, misname the secret, or point the health check at a path that doesn’t exist. None of these are hard. All of them are easy to get subtly wrong, and the failure shows up minutes later in a build log, out of context. Multiply by a dozen services and you’ve spent real time debugging your own inconsistency. The problem was never the individual mistake. It was that a human was re-deriving the same boilerplate from memory, and memory drifts.

A template plus a script

The fix is unglamorous. Keep a _template/ directory with every boring file already filled in and correct. Keep one script that copies it, renames the placeholders, and leaves you with only the interesting file to write.

#!/usr/bin/env bash
# new-service.sh <name>
set -euo pipefail
NAME="$1"

cp -r _template "$NAME"
cd "$NAME"

# stamp the name through every file that references it
grep -rl '__SERVICE_NAME__' . | xargs sed -i "s/__SERVICE_NAME__/$NAME/g"

echo "created $NAME/"
echo "next: write server.py, then follow NEW-SERVICE-CHECKLIST.md"

That’s the entire trick. The template carries the accumulated correctness of every service before it. When I learn something the hard way, like a build cache setting that shaves a minute off every build, I fix it once in the template and every future service is born with the fix. The script guarantees the placeholder substitution is complete, so there’s no half-renamed file waiting to confuse someone in three months.

The checklist covers what a script can’t

Some steps can’t or shouldn’t be automated because they touch shared state or need a human decision: creating the service’s secret, registering it in the build pipeline, adding it to the gateway, confirming the health check goes green. So they live in a short checklist that ships next to the template:

NEW-SERVICE-CHECKLIST.md
- [ ] run new-service.sh, write server.py
- [ ] create the secret in the secrets store (never in the repo)
- [ ] add the build project / pipeline entry
- [ ] register in the gateway
- [ ] first deploy, confirm health check is green
- [ ] confirm it appears in logging and metrics

A checklist in writing that gets followed every time beats a heroic memory every time. The specific line that has saved me most often is “create the secret,” because the service builds and deploys perfectly and then falls over on first request looking for a secret nobody made. It’s a five-minute fix that costs an hour to diagnose if you weren’t reminded to do it up front.

Automate the deterministic, checklist the judgemental

The dividing line is worth stating plainly, because people try to automate the wrong half. Anything with a single correct answer should be in the template or the script: file layout, base image, build steps, task definition shape. Anything that requires a decision or touches shared state should be in the checklist: secrets, pipeline registration, cutover. Automating the deterministic parts removes mistakes. Leaving the judgemental parts to a checklist keeps a human in the loop where a human belongs.

The boring conclusion

The reason some teams add a service in an hour and others lose a week to it is not talent, it’s whether they’ve made the boilerplate disappear. Put every boring file in a template, stamp out new services with a script, and keep the handful of human steps in a checklist you follow every time. It is deeply unexciting work that pays back on every service you ever add again. The glue is where the time goes, so make the glue free.