Quick Start

Get MediaMagic CRM running locally in under 5 minutes.

1. Clone the Repository

git clone https://github.com/AmericanMedia/crm.git
cd crm

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

Minimal Setup

# Required for basic functionality
MYSQL_ROOT_PASSWORD=your_secure_password
MYSQL_PASSWORD=your_mysql_password
ESPOCRM_ADMIN_PASSWORD=your_admin_password
POSTGRES_PASSWORD=your_postgres_password
GRAFANA_ADMIN_PASSWORD=your_grafana_password

Full Setup

# MySQL (EspoCRM database)
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_PASSWORD=your_mysql_password

# EspoCRM
ESPOCRM_ADMIN_USER=admin
ESPOCRM_ADMIN_PASSWORD=your_admin_password
ESPOCRM_SITE_URL=http://localhost:8080
ESPOCRM_API_KEY=your_api_key_after_setup

# PostgreSQL (Analytics)
POSTGRES_PASSWORD=your_postgres_password

# Grafana
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=your_grafana_password

# Ayrshare
AYRSHARE_API_KEY=your_ayrshare_api_key

# X Server
X_SERVER_URL=http://your-x-server:3001

# n8n
N8N_WEBHOOK_BASE=https://your-n8n-instance.com

3. Start Services

docker compose up -d

This starts all services:

4. Wait for Initialization

First run takes 2-3 minutes for EspoCRM to initialize:

docker compose logs -f espocrm

Look for: EspoCRM is ready

5. Set Up Custom Entities

cd espocrm/custom
npm install
ESPOCRM_URL=http://localhost:8080 \
ESPOCRM_ADMIN_USER=admin \
ESPOCRM_ADMIN_PASSWORD=your_password \
node setup-entities.js

6. Configure Navigation

1. Open http://localhost:8080
2. Log in with your admin credentials
3. Go to Admin → User Interface → Tab List
4. Add custom entities to the navigation
5. Save

7. Create API User

1. Go to Admin → API Users
2. Create a new API user with admin role
3. Copy the API key
4. Add to your .env as ESPOCRM_API_KEY
5. Restart the bridge:

docker compose restart bridge

8. Verify Everything Works

Health Check

curl http://localhost:3100/health

Expected Response

{
  "ok": true,
  "service": "mediamagic-bridge",
  "timestamp": "2026-02-05T12:00:00.000Z"
}

🎉 You're Ready!

Access your services:

Service	URL	Credentials
EspoCRM	localhost:8080	Admin user from .env
Grafana	localhost:3200	admin / password from .env
Bridge API	localhost:3100	—

Next Steps

• Configure external integrations
• Learn the data model
• Set up publishing workflows
• Deploy to production

Troubleshooting

EspoCRM not starting?

Check MySQL is healthy:

docker compose logs espocrm-mysql

Ensure MySQL is ready before EspoCRM starts.

Need to start fresh?

# Stop everything
docker compose down

# Remove volumes (⚠️ deletes all data)
docker volume rm crm_mysql-data crm_espocrm-data crm_grafana-data crm_postgres-data

# Start fresh
docker compose up -d

Webhooks not working?

• Verify webhook URLs in Admin → Webhooks
• Check Bridge logs: docker compose logs bridge
• Ensure Bridge container can reach EspoCRM