---
title: "Run the same images locally with Compose · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/build-test-and-deploy/compose-for-local
id: ENG-67
level: Recommended
applies: servers
updated: 2026-10-27
build: a2a6bdfed830
tokens: 822
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Run the same images locally with Compose

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ENG-67
- Level: Recommended
- Chapter: [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy.md)
- Rule: Describe the local setup in one Compose file that uses the production images and versions, so the app runs the same way on every laptop.
- Check: On a clean machine, `docker compose up --wait` exits 0 once every service is healthy, and the database reports the same major version as production.
- Applies when: The project runs its own servers, virtual machines or containers.
- How: Build the app from the same Dockerfile, and pin every other service, such as the database, to the version production runs. Keep secrets in a local `.env` file that `.dockerignore` and version control both leave out. Use `docker compose watch` to rebuild on changes. It gives [one-command start](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/readme-sections.md) for a new person. The tool pick is in [Use Docker and Docker Compose for containers](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/docker-and-compose.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
services:
  web:
    build: .
    init: true
    read_only: true
    tmpfs: [/tmp]
    env_file: .env
    ports: ["127.0.0.1:8080:8080"]
  db:
    image: postgres:17.11-alpine
```

## Sources

- [The Twelve-Factor App, Dev/prod parity](https://12factor.net/dev-prod-parity)

## Related rules

- DOC-6 [Give the README a fixed set of sections](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/readme-sections.md) in Documentation
- STK-53 [Use Docker and Docker Compose for containers](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/docker-and-compose.md) in Software choices
- STK-100 [Avoid Kubernetes until Compose and a managed container service fall short](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/avoid-early-kubernetes.md) in Software choices

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/engineering/build-test-and-deploy/compose-for-local">Agent Wranglers engineering playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Send only the files the build needs](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/dockerignore.md)
- Next: [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release.md)
- [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy.md)