# Twenty CRM

> Modern open-source CRM with a beautiful interface, Salesforce alternative.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: twenty, twenty-worker, postgresql, redis
- Tags: crm, sales, twenty, salesforce-alternative, business
- Source: https://docker.recipes/productivity/twenty-crm

## Overview

Twenty is a modern, open-source Customer Relationship Management (CRM) platform designed as a powerful alternative to Salesforce and other proprietary CRM solutions. Built with a focus on user experience and developer-friendly architecture, Twenty offers a clean, intuitive interface while providing the flexibility to customize objects, fields, and workflows to match specific business needs. The platform emphasizes modern web technologies and GraphQL APIs, making it highly extensible for developers who need to integrate CRM functionality into their existing systems.

This Docker deployment creates a complete Twenty CRM environment using four specialized containers: the main Twenty application server, a dedicated worker container for background job processing, a PostgreSQL database for persistent data storage, and Redis for caching and session management. The worker container runs the same Twenty image but executes background tasks like email processing, data synchronization, and scheduled operations, ensuring the main application remains responsive under heavy loads.

This configuration is ideal for businesses seeking a self-hosted CRM solution with enterprise-grade features but without the complexity of cloud vendor lock-in. Sales teams, marketing departments, and customer success organizations can benefit from Twenty's modern interface and customization capabilities, while IT teams appreciate the containerized deployment that can be easily scaled, backed up, and integrated into existing infrastructure management workflows.

## Features

- Custom object and field creation with flexible data modeling beyond standard CRM entities
- GraphQL API with full schema introspection for seamless third-party integrations
- Dedicated background worker processing for email campaigns, data imports, and scheduled tasks
- Modern React-based interface with real-time updates and collaborative editing features
- Local file storage system with configurable paths for document and attachment management
- JWT-based authentication with separate token secrets for access, login, refresh, and file operations
- PostgreSQL-powered data integrity with support for complex queries and reporting
- Redis-backed session management and caching for improved application performance

## Use cases

- Small to medium businesses replacing Salesforce or HubSpot with a self-hosted alternative
- Sales teams needing custom pipeline stages and deal tracking with specific business logic
- Marketing departments managing lead nurturing campaigns with custom contact properties
- Customer success teams tracking account health and renewal opportunities with tailored dashboards
- Development teams building integrated business applications that need embedded CRM functionality
- Organizations with strict data privacy requirements needing on-premises CRM deployment
- Consultancies and agencies managing multiple client relationships with custom project tracking fields

## Prerequisites

- Docker and Docker Compose installed with at least 2GB RAM available for the complete stack
- Port 3000 available for the Twenty web interface and API access
- Environment variables configured for database password and JWT token secrets
- Basic understanding of CRM concepts like contacts, companies, deals, and sales pipelines
- Familiarity with PostgreSQL for database maintenance and backup procedures
- Knowledge of Redis caching concepts for performance optimization and troubleshooting

## docker-compose.yml

```yaml
services:
  twenty:
    image: twentycrm/twenty:latest
    container_name: twenty
    environment:
      - SERVER_URL=${SERVER_URL}
      - FRONT_BASE_URL=${FRONT_URL}
      - PG_DATABASE_URL=postgres://twenty:${DB_PASSWORD}@db:5432/twenty
      - REDIS_URL=redis://redis:6379
      - STORAGE_TYPE=local
      - STORAGE_LOCAL_PATH=/app/docker-data
      - ACCESS_TOKEN_SECRET=${ACCESS_TOKEN_SECRET}
      - LOGIN_TOKEN_SECRET=${LOGIN_TOKEN_SECRET}
      - REFRESH_TOKEN_SECRET=${REFRESH_TOKEN_SECRET}
      - FILE_TOKEN_SECRET=${FILE_TOKEN_SECRET}
    volumes:
      - twenty-data:/app/docker-data
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    networks:
      - twenty-network
    restart: unless-stopped

  worker:
    image: twentycrm/twenty:latest
    container_name: twenty-worker
    command: ["yarn", "worker:prod"]
    environment:
      - PG_DATABASE_URL=postgres://twenty:${DB_PASSWORD}@db:5432/twenty
      - REDIS_URL=redis://redis:6379
      - STORAGE_TYPE=local
      - STORAGE_LOCAL_PATH=/app/docker-data
      - ACCESS_TOKEN_SECRET=${ACCESS_TOKEN_SECRET}
      - LOGIN_TOKEN_SECRET=${LOGIN_TOKEN_SECRET}
      - REFRESH_TOKEN_SECRET=${REFRESH_TOKEN_SECRET}
    volumes:
      - twenty-data:/app/docker-data
    depends_on:
      - twenty
    networks:
      - twenty-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: twenty-db
    environment:
      - POSTGRES_USER=twenty
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=twenty
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - twenty-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: twenty-redis
    volumes:
      - redis-data:/data
    networks:
      - twenty-network
    restart: unless-stopped

volumes:
  twenty-data:
  postgres-data:
  redis-data:

networks:
  twenty-network:
    driver: bridge
```

## .env

```bash
# Twenty CRM
SERVER_URL=http://localhost:3000
FRONT_URL=http://localhost:3000
DB_PASSWORD=secure_twenty_password

# Generate each with: openssl rand -base64 32
ACCESS_TOKEN_SECRET=your_access_token_secret
LOGIN_TOKEN_SECRET=your_login_token_secret
REFRESH_TOKEN_SECRET=your_refresh_token_secret
FILE_TOKEN_SECRET=your_file_token_secret
```

## Usage notes

- Web UI at http://localhost:3000
- Create first workspace
- Modern Salesforce alternative
- Custom objects and fields
- GraphQL API available

## Troubleshooting

- Twenty container failing to start with database connection errors: Verify DB_PASSWORD environment variable matches between twenty and db services, and ensure PostgreSQL container is fully initialized before Twenty starts
- GraphQL API returning 500 errors on queries: Check that all four JWT token secrets (ACCESS_TOKEN_SECRET, LOGIN_TOKEN_SECRET, REFRESH_TOKEN_SECRET, FILE_TOKEN_SECRET) are set and consistent between twenty and worker containers
- Background jobs not processing in worker container: Ensure Redis container is running and accessible, verify REDIS_URL environment variable format is redis://redis:6379 in worker service
- File uploads failing with storage errors: Check that twenty-data volume is properly mounted and STORAGE_LOCAL_PATH=/app/docker-data is correctly configured in both twenty and worker services
- Performance issues with large datasets: Monitor PostgreSQL memory usage and consider increasing shared_buffers, verify Redis memory limits are appropriate for your session and cache requirements
- Twenty web interface not loading after container restart: Ensure SERVER_URL and FRONT_BASE_URL environment variables match your actual domain/IP configuration and are accessible from client browsers

