Choosing a local development environment is less about finding a universal winner than matching the tool to your project, team, and deployment workflow. This guide compares Docker Compose, VS Code Dev Containers, and DDEV, provides reproducible starter templates, and gives you a maintenance routine for keeping local environments aligned with CI and production.
Overview
Local development environments solve a familiar problem: two developers check out the same repository but receive different results because their operating systems, runtimes, databases, extensions, or environment variables differ. Containers can reduce that variation, but the best approach depends on how much control your team needs and which workflow developers already use.
Docker Compose is a flexible foundation for defining several services, such as an application, database, cache, and mail testing service. It is usually the best starting point when your team needs explicit control over service topology or wants a setup that can map closely to container-based CI.
VS Code Dev Containers adds a development-container layer to an editor-centered workflow. It can describe the tools, extensions, ports, and commands expected inside a container, while allowing developers to open the repository in a consistent environment. It commonly works alongside Docker Compose rather than replacing it.
DDEV is a higher-level development tool designed to simplify common web stacks. It can be especially convenient for projects built with established PHP-based frameworks or content management systems, where a team values a guided workflow over manually defining every container detail.
| Consideration | Docker Compose | VS Code Dev Containers | DDEV |
|---|---|---|---|
| Setup complexity | Moderate; you define services and integration details. | Moderate; easiest when paired with an existing Compose file. | Often lower for supported web stacks; conventions reduce configuration. |
| Reproducibility | Strong when images, dependencies, and environment variables are pinned deliberately. | Strong for the editor and toolchain; application services may still come from Compose. | Strong when project configuration and required versions are committed. |
| Cross-platform support | Good, but file sharing, permissions, and resource settings need testing. | Good for teams using compatible editors and container tooling. | Good when the supported stack matches the project and host requirements. |
| CI parity | Usually the most direct path to container-oriented CI configuration. | Useful for developer tooling, but CI normally needs a separate non-editor definition. | Can support consistent project commands, but CI integration should be designed explicitly. |
| Debugging ergonomics | Flexible, though you may configure debugging, ports, and processes yourself. | Convenient inside VS Code when launch and debug settings are committed. | Convenient for supported workflows, with fewer low-level decisions. |
| Performance considerations | Depends on filesystem mounts, image size, and host container implementation. | Shares the underlying container performance characteristics. | Shares the underlying container performance characteristics and tool conventions. |
Use Compose when infrastructure definition is the priority, Dev Containers when the in-editor experience is the priority, and DDEV when its conventions closely match your application. A combined approach is valid: Compose can define services while a Dev Container defines the application workspace.
What to track
A reproducible environment is more than a container file. Track the inputs that affect a developer’s result, and keep them visible in version control.
- Runtime versions: Record the language runtime, package manager, database, cache, and supporting service versions. Prefer explicit image tags or version files over undocumented local defaults.
- Startup commands: Document one clear path from clone to running application. Include dependency installation, database initialization, migrations, and seed data where appropriate.
- Configuration: Commit safe defaults in an example environment file. Keep secrets out of the repository and explain which values must be supplied locally.
- Ports and service names: Choose predictable names and ports, then document conflicts and override options. A developer should not need to inspect several files to find the application URL.
- Persistent data: State which volumes are disposable and which contain local data that should survive a restart. Provide a reset command for cases where a clean database is needed.
- Quality checks: Make formatting, tests, linting, and type checking available through the same project commands used by CI wherever practical.
Template 1: Docker Compose
This minimal template describes an application and database. Adjust the image, command, and health check to your framework rather than treating these values as universal defaults.
services:
app:
build:
context: .
dockerfile: Dockerfile
working_dir: /workspace
volumes:
- .:/workspace
ports:
- "3000:3000"
environment:
DATABASE_URL: postgresql://app:app@db:5432/app
depends_on:
db:
condition: service_healthy
db:
image: postgres:VERSION
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: app
POSTGRES_DB: app
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 5s
retries: 10
volumes:
db-data:
The named volume keeps database data separate from the application checkout. The placeholder VERSION is intentional: select and document a version compatible with your application, then review it during upgrades. Add a README.md with commands such as docker compose up --build, migration instructions, and the approved reset procedure.
Template 2: VS Code Dev Container
Use this when the team wants a defined editor workspace. The dockerComposeFile points to the Compose services, while service identifies the container in which developers work.
{
"name": "project-workspace",
"dockerComposeFile": "../compose.yaml",
"service": "app",
"workspaceFolder": "/workspace",
"forwardPorts": [3000, 5432],
"customizations": {
"vscode": {
"extensions": [
"REPLACE_WITH_REQUIRED_EXTENSION"
]
}
},
"postCreateCommand": "REPLACE_WITH_INSTALL_OR_SETUP_COMMAND",
"remoteUser": "REPLACE_WITH_CONTAINER_USER"
}
Keep the extension list short and purposeful. A post-create command should be safe to run for every new workspace; avoid putting destructive database resets there. If your image already contains dependencies, make that choice explicit so developers know whether a rebuild or an install command is required after changing the lockfile.
Template 3: DDEV
DDEV projects commonly keep configuration under .ddev/. A practical starter workflow is to initialize the project with the DDEV command appropriate to the application type, commit the generated configuration, and add only the project-specific changes your team understands.
# Example workflow; choose values for your project
ddev config --project-type=REPLACE_WITH_PROJECT_TYPE --docroot=REPLACE_WITH_DOCROOT
ddev start
ddev composer install
# Run the framework's migration or setup command
ddev launch
For a DDEV template, commit the resulting project configuration, record the expected DDEV and runtime compatibility in the README, and document commands for importing a database, rebuilding configuration, and stopping or resetting the project. Do not assume that a generated configuration is self-explanatory; annotate non-default settings.
Cadence and checkpoints
Review the environment quarterly, and review it sooner when a runtime, framework, container tool, editor integration, or CI image changes. The goal is not to upgrade everything on a fixed date. The goal is to detect drift before it becomes an onboarding or release problem.
At each quarterly review
- Check the versions declared in Dockerfiles, Compose files, Dev Container metadata, DDEV configuration, package manifests, and lockfiles.
- Build the environment from a clean checkout on at least two supported host setups when possible.
- Run the same install, migration, test, lint, and development commands documented for new contributors.
- Compare local commands with CI commands. If they differ, document why or reduce the difference.
- Test the reset path: remove disposable volumes or caches, recreate the services, and verify that the documented recovery steps work.
- Record changes in a short maintenance note, including any compatibility decision that should guide the next review.
For onboarding, treat the first successful setup by a new teammate as a checkpoint. Capture where they needed clarification. Repeated questions about ports, permissions, missing tools, or database state usually indicate documentation or automation gaps rather than user error.
How to interpret changes
Not every difference requires changing tools. First identify the type of drift. A failed image build points to dependency or base-image changes. A service that starts but cannot connect may indicate network names, ports, credentials, or startup ordering. Slow file watching may be a host filesystem or mount issue rather than an application defect. A test that passes locally but fails in CI deserves comparison of runtime versions, environment variables, generated files, and service readiness.
Use a simple decision rule:
- If the project has several dependent services or needs infrastructure-level control, favor Compose as the source of service truth.
- If setup works but developers lack consistent tools, commands, or editor integration, add a Dev Container layer.
- If the application fits DDEV’s supported conventions and the team wants fewer low-level configuration decisions, evaluate DDEV before building a custom stack.
- If performance problems are host-specific, measure the affected workflow before migrating tools. Compare dependency installation, file watching, test execution, and database operations separately.
Keep the decision reversible. Separate application configuration from local convenience settings, avoid hidden global dependencies, and make the fallback manual commands clear. A team should be able to replace one environment layer without rewriting the application.
When to revisit
Revisit this comparison and your templates at least once every three months, after a major Docker, VS Code, DDEV, operating system, runtime, or framework change, and whenever CI begins failing for reasons that cannot be reproduced locally. Also review the setup when the project adopts a new framework such as Next.js, Rails, Laravel, or Astro, because its recommended development workflow may change the balance between a custom Compose stack and a higher-level tool.
Before an upgrade, create a small checklist: record the current versions, create a clean checkout, run the baseline commands, update one variable at a time, rebuild without relying on old caches, and repeat the checks. Keep the old setup instructions available until the team has completed the migration. Afterward, update the template, README, troubleshooting notes, and CI configuration together.
For the next review, start with these actions:
- Choose Compose, Dev Containers, DDEV, or a documented combination as the team’s supported path.
- Commit one minimal template and a README with clone-to-running instructions.
- Pin or clearly declare the versions that matter, including placeholders where a project must choose its own value.
- Test clean setup, normal development, debugging, tests, and reset behavior.
- Set a calendar reminder for the next quarterly review and note the events that should trigger an earlier check.
A local environment is successful when a new developer can reproduce the project’s normal workflow and an existing developer can upgrade it without guesswork. Treat the configuration as maintained developer tooling, not as a one-time setup file.