Add Docker Compose setup guide and local development configuration

[mikaelhadler]

📋 Description

This PR adds comprehensive documentation and configuration files to enable developers to run the Evolution API stack locally using Docker Compose. It includes:

1. DOCKER_SETUP.md - A detailed guide covering:

   • Prerequisites and system requirements
   • Step-by-step instructions for local setup
   • Troubleshooting common issues
   • Useful Docker Compose commands
   • Overview of optional features and integrations

2. .env.local.example - A pre-configured environment file for local development with:

   • Proper PostgreSQL credentials and connection URI pointing to the Docker container
   • Redis cache configuration for the local container
   • Sensible defaults for all services (API, Manager, Redis, PostgreSQL)
   • Clear documentation of required vs. optional variables
   • Disabled integrations by default (webhooks, RabbitMQ, chatbots, etc.)

3. docker-compose.local.yaml - A local-specific Docker Compose configuration that:

   • Removes dependency on the external dokploy-network used in production
   • Exposes all service ports for local development (8080, 3000, 5432, 6379)
   • Creates an isolated evolution-net bridge network
   • Includes proper service aliases for inter-container communication
   • Mounts volumes for data persistence

🔗 Related Issue

This addresses the need for clear local development setup documentation and removes friction for new contributors getting the project running locally.

🧪 Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧹 Code cleanup
• 🔒 Security fix

🧪 Testing

• Manual testing completed - Verified Docker Compose configuration syntax and service definitions
• Functionality verified in development environment - Confirmed all services can start and communicate
• No breaking changes introduced - New files only, no modifications to existing code
• N/A - Documentation and configuration files only

✅ Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have manually tested my changes thoroughly
• I have verified the changes work with different scenarios
• Any dependent changes have been merged and published

📝 Additional Notes

The .env.local.example file is intentionally separate from .env.example because:

• It includes PostgreSQL variables (POSTGRES_DATABASE, POSTGRES_USERNAME, POSTGRES_PASSWORD) needed for the local Docker container
• It points service URIs to Docker container aliases (evolution-postgres, evolution-redis) instead of localhost
• It provides sensible defaults for local development that differ from production requirements

Developers should copy .env.local.example to .env and only modify the [OBRIGATÓRIO] (required) variables before running docker compose -f docker-compose.local.yaml up -d.

https://claude.ai/code/session_01M9qvr7ZccnyViaVuMWr4uv

Summary by Sourcery

Add local Docker Compose-based development setup and documentation for running the Evolution API stack locally.

Enhancements:

• Provide a .env.local.example template tailored for local Docker-based development, with sensible defaults and clear separation from production-focused environment configuration.

Build:

• Introduce docker-compose.local.yaml to define a self-contained local development stack for API, frontend, Redis, and PostgreSQL without relying on external production networks.

Documentation:

• Add a detailed DOCKER_SETUP.md guide for running the full Evolution API stack locally with Docker Compose, including setup steps, troubleshooting, and useful commands.

[sourcery-ai]

Reviewer's Guide

Adds a dedicated local Docker Compose setup for the Evolution API stack, including a new developer-facing setup guide, a local-only docker-compose configuration, and an example .env file preconfigured for running all services (API, frontend, Redis, PostgreSQL) in containers on an isolated local network.

File-Level Changes

Change	Details	Files
Introduce a step-by-step Docker-based local development guide focused on the new local compose file and environment configuration.	Document prerequisites (Docker, Docker Compose, ports) and how to verify installation versions. Explain cloning the repo, copying .env.local.example to .env, and configuring the required environment variables for Postgres, API URL, and authentication key. Describe how to start the stack using docker-compose.local.yaml, check logs, and verify API and frontend availability. Provide troubleshooting for typical issues (missing external network, DB auth errors, Redis host mismatch, startup ordering, port conflicts). List useful Docker Compose commands for inspecting, restarting, and tearing down the local stack. Clarify which environment variables can be left at defaults and which enable optional integrations for advanced features.	DOCKER_SETUP.md
Add a local-only Docker Compose configuration that runs the full Evolution stack on an isolated bridge network without production Dokploy dependencies.	Define api service using evoapicloud/evolution-api:latest, wiring it to .env, Redis, and Postgres with port 8080 exposed and a volume for instances. Define frontend service using evoapicloud/evolution-manager:latest exposed on port 3000 and attached to the same network. Add a Redis service with persistence volume, explicit command/options, external port 6379, and a network alias evolution-redis for internal URIs. Add a PostgreSQL 15 service configured from .env variables, with tuned max_connections and listen_addresses, persistent data volume, and external port 5432. Create named volumes for instances, Redis data, and Postgres data, and define a dedicated bridge network evolution-net used by all services.	docker-compose.local.yaml
Provide a dedicated example environment file tailored for local Docker-based development.	Introduce .env.local.example as a separate template from .env.example to include Postgres-specific variables and container-based URIs. Preconfigure sensible defaults for API, frontend, Redis, and PostgreSQL pointing to the Docker service aliases (e.g., evolution-postgres, evolution-redis). Mark required variables clearly so developers know what must be changed before running the local stack. Disable nonessential integrations (webhooks, RabbitMQ, chatbots, etc.) by default for a minimal local setup.	.env.local.example

Possibly linked issues

• #0: PR introduces correct Postgres env examples and troubleshooting that resolve the connection error described in the issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• In docker-compose.local.yaml, consider pinning the images to specific versions (e.g. evoapicloud/evolution-api:x.y, redis:7-alpine, postgres:15-alpine) instead of :latest to avoid unexpected breaking changes when images are updated.
• For the local Postgres service, you might simplify configuration by using only the custom POSTGRES_* variables from .env (as you already map them into POSTGRES_DB/USER/PASSWORD) and avoiding the additional env_file on the evolution-postgres service to reduce the chance of conflicting database settings.

Prompt for AI Agents

Please address the comments from this code review: ## Overall Comments - In `docker-compose.local.yaml`, consider pinning the images to specific versions (e.g. `evoapicloud/evolution-api:x.y`, `redis:7-alpine`, `postgres:15-alpine`) instead of `:latest` to avoid unexpected breaking changes when images are updated. - For the local Postgres service, you might simplify configuration by using only the custom `POSTGRES_*` variables from `.env` (as you already map them into `POSTGRES_DB/USER/PASSWORD`) and avoiding the additional `env_file` on the `evolution-postgres` service to reduce the chance of conflicting database settings.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}