Cookiecutter Template for Production Microservices
The day-to-day symptoms are painfully familiar: new repos with different layouts, missing tests, logging that cannot be aggregated, and ad-hoc infra changes that nobody remembers. That friction surfaces as slow onboarding, error-prone deployments, and an ops load that grows with every "small" service.
Contents
- Why a cookiecutter microservice template becomes your team's velocity multiplier
- What's inside the template: repository layout, configs, and testing harness
- CI/CD and IaC patterns that keep services deployable and auditable
- How to publish, version, and maintain a living template
- Practical scaffolding checklist and step-by-step bootstrap
Why a cookiecutter microservice template becomes your team's velocity multiplier
Templates are not about convenience; they are about guardrails. When you codify the non-negotiable parts of a service (how it logs, how tests are structured, how infra is declared), you remove repetitive cognitive work and reduce the risk of critical omissions. Cookiecutter is a widely used CLI for project templates that lets you capture those guardrails as an actual repo users run to bootstrap services. (cookiecutter.readthedocs.io)
- Speed: New services reach a working CI and basic observability within hours instead of days because the scaffold includes build, test, and deploy wiring.
- Consistency: A single canonical layout is easier to review, document, and automate against.
- Safety: Defaulting to tested patterns and IaC reduces surprises in production.
| Area | Manual bootstrap | Cookiecutter template (opinionated) |
| --- | ---: | :--- |
| Time to first commit | High friction | Low friction |
| Repo layout consistency | Variable | Consistent |
| Tests included by default | Often missing | Included |
| Infra-initialized | Rare | Skeleton (Terraform/Helm) |
| Logging/observability standard | Ad hoc | Opinionated (stdout + structured) |
Cookiecutter templates are also maintainable — you can treat the template itself as a first-class product: release it, version it, and add CI that tests the template by generating an example project and running its tests. (cookiecutter.readthedocs.io)
What's inside the template: repository layout, configs, and testing harness
A production-ready microservice template is not just a handful of files; it’s a packaged developer experience. Make the template opinionated and narrow in scope so it covers the 80% day-one needs, while leaving extension points for the 20% special cases.
Example high-level layout (use exactly this pattern as a starting point):
cookiecutter-microservice/
├── cookiecutter.json
├── hooks/
│ ├── pre_prompt.py
│ ├── pre_gen_project.py
│ └── post_gen_project.py
├── {{cookiecutter.service_slug}}/
│ ├── app/
│ │ ├── __init__.py
│ │ └── main.py
│ ├── tests/
│ │ ├── unit/
│ │ ├── integration/
│ │ └── contract/
│ ├── Dockerfile
│ ├── Makefile
│ └── README.md
├── .github/
│ └── workflows/
│ ├── ci.yml
│ └── deploy.yml
├── iac/
│ ├── terraform/
│ │ └── modules/
│ └── k8s/
└── docs/
Minimal cookiecutter.json example (declare the user's inputs and sensible defaults):
{
"service_name": "Awesome Service",
"service_slug": "awesome_service",
"description": "An opinionated microservice",
"python_version": "3.11",
"use_postgres": "no",
"template_version": "0.1.0"
}
Key template pieces explained
- cookiecutter.json: the schema of choices and defaults that drives prompts and generated files. (cookiecutter.readthedocs.io)
- hooks/: pre/post hooks let you validate inputs, remove conditional artifacts, or run git init and the first commit; these run inside the generated project. Use Python hooks for cross-platform reliability. (cookiecutter.readthedocs.io)
- tests/: include unit, integration, and contract categories. Provide conftest.py fixtures so teams can run only unit tests locally and the CI pipeline can orchestrate heavier integration suites. pytest fixtures and scopes are the right abstraction for scalable test harnesses. (docs.pytest.org)
- Dockerfile: provide a multi-stage Dockerfile that produces small, secure runtime images (non-root user, pinned base images). Add a .dockerignore. (docs.docker.com)
- iac/terraform: include a minimal module or examples/ that show how to wire the service into the platform. Follow the standard Terraform module structure so your platform tooling can consume it predictably. (developer.hashicorp.com)
Logging and observability (must-haves)
- Emit logs to stdout and prefer structured (JSON) events with fields for timestamp, level, service, env, request_id/trace_id. This aligns with the Twelve-Factor recommendation to treat logs as event streams and with OpenTelemetry logging conventions for trace correlation. (12factor.net)
Example Python stdout JSON logger skeleton:
# app/logging_config.py
import logging, sys
from pythonjsonlogger import jsonlogger
handler = logging.StreamHandler(sys.stdout)
formatter = jsonlogger.JsonFormatter('%(asctime)s %(levelname)s %(name)s %(message)s')
handler.setFormatter(formatter)
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(handler)
> Important: Never bake secrets, credentials, or environment-specific endpoints into generated code. Template values should be placeholders or documented environment references and the template should integrate with your secrets manager pattern.
CI/CD and IaC patterns that keep services deployable and auditable
The template must come with opinionated CI that demonstrates the end-to-end flow: build, lint, unit tests, integration tests (optional), security checks, image build + scan, and deploy (or a deployable artifact to a registry). Reusable workflows let you package CI best practices centrally and call them from downstream repos. Use GitHub Actions reusable workflows (or your platform equivalent) and reference workflows by tag/sha for stability. (docs.github.com)
Pattern: split responsibilities across pipelines
- Template CI (runs on PR): fast checks — lint, unit tests, simple integration smoke tests.
- Template CD (runs on release to main): build image, run full integration tests, run IaC validations, produce artifacts (container image, helm charts, Terraform plan).
- Infra pipeline (separate repo or reusable workflow): manage long‑lived resources (VPC, clusters) and apply with strong gating and approvals.
Terraform in CI: validate and plan in PRs, apply from protected branches
- Use hashicorp/setup-terraform in Actions to install and run Terraform in CI, run terraform fmt, terraform validate, and terraform plan and post the plan to the PR for reviewer visibility. Use the commit SHA or tag when referencing reusable workflows to avoid unexpected changes. (hashicorp/setup-terraform)
Example GitHub Actions snippet (CI job):
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Install deps
run: pip install -r requirements-dev.txt
- name: Run unit tests
run: pytest -q
- name: Build container (CI artifact)
run: docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
Example Terraform plan job (PR visibility):
- name: Setup Terraform
uses: hashicorp/setup-terraform@v3
- name: Terraform Init
run: terraform init -input=false
- name: Terraform Validate
run: terraform validate -no-color
- name: Terraform Plan
id: plan
run: terraform plan -no-color -input=false
Design notes
- Use commit SHAs for reusable workflow references in production to preserve reproducibility; @v1 gives convenience but not immutability. (docs.github.com)
- Keep Terraform modules focused and composable — one module per responsibility and examples demonstrating composition. (developer.hashicorp.com)
How to publish, version, and maintain a living template
Treat the template as a product. That means versioning, releases, compatibility notes, and a straightforward upgrade path for generated projects.
Versioning rules
- Adopt Semantic Versioning for template releases: major bumps for breaking changes, minor for backwards-compatible additions, patch for fixes. Link to your policy from the template README so consumers understand upgrade implications. (semver.org)
Publishing and distribution
- Host the template on a Git host (private repo for internal templates, public for OSS). Use Git tags and GitHub Releases to mark versions.
- Provide an example project in the repo (or an examples/ directory) that CI can generate and run against, so you test the template itself on every change. (cookiecutter.readthedocs.io)
Maintaining generated projects over time
- Ship your template with cruft support so generated projects can be linked back and kept in-sync with template improvements. cruft check can run in the service repo CI and cruft update can be used in a controlled manner to apply template upgrades. (cruft.github.io)
- Keep a CHANGELOG.md and release notes that explain migration steps for every non-trivial release. Use template_version in cookiecutter.json so generated projects can record what they were created from.
Documenting template inputs
- Add human-focused variable descriptions (a README or tools like cookiecutter-autodocs) so consumers know what each option does. Consider an interactive README section for the common flows. (cookiecutter-autodocs.readthedocs.io)
Practical scaffolding checklist and step-by-step bootstrap
This checklist lets you create a production-ready microservice cookiecutter template that your team will adopt.
1. Decide scope and defaults
- Pick a small set of opinionated defaults (logging format, test framework, CI provider, runtime).
- Document reasons in an ADR (Architectural Decision Record).
2. Create cookiecutter.json
- Include service_name, service_slug, python_version, template_version, and feature toggles (use_postgres, enable_metrics).
3. Implement the skeleton
- Add app/, tests/ (unit, integration, contract), Dockerfile, Makefile, docs/.
4. Add hooks/ for validation and post-generation work
- pre_gen_project.py validate service_slug and required tools.
- post_gen_project.py run git init, create main branch, and make the initial commit. (cookiecutter.readthedocs.io)
Example post_gen_project.py:
# hooks/post_gen_project.py
import os
import subprocess
def run(cmd):
subprocess.run(cmd, shell=True, check=True)
if __name__ == "__main__":
run("git init")
run("git checkout -b main")
run("git add -A")
run("git commit -m 'chore: initial commit from template'")
5. Ship a minimal sample app + tests and make CI run them
- CI should generate a sample project using cookiecutter and run its tests.
- Add a CI job that runs cookiecutter . --no-input with fixture values and then pytest inside the generated project.
6. Add IaC skeleton and Terraform module examples
- Follow HashiCorp's standard module structure and include examples/ that show how to compose modules into an environment. (developer.hashicorp.com)
7. Add CI/CD patterns
- Provide a ci.yml reusable workflow for lint/test/build.
- Provide a deploy.yml reusable workflow that runs terraform plan (and optionally apply from protected branches). Use hashicorp/setup-terraform in these workflows. (hashicorp/setup-terraform)
8. Add observability defaults
- Log to stdout with structured JSON and include a tracing correlation field (trace_id).
- Add a minimal metrics endpoint or exporter example.
9. Security and image hygiene
- Provide a multi-stage Dockerfile, run vulnerability scans in CI, and pin base images or use verified images. (docs.docker.com)
10. Release, document, and support updates
- Tag the template with a semver release and publish release notes describing migration steps. (semver.org)
- Add cruft guidance to help generated projects adopt template improvements. (cruft.github.io)
Quick CI job example to test the template itself (generate + run tests):
name: Template self-test
on: [push]
jobs:
test-template:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install cookiecutter
run: pip install cookiecutter
- name: Generate example project
run: cookiecutter . --no-input service_slug=ci_test_service template_version=0.1.0
- name: Run generated project's tests
run: |
cd ci_test_service
pip install -r requirements-dev.txt
pytest -q
Sources
cookiecutter — cookiecutter 2.3.1 documentation - Core cookiecutter usage, cookiecutter.json behavior, and project-template concepts. (cookiecutter.readthedocs.io)
The Twelve-Factor App — Logs - Recommendation to write logs to stdout and treat logs as event streams. (12factor.net)
Semantic Versioning 2.0.0 - SemVer rules for communicating breaking and compatible changes. (semver.org)
Reuse workflows - GitHub Docs - Guidance on reusable workflows, referencing by {owner}/{repo}/.github/workflows/{file}@{ref}, and stable references. (docs.github.com)
Standard Module Structure | Terraform | HashiCorp Developer - Recommended Terraform module layout and examples/ guidance. (developer.hashicorp.com)
Hooks — cookiecutter documentation (stable) - Pre/post-generate hook behavior and examples. (cookiecutter.readthedocs.io)
How to use fixtures — pytest documentation - Fixture patterns, scopes, and organizing tests for maintainability and speed. (docs.pytest.org)
Dockerfile Best Practices — Docker Docs - Multi-stage builds, base image choices, .dockerignore, and image hygiene. (docs.docker.com)
OpenTelemetry Logs - Data model & best practices - Structured log conventions, trace correlation fields, and collector guidance. (opentelemetry.io)
hashicorp/setup-terraform · GitHub - Action for installing and running Terraform in GitHub Actions; examples for terraform plan and PR comments. (hashicorp/setup-terraform)
Cookiecutter (official website) - Project overview and organizational usage patterns for cookiecutter templates. (cookiecutter.io)
cruft — Keep projects in sync with Cookiecutter templates - Workflow and commands for linking projects to templates and automating safe template updates. (cruft.github.io)
Best Practices: Organising Terraform and Application Code – HashiCorp Help Center - Guidance on monorepo vs polyrepo for infra and app code. (support.hashicorp.com)
cookiecutter-autodocs — docs - Tooling to document template inputs and provide richer metadata for cookiecutter variables. (cookiecutter-autodocs.readthedocs.io)
govcookiecutter — example template with CI/CD and docs - Example of a mature organization template that includes CI, documentation, and cruft guidance. (best-practice-and-impact.github.io)
Make the template the narrow, opinionated path your teams use every day; ship it, version it, and test it so the first commit of every new service already carries the operational defaults you depend on.
Mentions
GitHub ActionsでTerraformの品質チェックを自動化する はじめに 普段の業務では、Terraformを利用したAWSインフラの設計・構築に取り組んでいます。 Terraformの設定変更時には、フォーマットや構文のチェックが重要です。ローカルでも実行できますが、その実行結果はGitHub上に共有されないため、PRのレビュアーがチェック結果を確認しにくいという課題があります。 そこで今回は、GitHub Actionsを利用して、PR作成時にTerraformの品質チェックを自動実行し、チェック結果をGitHub上で確認できるようにしました。 今回やること PR作成時に、以下の3つを自動実行します。 terraform fmt：Terraformコードのフォーマットをチェックする terraform init：Terraformの初期化を行う terraform validate：Terraformの設定を検証する 今回はTerraformの設定ファイルがリポジトリのルートディレクトリにあることを前提としています。 GitHub Actionsのワークフロー 今回作成したワークフローは以下のとおりです。 name: Terraform Quality Check on: pull_request: permissions: contents: read jobs: terraform-quality: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v7 - name: Setup Terraform uses: hashicorp/setup-terraform@v4 - name: Check formatting run: terraform fmt -check -recursive - name: Initialize Terraform run: terraform init -backend=false - name: Validate Terraform run: terraform validate ※ Actionのバージョンは、利用時に公式リポジトリで最新バージョンや互換性を確認してください。 各処理の役割 1. PR作成時にワークフローを実行する on: pull_request: pull_request を指定することで、PRに関連するイベントを契機にワークフローが実行されます。 これにより、PR上でチェック結果を確認できるようになります。 2. Terraformのフォーマットをチェックする - name: Check formatting run: terraform fmt -check -recursive terraform fmt は、Terraformの設定ファイルを標準的な形式に自動整形するコマンドです。 一方、-check を指定すると、自動整形は行わず、フォーマットが正しいかをチェックします。また、-recursive を指定することで、サブディレクトリも対象にできます。 フォーマットに問題がある場合は、コマンドが失敗します。 ローカルでは terraform fmt -recursive で自動整形し、GitHub Actionsでは terraform fmt -check -recursive で修正漏れを検出する方針にしました。 3. Terraformを初期化する - name: Initialize Terraform run: terraform init -backend=false terraform init は、Terraformの実行に必要なプロバイダーなどを初期化するコマンドです。 今回は -backend=false を指定しています。 このオプションにより、バックエンドの初期化をスキップできます。例えば、S3などをTerraformのState保存先として設定している場合でも、バックエンドへの接続・初期化を避けて検証を進められます。 なお、バックエンドをスキップしても、プロバイダーやモジュールのダウンロードが発生する場合があります。 4. Terraformの設定を検証する - name: Validate Terraform run: terraform validate terraform validate は、Terraformの構文や設定の内部的な整合性を検証するコマンドです。 例えば、設定の構文エラーや、リソースの引数・属性の指定に問題がある場合などを検出できます。 ただし、AWS上にリソースを作成できるか、IAM権限が十分か、設計が業務要件を満たしているかといったことまでは検証できません。 実行前には、terraform init などで必要な初期化を済ませておく必要があります。 実際に動かしてみた 作成したワークフローをPRで実行し、各ステップの結果を確認しました。 Check formatting：成功 Initialize Terraform：成功 Validate Terraform：成功 terraform validate では、以下のメッセージが表示されました。 Success! The configuration is valid. 一方、terraform fmt -check -recursive は、問題がなければ特にメッセージが表示されない場合があります。GitHub Actionsのステップが成功していることを確認しました。 このように、PR上で各チェックの実行結果を確認できることが分かりました。 やってみて学んだこと 今回、特に学びになったのは、Terraformのコマンドをローカルで実行することと、CIで自動実行することの違いです。 ローカルでチェックするだけでなく、PR作成時に自動実行することで、チェックの実行漏れを防ぎやすくなり、結果もGitHub上で確認できます。 また、各コマンドには異なる役割があります。 terraform fmt -check：フォーマットのチェック terraform init -backend=false：バックエンドを初期化せずにTerraformを初期化 terraform validate：設定の構文や内部整合性の検証 これらを組み合わせることで、AWSへのデプロイを行う前に、Terraformコードの基本的な品質を確認できるようになります。 まとめ 今回は、GitHub Actionsを使って、PR作成時にTerraformの品質チェックを自動実行する仕組みを作りました。 これまではローカルで実行していたチェックをCIに組み込むことで、PR上で結果を確認できるようになりました。 今後は、Terraformのセキュリティスキャンやテストなども組み合わせ、PRの段階で問題を検出できる仕組みを少しずつ改善していきたいと思います。 参考 Terraform fmt Terraform init Terraform validate GitHub Actions ワークフロー構文 actions/checkout hashicorp/setup-terraform
Cookiecutter Template for Production Microservices The day-to-day symptoms are painfully familiar: new repos with different layouts, missing tests, logging that cannot be aggregated, and ad-hoc infra changes that nobody remembers. That friction surfaces as slow onboarding, error-prone deployments, and an ops load that grows with every "small" service. Contents - Why a cookiecutter microservice template becomes your team's velocity multiplier - What's inside the template: repository layout, configs, and testing harness - CI/CD and IaC patterns that keep services deployable and auditable - How to publish, version, and maintain a living template - Practical scaffolding checklist and step-by-step bootstrap Why a cookiecutter microservice template becomes your team's velocity multiplier Templates are not about convenience; they are about guardrails. When you codify the non-negotiable parts of a service (how it logs, how tests are structured, how infra is declared), you remove repetitive cognitive work and reduce the risk of critical omissions. Cookiecutter is a widely used CLI for project templates that lets you capture those guardrails as an actual repo users run to bootstrap services. (cookiecutter.readthedocs.io) - Speed: New services reach a working CI and basic observability within hours instead of days because the scaffold includes build, test, and deploy wiring. - Consistency: A single canonical layout is easier to review, document, and automate against. - Safety: Defaulting to tested patterns and IaC reduces surprises in production. | Area | Manual bootstrap | Cookiecutter template (opinionated) | | --- | ---: | :--- | | Time to first commit | High friction | Low friction | | Repo layout consistency | Variable | Consistent | | Tests included by default | Often missing | Included | | Infra-initialized | Rare | Skeleton (Terraform/Helm) | | Logging/observability standard | Ad hoc | Opinionated (stdout + structured) | Cookiecutter templates are also maintainable — you can treat the template itself as a first-class product: release it, version it, and add CI that tests the template by generating an example project and running its tests. (cookiecutter.readthedocs.io) What's inside the template: repository layout, configs, and testing harness A production-ready microservice template is not just a handful of files; it’s a packaged developer experience. Make the template opinionated and narrow in scope so it covers the 80% day-one needs, while leaving extension points for the 20% special cases. Example high-level layout (use exactly this pattern as a starting point): cookiecutter-microservice/ ├── cookiecutter.json ├── hooks/ │ ├── pre_prompt.py │ ├── pre_gen_project.py │ └── post_gen_project.py ├── {{cookiecutter.service_slug}}/ │ ├── app/ │ │ ├── __init__.py │ │ └── main.py │ ├── tests/ │ │ ├── unit/ │ │ ├── integration/ │ │ └── contract/ │ ├── Dockerfile │ ├── Makefile │ └── README.md ├── .github/ │ └── workflows/ │ ├── ci.yml │ └── deploy.yml ├── iac/ │ ├── terraform/ │ │ └── modules/ │ └── k8s/ └── docs/ Minimal cookiecutter.json example (declare the user's inputs and sensible defaults): { "service_name": "Awesome Service", "service_slug": "awesome_service", "description": "An opinionated microservice", "python_version": "3.11", "use_postgres": "no", "template_version": "0.1.0" } Key template pieces explained - cookiecutter.json: the schema of choices and defaults that drives prompts and generated files. (cookiecutter.readthedocs.io) - hooks/: pre/post hooks let you validate inputs, remove conditional artifacts, or run git init and the first commit; these run inside the generated project. Use Python hooks for cross-platform reliability. (cookiecutter.readthedocs.io) - tests/: include unit, integration, and contract categories. Provide conftest.py fixtures so teams can run only unit tests locally and the CI pipeline can orchestrate heavier integration suites. pytest fixtures and scopes are the right abstraction for scalable test harnesses. (docs.pytest.org) - Dockerfile: provide a multi-stage Dockerfile that produces small, secure runtime images (non-root user, pinned base images). Add a .dockerignore. (docs.docker.com) - iac/terraform: include a minimal module or examples/ that show how to wire the service into the platform. Follow the standard Terraform module structure so your platform tooling can consume it predictably. (developer.hashicorp.com) Logging and observability (must-haves) - Emit logs to stdout and prefer structured (JSON) events with fields for timestamp, level, service, env, request_id/trace_id. This aligns with the Twelve-Factor recommendation to treat logs as event streams and with OpenTelemetry logging conventions for trace correlation. (12factor.net) Example Python stdout JSON logger skeleton: # app/logging_config.py import logging, sys from pythonjsonlogger import jsonlogger handler = logging.StreamHandler(sys.stdout) formatter = jsonlogger.JsonFormatter('%(asctime)s %(levelname)s %(name)s %(message)s') handler.setFormatter(formatter) root = logging.getLogger() root.setLevel(logging.INFO) root.addHandler(handler) > Important: Never bake secrets, credentials, or environment-specific endpoints into generated code. Template values should be placeholders or documented environment references and the template should integrate with your secrets manager pattern. CI/CD and IaC patterns that keep services deployable and auditable The template must come with opinionated CI that demonstrates the end-to-end flow: build, lint, unit tests, integration tests (optional), security checks, image build + scan, and deploy (or a deployable artifact to a registry). Reusable workflows let you package CI best practices centrally and call them from downstream repos. Use GitHub Actions reusable workflows (or your platform equivalent) and reference workflows by tag/sha for stability. (docs.github.com) Pattern: split responsibilities across pipelines - Template CI (runs on PR): fast checks — lint, unit tests, simple integration smoke tests. - Template CD (runs on release to main): build image, run full integration tests, run IaC validations, produce artifacts (container image, helm charts, Terraform plan). - Infra pipeline (separate repo or reusable workflow): manage long‑lived resources (VPC, clusters) and apply with strong gating and approvals. Terraform in CI: validate and plan in PRs, apply from protected branches - Use hashicorp/setup-terraform in Actions to install and run Terraform in CI, run terraform fmt, terraform validate, and terraform plan and post the plan to the PR for reviewer visibility. Use the commit SHA or tag when referencing reusable workflows to avoid unexpected changes. (hashicorp/setup-terraform) Example GitHub Actions snippet (CI job): name: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install deps run: pip install -r requirements-dev.txt - name: Run unit tests run: pytest -q - name: Build container (CI artifact) run: docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} . Example Terraform plan job (PR visibility): - name: Setup Terraform uses: hashicorp/setup-terraform@v3 - name: Terraform Init run: terraform init -input=false - name: Terraform Validate run: terraform validate -no-color - name: Terraform Plan id: plan run: terraform plan -no-color -input=false Design notes - Use commit SHAs for reusable workflow references in production to preserve reproducibility; @v1 gives convenience but not immutability. (docs.github.com) - Keep Terraform modules focused and composable — one module per responsibility and examples demonstrating composition. (developer.hashicorp.com) How to publish, version, and maintain a living template Treat the template as a product. That means versioning, releases, compatibility notes, and a straightforward upgrade path for generated projects. Versioning rules - Adopt Semantic Versioning for template releases: major bumps for breaking changes, minor for backwards-compatible additions, patch for fixes. Link to your policy from the template README so consumers understand upgrade implications. (semver.org) Publishing and distribution - Host the template on a Git host (private repo for internal templates, public for OSS). Use Git tags and GitHub Releases to mark versions. - Provide an example project in the repo (or an examples/ directory) that CI can generate and run against, so you test the template itself on every change. (cookiecutter.readthedocs.io) Maintaining generated projects over time - Ship your template with cruft support so generated projects can be linked back and kept in-sync with template improvements. cruft check can run in the service repo CI and cruft update can be used in a controlled manner to apply template upgrades. (cruft.github.io) - Keep a CHANGELOG.md and release notes that explain migration steps for every non-trivial release. Use template_version in cookiecutter.json so generated projects can record what they were created from. Documenting template inputs - Add human-focused variable descriptions (a README or tools like cookiecutter-autodocs) so consumers know what each option does. Consider an interactive README section for the common flows. (cookiecutter-autodocs.readthedocs.io) Practical scaffolding checklist and step-by-step bootstrap This checklist lets you create a production-ready microservice cookiecutter template that your team will adopt. 1. Decide scope and defaults - Pick a small set of opinionated defaults (logging format, test framework, CI provider, runtime). - Document reasons in an ADR (Architectural Decision Record). 2. Create cookiecutter.json - Include service_name, service_slug, python_version, template_version, and feature toggles (use_postgres, enable_metrics). 3. Implement the skeleton - Add app/, tests/ (unit, integration, contract), Dockerfile, Makefile, docs/. 4. Add hooks/ for validation and post-generation work - pre_gen_project.py validate service_slug and required tools. - post_gen_project.py run git init, create main branch, and make the initial commit. (cookiecutter.readthedocs.io) Example post_gen_project.py: # hooks/post_gen_project.py import os import subprocess def run(cmd): subprocess.run(cmd, shell=True, check=True) if __name__ == "__main__": run("git init") run("git checkout -b main") run("git add -A") run("git commit -m 'chore: initial commit from template'") 5. Ship a minimal sample app + tests and make CI run them - CI should generate a sample project using cookiecutter and run its tests. - Add a CI job that runs cookiecutter . --no-input with fixture values and then pytest inside the generated project. 6. Add IaC skeleton and Terraform module examples - Follow HashiCorp's standard module structure and include examples/ that show how to compose modules into an environment. (developer.hashicorp.com) 7. Add CI/CD patterns - Provide a ci.yml reusable workflow for lint/test/build. - Provide a deploy.yml reusable workflow that runs terraform plan (and optionally apply from protected branches). Use hashicorp/setup-terraform in these workflows. (hashicorp/setup-terraform) 8. Add observability defaults - Log to stdout with structured JSON and include a tracing correlation field (trace_id). - Add a minimal metrics endpoint or exporter example. 9. Security and image hygiene - Provide a multi-stage Dockerfile, run vulnerability scans in CI, and pin base images or use verified images. (docs.docker.com) 10. Release, document, and support updates - Tag the template with a semver release and publish release notes describing migration steps. (semver.org) - Add cruft guidance to help generated projects adopt template improvements. (cruft.github.io) Quick CI job example to test the template itself (generate + run tests): name: Template self-test on: [push] jobs: test-template: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: '3.11' - name: Install cookiecutter run: pip install cookiecutter - name: Generate example project run: cookiecutter . --no-input service_slug=ci_test_service template_version=0.1.0 - name: Run generated project's tests run: | cd ci_test_service pip install -r requirements-dev.txt pytest -q Sources cookiecutter — cookiecutter 2.3.1 documentation - Core cookiecutter usage, cookiecutter.json behavior, and project-template concepts. (cookiecutter.readthedocs.io) The Twelve-Factor App — Logs - Recommendation to write logs to stdout and treat logs as event streams. (12factor.net) Semantic Versioning 2.0.0 - SemVer rules for communicating breaking and compatible changes. (semver.org) Reuse workflows - GitHub Docs - Guidance on reusable workflows, referencing by {owner}/{repo}/.github/workflows/{file}@{ref}, and stable references. (docs.github.com) Standard Module Structure | Terraform | HashiCorp Developer - Recommended Terraform module layout and examples/ guidance. (developer.hashicorp.com) Hooks — cookiecutter documentation (stable) - Pre/post-generate hook behavior and examples. (cookiecutter.readthedocs.io) How to use fixtures — pytest documentation - Fixture patterns, scopes, and organizing tests for maintainability and speed. (docs.pytest.org) Dockerfile Best Practices — Docker Docs - Multi-stage builds, base image choices, .dockerignore, and image hygiene. (docs.docker.com) OpenTelemetry Logs - Data model & best practices - Structured log conventions, trace correlation fields, and collector guidance. (opentelemetry.io) hashicorp/setup-terraform · GitHub - Action for installing and running Terraform in GitHub Actions; examples for terraform plan and PR comments. (hashicorp/setup-terraform) Cookiecutter (official website) - Project overview and organizational usage patterns for cookiecutter templates. (cookiecutter.io) cruft — Keep projects in sync with Cookiecutter templates - Workflow and commands for linking projects to templates and automating safe template updates. (cruft.github.io) Best Practices: Organising Terraform and Application Code – HashiCorp Help Center - Guidance on monorepo vs polyrepo for infra and app code. (support.hashicorp.com) cookiecutter-autodocs — docs - Tooling to document template inputs and provide richer metadata for cookiecutter variables. (cookiecutter-autodocs.readthedocs.io) govcookiecutter — example template with CI/CD and docs - Example of a mature organization template that includes CI, documentation, and cruft guidance. (best-practice-and-impact.github.io) Make the template the narrow, opinionated path your teams use every day; ship it, version it, and test it so the first commit of every new service already carries the operational defaults you depend on.