Welcome to the Evo CRM Community Installation Guide - Documentação do Evolution Foundation

Evo CRM Community is the free, open-source edition of Evo CRM. You install everything on your own server — your data stays with you, no monthly fees and no usage limits. The platform consists of 5 services that work together:

Service	What it does	Port
`evo-auth-service-community`	Handles login and access permissions	3001
`evo-ai-crm-community`	Manages conversations, contacts, and inboxes	3000
`evo-ai-frontend-community`	The visual interface you use in the browser	5173
`evo-ai-processor-community`	Runs AI agents	8000
`evo-ai-core-service-community`	Manages agents, folders, and API keys	5555

This edition has no global admin panel, billing plans, or multi-tenancy support. It’s simple by design.

Before You Start

You’ll need three tools installed on your machine:

Docker and Docker Compose — create and manage the containers where each service runs. Click here to install
Git — downloads the project code. Click here to install
make — simplifies the execution of long commands. Usually pre-installed on Linux and macOS. Click here to install

Step by Step

Step 1 — Download the project

Open your terminal and run:

git clone --recurse-submodules [email protected]:evolution-foundation/evo-crm-community.git
cd evo-crm-community

This command downloads the main repository and all the services that make up the platform at once.

If you already cloned the repository without the --recurse-submodules flag, run this command to download the missing services:

git submodule update --init --recursive

Step 2 — Update services to the latest version

git submodule update --remote --merge

This ensures each service is on the latest available version. Do this whenever you want to update the platform.

Step 3 — Choose where your database will run

Before configuring .env, decide where the database will be hosted. There are three options:

Option A — Docker (default, recommended to start)

Nothing to do. Docker Compose already spins up a PostgreSQL automatically. Skip straight to Step 4.

Option B — PostgreSQL installed locally

Prefer to install PostgreSQL directly on your machine? Use version 16 or higher with the pgVector extension enabled.

System	How to install
Linux	Official Linux guide
macOS	Postgres.app — the simplest way
Windows	Official installer

After installing, enable pgVector in the database:

CREATE EXTENSION IF NOT EXISTS vector;

Option C — Cloud database

You can also use a managed service. See the compatible options:

Provider	Native pgVector	Official documentation
Supabase	✅	supabase.com/docs/…/pgvector
Neon	✅	neon.tech/docs/…/pgvector
AWS RDS	✅	docs.aws.amazon.com/…/PostgreSQL.ExtensionsAndModules
Google Cloud SQL	✅	cloud.google.com/sql/docs/…/extensions
Azure PostgreSQL	✅	learn.microsoft.com/…/how-to-use-pgvector
Railway	✅	docs.railway.app/databases/postgresql

If you chose Option B or C, after creating the database, adjust these 5 variables in .env (Step 4):

DB_HOST=localhost       # Database server address
DB_PORT=5432            # Default PostgreSQL port
DB_NAME=evo_crm         # Name of the database you created
DB_USER=your_user       # Database user
DB_PASSWORD=your_pass   # Database password

Evo CRM Community is not compatible with MySQL, MariaDB, or SQLite. Always use PostgreSQL 16 or higher with the pgVector extension enabled.

Step 4 — Configure environment variables

cp .env.example .env

This creates the .env file from a ready-made template. Open it with any text editor and adjust the settings to match your environment. If you went with Option A (Docker), the default values already work. No changes needed for now.

Step 5 — Run setup

make setup

This single command takes care of everything, in the right order:

Builds Docker images for all services
Starts the database and waits for it to be ready
Creates tables and populates initial data
Starts all services

On the first run, this process can take 15 to 20 minutes. Docker needs to download and compile all the images. Next time it will be much faster.

Step 6 — Access the platform

When setup finishes, open your browser and go to:

http://localhost:5173

The platform is ready to use.

Available services

Interface	Address
Frontend	`http://localhost:5173`
CRM API	`http://localhost:3000`
Auth API	`http://localhost:3001`
Processor API	`http://localhost:8000`
Core API	`http://localhost:5555`
Mailhog (email)	`http://localhost:8025`

Day-to-day commands

After setup, use these commands to manage the platform:

Command	What it does
`make start`	Starts all services
`make stop`	Stops all services
`make restart`	Restarts all services
`make status`	Shows which containers are running
`make logs`	Shows logs from all services in real time
`make logs SERVICE=name`	Filters logs for a specific service (e.g. `SERVICE=evo-crm`)
`make build`	Rebuilds all images from scratch (no cache)
`make seed`	Re-populates the initial database data
`make shell-auth`	Opens a terminal inside the Auth container
`make shell-crm`	Opens a terminal inside the CRM container
`make shell-core`	Opens a terminal inside the Core container
`make shell-processor`	Opens a terminal inside the Processor container
`make clean`	Stops everything and permanently deletes all data

make clean is irreversible. It removes the database, cache, and all generated files. Use it only if you want to start from scratch.

Next steps

Getting Started

Access the platform for the first time and set up your account

Configure Channels

Connect WhatsApp, email, Telegram, and other channels

Configure AI Agents

Create and configure your AI support agents

Environment Variables

Complete reference of all available variables

Need help?

GitHub: evolution-foundation/evo-crm-community
Community: evolutionfoundation.com.br/community
Issues: Found a problem? Open an issue in the corresponding service repository

​Before You Start

​Step by Step

​Step 1 — Download the project

​Step 2 — Update services to the latest version

​Step 3 — Choose where your database will run

​Option A — Docker (default, recommended to start)

​Option B — PostgreSQL installed locally

​Option C — Cloud database

​Step 4 — Configure environment variables

​Step 5 — Run setup

​Step 6 — Access the platform

​Available services

​Day-to-day commands

​Next steps

Getting Started

Configure Channels

Configure AI Agents

Environment Variables

​Need help?

Before You Start

Step by Step

Step 1 — Download the project

Step 2 — Update services to the latest version

Step 3 — Choose where your database will run

Option A — Docker (default, recommended to start)

Option B — PostgreSQL installed locally

Option C — Cloud database

Step 4 — Configure environment variables

Step 5 — Run setup

Step 6 — Access the platform

Available services

Day-to-day commands

Next steps

Need help?