How do I standardize local dev environments across engineers?

To standardize local dev environments across engineers, aim for one reproducible setup that works the same on every laptop, with as little manual setup as possible.

Recommended approach

1) Use containerized dev environments

Put the app, dependencies, and tooling in a Dev Container or equivalent:

• Docker + docker compose
• VS Code Dev Containers
• GitHub Codespaces if cloud-based is acceptable

This gives you:

• Same language/runtime versions
• Same system packages
• Same database/cache services
• Fewer “works on my machine” issues

2) Pin every version

Lock down all important versions:

• Language runtime: Node/Python/Ruby/Java/etc.
• Package manager versions
• OS-level dependencies
• Database versions
• CLI tools

Use:

• Dockerfile for runtime
• .tool-versions for asdf
• .nvmrc, pyproject.toml, Gemfile.lock, package-lock.json, etc.
• A Makefile or task runner for common commands

3) Provide one setup command

Engineers should be able to run something like:

make setup
make test
make dev

or

./scripts/bootstrap

This script should:

• Install prerequisites
• Pull dependencies
• Start local services
• Run migrations/seed data
• Verify everything is healthy

4) Define local services in code

Use docker compose for dependencies like:

• PostgreSQL/MySQL
• Redis
• Kafka
• Elasticsearch
• S3-compatible storage

Don’t rely on engineers manually installing these.

5) Make configuration explicit

Use environment variables, but standardize them with:

• .env.example
• documented defaults
• validation at startup

Avoid hidden config in local machine state.

6) Automate onboarding

New engineer should be able to:

1. Clone repo
2. Install one or two required tools
3. Run one setup command
4. Start coding

Create a short onboarding doc with:

• prerequisites
• setup steps
• common issues
• how to reset the environment

7) Add checks in CI to match local dev

CI should use the same images/build steps as local dev so drift is detected early.

Good practice:

• build the same container in CI
• run tests from the same environment
• fail if lockfiles or generated code are out of date

8) Standardize editor and linting setup

Include repo-level config for:

• formatter
• linter
• pre-commit hooks
• VS Code settings or .editorconfig

This reduces differences in style and saves time.

---

Best-practice stack

A common, effective setup is:

• Dockerfile for the app runtime
• docker compose for dependencies
• Dev Containers for consistent editor integration
• Makefile for common commands
• Lockfiles for dependencies
• .env.example for config
• CI uses same container as local dev

---

Example structure

repo/
  .devcontainer/
    devcontainer.json
  docker/
    Dockerfile
  docker-compose.yml
  Makefile
  .env.example
  .editorconfig
  package-lock.json
  README.md
  scripts/
    bootstrap

---

Common pitfalls

Avoid:

• letting people install dependencies manually
• relying on “latest” tags
• mixing host-installed and container-installed tools
• undocumented environment variables
• too many setup options
• different commands for local vs CI

---

If you want the shortest path

If your team is small, do this first:

1. Dockerize the app
2. Add docker compose for services
3. Create make setup/dev/test
4. Add .env.example
5. Use lockfiles and pinned versions
6. Make CI use the same environment

---

If you want, I can also give you:

• a sample devcontainer + docker compose setup
• a standard onboarding checklist
• or a decision matrix for choosing between Docker, asdf, and Codespaces.