Twenty CRM Local Setup and Docker Deployment Guide for Developers

Twenty is a flexible, open-source CRM that allows you to customize views using filters, sorting, groups, Kanban boards, and tables. You can define your own custom objects and fields, manage permissions through tailored roles, and automate workflows with specific triggers and actions. The platform also natively handles email, calendar events, files, and more.

The technical stack is built on TypeScript, Nx, and NestJS with BullMQ, utilizing PostgreSQL and Redis for storage and messaging. The front end is powered by React, Recoil, Emotion, and Lingui.

To maintain high standards, Twenty integrates several third-party services into its development lifecycle: Chromatic for UI testing, Greptile for code reviews, Sentry for error tracking, and Crowdin for localized translations.

If you are a developer looking to run Twenty on your local machine, follow the steps below.

Prerequisites

For development on Linux, macOS, or Windows (WSL), you will need Git, Node v22, Yarn v4, and nvm.

Note: Use Yarn instead of npm. Node.js typically includes Yarn; if it is not active on your system, run corepack enable to set it up.

Step 1: Clone the Repository

Clone the project using your terminal. SSH is the recommended method:

git clone [email protected]:twentyhq/twenty.git

If you have not configured SSH keys, use the HTTPS URL instead.

Step 2: Navigate to the Project Root

cd twenty

All subsequent commands should be executed from within this directory.

Step 3: Configure PostgreSQL

There are two primary ways to set up the database on Linux, macOS, or Windows (WSL):

• Option 1 (Recommended): Install PostgreSQL directly on your operating system. Refer to the official PostgreSQL documentation for your specific OS. Once installed, initialize the databases:

  psql postgres -c "CREATE DATABASE "default";" -c "CREATE DATABASE test;"

If you encounter permission issues, prefix the command with sudo -u postgres.

• Option 2: If you prefer using Docker, run:

  make postgres-on-docker

The database will be accessible at localhost:5432 with the username postgres and password postgres.

Step 4: Configure Redis (Caching)

Twenty requires Redis to handle performance-critical tasks. You have two options:

• Option 1: Install and run Redis locally on your host machine.

• Option 2: Use Docker by running:

  make redis-on-docker

To inspect your data, you can use a GUI like Redis Insight (which offers a free tier).

Step 5: Initialize Environment Variables

Duplicate the example .env files for both the front-end and server packages:

cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env

Step 6: Install Dependencies

Execute the following command to install required packages, build the server, and seed the database:

yarn

Avoid using npm or pnpm for this process.

Step 7: Launch the Application

Ensure Redis is running before proceeding. On some systems, it starts automatically; otherwise, check your distribution's service manager.

First, reset the database to a clean state:

npx nx database:reset twenty-server

Then, start the server, worker, and front end in separate terminal sessions:

npx nx start twenty-server
npx nx worker twenty-server
npx nx start twenty-front

Alternatively, you can launch all components simultaneously with:

npx nx start

Step 8: Access Twenty

• Front end: Accessible at http://localhost:3001. Use the demo credentials: [email protected] / [email protected].
• Back end: The server runs at http://localhost:3000. You can access the GraphQL playground at http://localhost:3000/graphql and REST endpoints at http://localhost:3000/rest.

Refer to the troubleshooting documentation if you encounter errors during the startup process.

Deployment with Docker Compose

Using Docker containers is the standard approach for production hosting or self-hosting. Follow these steps to configure Twenty with Docker Compose.

System Requirements

• Memory: A minimum of 2GB of RAM is required to prevent processes from crashing.
• Docker: Ensure both Docker and Docker Compose are installed and updated to their latest versions.

Option 1: Automatic One-Line Installation

You can pull and start the latest stable version with a single command:

bash <(curl -sL https://git.new/20)

To use a specific release or development branch:

VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://git.new/20)

Replace vx.y.z with your desired version and branch-name with the appropriate branch.

Option 2: Manual Installation

1. Configure the Environment File

Create your .env file from the repository example:

curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example

Generate a secure secret token:

openssl rand -base64 32

Open the .env file and replace the APP_SECRET placeholder with your generated string:

APP_SECRET=your_random_string

Additionally, set a strong password for the database (avoiding special characters that might break connection strings):

PGPASSWORD_SUPERUSER=your_secure_password

2. Download the Docker Compose File

Download the official configuration:

curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml

3. Start the Services

docker compose up -d

4. Access the Application

The interface will be available at http://localhost:3000.

Configuration for External Access

By default, the application is configured for local access on port 3000. For external access, you must define the SERVER_URL variable in your .env file.

Defining SERVER_URL

• Protocol: Use http or https. Note that https is required for certain browser features like the clipboard API and secure cookie handling.
• Domain/IP: The public address used to access the CRM.
• Port: Include the port number if you are not using standard ports (80 or 443).

SSL Requirements

Features such as the "copy to clipboard" buttons often fail in non-secure contexts. For production environments, it is highly recommended to run Twenty behind a reverse proxy (such as Nginx or Caddy) that handles SSL termination.

Setting the URL

• Direct Access (No Proxy): SERVER_URL=http://your-domain-or-ip:3000

• Via Reverse Proxy (Standard HTTPS): SERVER_URL=https://your-domain-or-ip

• Via Reverse Proxy (Custom Port): SERVER_URL=https://your-domain-or-ip:custom-port

After updating the .env file, restart the containers:

docker compose down
docker compose up -d

Additional Deployment Notes

• Reverse Proxy: Ensure your proxy forwards requests to internal port 3000 and passes the necessary headers (e.g., X-Forwarded-For).
• Firewall: Open the required ports on your server to allow incoming traffic.
• Consistency: The SERVER_URL must exactly match the URL accessed by users to prevent redirection issues.

Data Persistence

The provided Docker Compose configuration uses volumes to ensure your database and uploaded files remain intact when containers are restarted or updated. If you are deploying to a stateless environment, you will need to configure Twenty to point to external persistent storage or a managed database service.