Codakey
Play
← Back to twenty

How to Deploy & Use twenty

Twenty CRM: Deployment and Usage Guide

1. Prerequisites

Before installing Twenty, ensure you have the following installed on your system:

Runtime & Tools:

  • Node.js (v18 or later) - JavaScript runtime
  • npm or yarn - Package manager (npm is recommended)
  • Docker and Docker Compose - For containerized deployment
  • PostgreSQL (v14+) - Primary database
  • Redis - For caching and background jobs

Development Tools (for local setup):

  • Git - Version control
  • TypeScript knowledge - The project is built with TypeScript
  • Nx - Build system used by the project (installed via npm)

Accounts (Optional):

  • Google Cloud or AWS accounts for cloud deployment
  • Email service provider (SendGrid, AWS SES, etc.) for email features
  • Storage provider (AWS S3, Google Cloud Storage) for file attachments

2. Installation

Option A: Local Development Setup

# Clone the repository
git clone https://github.com/twentyhq/twenty.git
cd twenty

# Install dependencies
npm install

# Install Nx CLI globally (if not already installed)
npm install -g nx

Option B: Docker Compose (Self-hosting)

# Clone the repository
git clone https://github.com/twentyhq/twenty.git
cd twenty

# Copy environment template
cp .env.example .env

# Start with Docker Compose
docker-compose up -d

3. Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Database Configuration
DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=twenty
DATABASE_PASSWORD=your_secure_password
DATABASE_NAME=twenty_db

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

# Application Configuration
NODE_ENV=production
PORT=3000
API_URL=http://localhost:3000
FRONT_BASE_URL=http://localhost:3001

# Security
JWT_SECRET=your_jwt_secret_key_here
ENCRYPTION_KEY=your_encryption_key_here

# Email (Optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password

# Storage (Optional)
STORAGE_TYPE=local # or 's3', 'gcs'
AWS_S3_BUCKET_NAME=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# OpenAPI Configuration (for API documentation)
OPENAPI_ENABLED=true

Database Setup

For local development, you can use the included Docker setup or install PostgreSQL manually:

# Using Docker
docker run --name twenty-postgres \
  -e POSTGRES_USER=twenty \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e POSTGRES_DB=twenty_db \
  -p 5432:5432 \
  -d postgres:14

# Run migrations
npm run migration:run

4. Build & Run

Development Mode

# Start the development server (frontend + backend)
npm run dev

# Or run separately:
# Backend server
npm run start:server:dev

# Frontend application
npm run start:front:dev

The application will be available at:

Production Build

# Build both frontend and backend
npm run build

# Build specific parts
npm run build:server
npm run build:front

# Start production server
npm run start:prod

Using Nx Commands

Since Twenty uses Nx monorepo structure, you can also use Nx commands:

# Run specific applications
nx serve twenty-server
nx serve twenty-front

# Build specific applications
nx build twenty-server
nx build twenty-front

# Run tests
nx test twenty-server
nx test twenty-front

5. Deployment

Platform Recommendations

Based on the TypeScript/Node.js stack with PostgreSQL and Redis:

Recommended Platforms:

  1. Railway - Excellent for full-stack TypeScript applications with built-in PostgreSQL
  2. Render - Simple deployment with managed databases
  3. AWS (ECS/EKS) - For enterprise-scale deployments
  4. DigitalOcean App Platform - Simple PaaS with managed databases
  5. Docker Swarm/Kubernetes - For container orchestration

Docker Deployment

# Build Docker images
docker build -t twenty-server ./packages/twenty-server
docker build -t twenty-front ./packages/twenty-front

# Or using docker-compose for production
docker-compose -f docker-compose.prod.yml up -d

Railway Deployment Example

# Install Railway CLI
npm i -g @railway/cli

# Link your project
railway link

# Set environment variables
railway variables set DATABASE_URL=postgresql://...

# Deploy
railway up

Environment-Specific Configuration

For production, ensure you:

  1. Set NODE_ENV=production
  2. Use strong, unique secrets for JWT_SECRET and ENCRYPTION_KEY
  3. Configure proper CORS settings
  4. Set up SSL/TLS certificates
  5. Configure database connection pooling
  6. Set up proper logging and monitoring

6. Troubleshooting

Common Issues and Solutions

1. Database Connection Issues

# Check if PostgreSQL is running
psql -h localhost -U twenty -d twenty_db

# Reset database (development only)
npm run migration:reset

2. Build Failures

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules
npm install

# Check TypeScript compilation
npm run type-check

3. Docker Compose Issues

# Check container status
docker-compose ps

# View logs
docker-compose logs -f twenty-server

# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up -d

4. Memory Issues

  • Increase Node.js memory limit: NODE_OPTIONS="--max-old-space-size=4096"
  • Configure Redis memory policy in redis.conf
  • Monitor PostgreSQL connection limits

5. Migration Errors

# View migration status
npm run migration:show

# Revert last migration
npm run migration:revert

# Generate new migration
npm run migration:generate --name=MigrationName

6. API Issues

7. Frontend Rendering Issues

# Clear browser cache
# Check browser console for errors
# Verify API endpoints are accessible

Getting Help

Monitoring

For production deployments, monitor:

  • Database connection pool usage
  • Redis memory usage
  • API response times
  • Error rates in logs
  • Background job queue lengths
← Project overviewView alternatives to twenty →