Self-Hosting & Docker
Relevant source files
The following files were used as context for generating this wiki page:
Twenty is designed to be a highly customizable CRM that can be run on a team's own infrastructure. The project provides multiple pathways for self-hosting, primarily centering around Docker containers for standard deployments and Kubernetes (via Helm) for orchestrated environments. This architecture ensures that teams can build, ship, and version their CRM in the same way they manage the rest of their software stack.
Sources: README.md:16-18, README.md:43-45
Deployment Architectures
Twenty supports several self-hosting strategies. While Docker Compose is the standard method supported by the core team, community-maintained Kubernetes and Podman configurations are also available.
Container Orchestration Overview
The system relies on a multi-container architecture to separate concerns between the user interface, API services, and background processing.
The diagram shows the standard flow where a load balancer or ingress controller routes traffic to the frontend and backend services, which share state via PostgreSQL and Redis.
Sources: CLAUDE.md:120-125, packages/twenty-docker/k8s/README.md:1-4
Supported Platforms
| Platform | Support Level | Primary Tools |
|---|---|---|
| Docker Compose | Core Team Supported | docker-compose.yml |
| Kubernetes | Community Maintained | Helm 3, Terraform |
| Podman | Community Maintained | Podman CLI |
| Local / Dev | Core Team Supported | setup-dev-env.sh |
Sources: packages/twenty-docker/k8s/README.md:1-5, CLAUDE.md:143-150
Configuration & Environment
Self-hosting Twenty requires the configuration of several key infrastructure components. The backend architecture is built on NestJS and TypeORM, necessitating a specific set of supporting services.
Core Dependencies
- PostgreSQL: The primary relational database for workspace data, metadata, and object definitions.
- Redis: Utilized for caching, session management, and as a message broker for BullMQ.
- Worker Node: A dedicated background job processing instance using BullMQ.
Sources: CLAUDE.md:120-128, CLAUDE.md:133-134
Key Environment Variables and Secrets
For secure deployment, particularly in Kubernetes, specific tokens must be generated and stored as secrets.
# Example: Creating Kubernetes secrets for tokens
kubectl create secret generic -n twentycrm tokens \
--from-literal accessToken=changeme \
--from-literal loginToken="changeme" \
--from-literal refreshToken="changeme" \
--from-literal fileToken="changeme"
Sources: packages/twenty-docker/k8s/README.md:65-67
Deployment Procedures
Docker Development Environment
For developers looking to contribute or test locally, Twenty provides a unified setup script that manages infrastructure via Docker.
# Start Postgres + Redis via Docker and initialize schema
bash packages/twenty-utils/setup-dev-env.sh --docker
The --docker flag forces Docker mode, utilizing packages/twenty-docker/docker-compose.dev.yml to spin up necessary services.
Sources: CLAUDE.md:143-152
Kubernetes via Helm
The recommended community method for Kubernetes deployment is through the Helm chart.
This sequence illustrates the automated deployment of the full Twenty stack into a Kubernetes namespace.
Sources: packages/twenty-docker/k8s/README.md:17-25
Installation Steps (Helm)
- Namespace Setup: Create a dedicated namespace (e.g.,
twentycrm). - Ingress Configuration: Define the host domain and TLS settings.
- Execution: Run the
helm installcommand with necessary overrides.
Sources: packages/twenty-docker/k8s/README.md:18-25
Troubleshooting & Maintenance
Maintenance for self-hosted instances involves managing migrations and inspecting logs.
Database Operations
When self-hosting, schema changes are handled via instance commands.
- Reset:
npx nx database:reset twenty-server - Initialize:
npx nx run twenty-server:database:init:prod - Migrate:
npx nx run twenty-server:database:migrate:prod
Sources: CLAUDE.md:85-88
Logs and Inspection
- Kubernetes: Use
kubectl logsto inspect specific pod output. - Docker: Logs are typically accessed via
docker-compose logs. - Database Inspection: A read-only Postgres MCP server can be used to verify migration results and explore the multi-tenant schema structure.
Sources: packages/twenty-docker/k8s/README.md:95-97, CLAUDE.md:96-102
Self-hosting Twenty provides full control over the CRM data and infrastructure, allowing for deep customization through the Twenty SDK while maintaining the security and compliance requirements of the host organization.
Sources: README.md:16-18, packages/twenty-codex-plugin/skills/develop-app/SKILL.md:13-20