Infrastructure Template for Modern DevOps applications

Production-ready scaffold for teams that want to ship infrastructure-as-code with Pulumi and Docker from day zero.

Possibilities

• Pulumi (Python) starter that exports environment metadata and tagging helpers.
• Reproducible Docker Compose workspace with a Pulumi-ready container and helper make tasks.
• CI pipelines for structural, policy, preview, security, unit, integration, mutation, and CLI-level checks.
• Release and template-sync automations to keep downstream repos aligned.
• Documentation on AWS credential management for secure automation using GitHub OIDC and short-lived credentials.

Why You Might Need It

Spin up consistent project infrastructure without wiring every component manually. This template gives DevOps teams a single source that:

• Encodes best practices from VilnaCRM’s production stack.
• Works out-of-the-box with AWS and Pulumi.
• Keeps infrastructure changes reviewable with local Pulumi previews, policy-pack guardrails, and CI test suites before deploying.

License

This software is distributed under the Creative Commons Zero v1.0 Universal license. Please read LICENSE for details.

Documentation

All project docs live under docs/ to keep everything version controlled. Start with the handbook and jump directly to common topics:

• Quick Start
• Local Tooling
• Development Environment
• PyCharm Autocomplete
• CI/CD and Secrets
• CI Quality Gates
• CI Guardrails
• CI Architecture
• Security Baseline
• Pulumi Guardrails
• uv and Rust-native Python tooling
• SRE Operations
• Testing and Validation
• Security
• Contributing
• Sponsorship

Community Q&A lives under the vilnacrm tag on Stack Overflow. For questions or feature requests, open an issue.

Local Pulumi test suites

Docker Compose CLI 2.24.0+ is required because docker-compose.yml uses the env_file.required flag (older Compose releases fail to parse it).

Environment files

The Makefile resolves the effective env file as the first existing file from .env and .env.empty.

• .env is git-ignored and should hold local secrets or developer-specific overrides.
• .env.empty is committed and acts as the minimal fallback so Docker Compose and make targets still run in a fresh clone.
• .env.dist remains an optional example/template file you can copy from when you want a fuller starting point; unlike .env.empty, it is not the automatic fallback used by the Makefile.

For onboarding, create or update .env with any local overrides you need, keep .env.empty safe to commit, and refresh .env.dist only when the example values or documented setup flow changes.

If you want a local uv environment outside Docker, seed it once so Pulumi's Automation API can still use pip for package discovery:

export UV_PROJECT_ENVIRONMENT="${HOME}/.venvs/infrastructure-template"
uv venv --seed "${UV_PROJECT_ENVIRONMENT}"
uv sync --all-groups

The Docker workspace already ships with an isolated seeded environment outside the bind-mounted repository tree, so the make targets remain the recommended way to run the different Pulumi-focused suites (see docker-compose.yml for the canonical workspace layout):

# Build the dev image used by the local and CI batteries
make build

# Configuration validation
make test-pulumi

# Rust-based quality gates
make test-quality

# Pulumi policy and guardrail validation
make test-policy

# Unit tests (pure Pulumi runtime with mocks)
make test-unit

# Automation-based integration tests
make test-integration

# Mutation analysis (time-consuming)
make test-mutation

Use the local batteries that match the scope of your change:

• make test runs the faster structural, policy, quality, repo-hygiene, unit, integration, coverage, and CLI battery.
• make test-security and make test-guardrails focus on infrastructure safety controls.
• make ci-pr mirrors the non-mutation GitHub pull-request battery before merge.
• make ci runs the full local superset, including the prerequisite check, image build, preview guardrails, security scans, and mutation suite.
• make report-quality generates the scheduled Wily, Vulture, docstring-coverage, and SBOM reports locally.

If Pulumi provider plugin downloads hit GitHub rate limits during local preview or drift commands, pass GITHUB_TOKEN="$(gh auth token)" explicitly to that single Make invocation instead of exporting it globally.

Run make doctor when you need a fast prerequisite check before debugging local Docker or Compose behavior.

make pulumi-preview and make pulumi-up automatically enable the repository policy pack. If the shared uv environment inside the container is missing core Pulumi Python dependencies, the bootstrap helper resyncs it from uv.lock before Pulumi starts. The policy runtime is refreshed separately in policy/.venv from policy/requirements.txt so Pulumi starts the policy pack consistently in Docker, CI, and local shells. The interactive Pulumi targets also log into the configured backend automatically, falling back to the local file backend under .pulumi-backend/ when no shared backend is configured, select the first committed Pulumi.<stack>.yaml file by default, and expect shared backends to use an AWS KMS-backed secrets provider instead of a passphrase-managed stack secret flow.

Security

Please disclose any vulnerabilities found responsibly – report security issues to the maintainers privately.