DEV Community

Cover image for Complete Guide to Self-Hosting Twenty CRM
Aditya Deshlahre
Aditya Deshlahre

Posted on

Complete Guide to Self-Hosting Twenty CRM

#opensource #saas #docker #tutorial

Twenty CRM is a cost-effective, open-source CRM solution that empowers businesses to manage customer relationships and sales independently by hosting the system on their own servers. This provides data privacy, customization options, and cost savings, ideal for small to medium-sized businesses.

  • Open-source CRM designed for self-hosting, giving businesses full control over customer data and processes.

  • Eliminates recurring fees, making it a cost-effective alternative to traditional CRMs.

  • Ensures data privacy and security by allowing businesses to host the CRM on their own infrastructure.

  • Provides flexibility for customization to meet specific business needs.

  • Ideal for small to medium-sized businesses to manage sales, customer interactions, and lead tracking efficiently.

Choosing Twenty CRM?

Twenty CRM is an affordable, self-hosted CRM solution that offers essential customer management and sales tools with the flexibility, control, and scalability that growing businesses need.

  • Self-hosted, budget-friendly CRM designed for small businesses and startups.

  • Provides core CRM functionalities with full control and customization options.

  • Avoids subscription fees, supporting data privacy and independence.

  • Built on an open-source framework, offering scalability as businesses expand.

  • Ideal for tailoring the platform to fit specific operational needs.

This guide will provide a step-by-step walkthrough for setting up (Self-hosting) and customizing Twenty CRM on your own infrastructure.

before that if you want a quick look at what the final self-hosted Twenty looks like. Check out this YouTube Video : )

Let's get started with self-hosting here.......

Prerequisites

Before getting started, ensure you have the following:

  • Docker Basics: Some knowledge of Docker and Docker Compose, since the setup relies on Docker containers.

  • PostgreSQL and Redis: Installed and ready on your server if not already configured.

  • Domain and SSL Certificate: A domain and SSL for secure access (optional for local testing).

  • Email Account for Notifications: An SMTP-compatible email account, such as Gmail.

  • OpenSSL: Needed for creating secure tokens.

  • Prepare the Server Environment:

    • CPU: 2+ cores
    • Memory: 4GB or more
    • Storage: SSD with at least 50GB free space
    • Operating System: Ubuntu 20.04+ or any Docker-compatible OS

Step 01: Clone & Configure Twenty CRM

  1. Clone the Repository to Server: 
git clone https://github.com/twentyhq/twenty.git

cd twenty
Enter fullscreen mode Exit fullscreen mode
  1. Download Sample Environment (.env) and Docker (docker-compose.yml) Files: 
curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/.env.example

curl -O https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/docker-compose.yml
Enter fullscreen mode Exit fullscreen mode

Step 02: Set Up Essential Environment Variables

Edit the .env file to configure connections for all services. Here are some example variables, organized by component.

Frontend Environment Variables

These variables are essential for configuring the front end of your CRM instance:

REACT_APP_SERVER_BASE_URL=http://localhost:3000       # Backend server URL
GENERATE_SOURCEMAP=false                              # Disable source maps for production
CHROMATIC_PROJECT_TOKEN=<your_chromatic_token>        # Obtain this from Chromatic for versioning UI changes
Enter fullscreen mode Exit fullscreen mode

Backend Environment Variables

Define these variables to set up database connections, server settings, and secure tokens:

PG_DATABASE_URL=postgres://user:password@localhost:5432/database    # PostgreSQL connection URL
REDIS_URL=redis://localhost:6379                                    # Redis connection URL
SERVER_URL=http://localhost:3000                                    # Base URL for the backend
ACCESS_TOKEN_SECRET=<random>                                        # Secure token for access management
CACHE_STORAGE_TTL=604800                                            # Cache TTL (7 days in seconds)
Enter fullscreen mode Exit fullscreen mode

Security Token Generation

For enhanced security, generate unique tokens for each of the following:

openssl rand -base64 32
Enter fullscreen mode Exit fullscreen mode

Use the generated strings to populate the secure token variables in .env:

ACCESS_TOKEN_SECRET=<token_1>
LOGIN_TOKEN_SECRET=<token_2>
REFRESH_TOKEN_SECRET=<token_3>
FILE_TOKEN_SECRET=<token_4>
Enter fullscreen mode Exit fullscreen mode

Step 03: Enable Messaging and Calendar Synchronization

To streamline customer engagement, set up messaging and calendar sync by scheduling these recurring tasks:

# These are commands run it on the server 
yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
Enter fullscreen mode Exit fullscreen mode

These commands will import all Gmail messages and calendar events, centralizing customer interactions in one location.

Step 04: Set Up Email Notifications and File Storage

Configure email and file storage to enable notifications and manage files effectively.

Email Configuration

Gmail is supported for email, though any SMTP-compatible provider will work:

# Edit this is .env file
EMAIL_SMTP_HOST=smtp.gmail.com 
EMAIL_SMTP_PORT=465
EMAIL_SMTP_USER=<your_email>
EMAIL_SMTP_PASSWORD=<your_app_password>
Enter fullscreen mode Exit fullscreen mode

File Storage Options

For local file storage, use these settings:

# Edit this is .env file
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=.local-storage
Enter fullscreen mode Exit fullscreen mode

For scalable storage on Amazon S3, use the following configuration:

Alternatively, you can use MinIo in the save server and configure it too

# Edit this is .env file
STORAGE_S3_REGION=us-east-1
STORAGE_S3_NAME=my-bucket
STORAGE_S3_ACCESS_KEY_ID=<access_key>
STORAGE_S3_SECRET_ACCESS_KEY=<secret_key>
Enter fullscreen mode Exit fullscreen mode

Step 05: Deploy with Docker Compose

To launch Twenty CRM, use Docker Compose:

  • Start the Docker Containers: Run Twenty CRM in detached mode: 
# This is a command to run on the server 
docker-compose up -d
Enter fullscreen mode Exit fullscreen mode
  • Verify: Access the app at http://localhost:3000. For production, update SERVER_URL to your domain in .env, then restart: 
# This is a command to run on the server 
docker-compose down && docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Step 06: Configure External Access

To make your CRM accessible over the internet, set up your domain and enable SSL. Follow these instructions:

Without a Reverse Proxy

For direct access:

# Edit this is .env file
SERVER_URL=http://your-domain-or-ip:3000
Enter fullscreen mode Exit fullscreen mode

With a Reverse Proxy

For secure HTTPS access through a reverse proxy:

# Edit this is .env file
SERVER_URL=https://your-domain-or-ip
Enter fullscreen mode Exit fullscreen mode

After updating SERVER_URL, restart the containers:

To restart the container use the below command

# This is a command to run on the server 
docker-compose down && docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Common Issues

A: Unable to Login

A frequent issue reported on Discord is the “Unable to login” error.

If you’re facing login problems, try executing the following commands:

# These are commands run it on the server 
docker exec -it twenty-server-1 yarn
docker exec -it twenty-server-1 npx nx database:reset
Enter fullscreen mode Exit fullscreen mode

After completing these steps, restart the containers with:

# These are commands run it on the server 
docker-compose down
docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

B: Connectivity Issues with a Reverse Proxy

Ensure that SERVER_URL in your .env file matches the URL for external access. Double-check that your reverse proxy settings are correctly forwarding requests to the Twenty server, then restart both the reverse proxy and Twenty containers.

C: Authentication Callback Issues

Errors often arise from misconfigurations with Google or Microsoft SSO. Verify that the callback URLs in your .env file exactly match those in your API credentials.

D: Optimizing Performance

Adjust Redis cache settings to manage higher traffic, and fine-tune PostgreSQL for improved performance.

Scaling Your Deployment

For larger setups, consider the following:

  • Load Balancing: Use tools like NGINX or HAProxy to distribute traffic across multiple instances.
  • Horizontal Scaling: Run multiple backend containers to manage higher workloads.
  • Database Replication: Configure read replicas for PostgreSQL to support high query volumes.
  • Redis Clustering: Set up Redis clusters to handle larger datasets and improve caching speed.

Extrazzzzzzzzz........

Integrating Additional Tools

Enhance Twenty CRM by integrating with third-party tools:

  • Google Analytics: Monitor CRM usage with Google Analytics.
  • Zapier: Automate workflows between Twenty CRM and other applications.
  • Slack/Webhooks: Configure webhooks for instant notifications in Slack or other platforms.

Advanced Configuration

To unlock additional capabilities, Twenty CRM supports AI integrations, telemetry, and monitoring.

Enabling AI Features

If you’re using OpenAI for customer insights, include the following in your configuration:

# Edit this is .env file
OPENAI_API_KEY=your_openai_key
Enter fullscreen mode Exit fullscreen mode

Telemetry and Error Tracking

Set up Sentry to log errors and monitor performance by adding:

# Edit this is .env file
SENTRY_DSN=https://your_key@your_project.ingest.sentry.io/your_id
SENTRY_ENVIRONMENT=production
Enter fullscreen mode Exit fullscreen mode

Conclusion

Following this guide, you should have a fully operational, self-hosted instance of Twenty CRM, equipped to manage your business's customer relationships. For additional help, consider joining Twenty's active Discord community or checking the GitHub discussions for further support and updates.

Own Your Data Happy Hosting :)

Top comments (0)

Read next

bladepipe profile image

Move Data from Oracle to ClickHouse in Minutes

BladePipe -

truongpx396 profile image

🐹 Common Design Patterns In Golang Projects 🧩

Truong Phung -

eliasfloreteng profile image

Generate SSH Keys Effortlessly with generate-ssh-key

Elias -

thinkthroo profile image

Scan for CLI flags and arguments using MRI package

thinkThroo -