オープンソースCRM「Twenty」のローカル開発環境を構築してみた

エニークラウドで、オープンソースのCRM「Twenty」を触りはじめました。手元で自由に動かして中身を見たいので、まずはローカル開発環境を構築しました。

この記事では、構築の手順と実測時間、ハマりどころをまとめます。

Twentyとは

Twenty は「#1 Open-Source CRM」を掲げるオープンソースのCRMで、GitHubスターは約5万です。SalesforceやHubSpotの代替を狙うプロダクトの中では、現時点でもっとも勢いのあるOSSのひとつだと思います。

技術スタックはTypeScriptで統一されたモノレポで、フロントエンドがReact、バックエンドがNestJS、データベースがPostgreSQL、キャッシュがRedisです。定義したオブジェクトはGraphQLとRESTの両APIに自動で公開されます。

ライセンスは本体がAGPL-3.0で、セルフホストなら無料・ユーザー数無制限で使えます。

前提環境

構築に使ったマシンはApple SiliconのMacです。必要なものは次の通りです。

PostgreSQLとRedisはHomebrewでも立てられますが、リポジトリにDocker用のMakefileが同梱されているので、今回はそちらを使いました。

手順

1. clone — とにかく大きい

git clone https://github.com/twentyhq/twenty.git
cd twenty

リポジトリはclone後で1.6GB、作業ファイル約26,000個あります。手元の環境では完了まで7分40秒かかりました。

所要時間は回線次第で大きく変わる部分なので、履歴が不要なら --filter=blob:none のpartial cloneで短縮できます。

2. Nodeとyarnの準備

.nvmrc にNodeのバージョンが書かれているので、それに合わせます。

nvm use            # 24.16.0 に切り替え(未インストールなら nvm install)
corepack enable    # yarn 4 を有効化
yarn -v            # 4.13.0

package.json のenginesに "npm": "please-use-yarn" と書かれている通り、npmでは動きません。yarn 4はcorepack経由で入るので、手動でのインストールは不要でした。

3. PostgreSQLとRedisをDockerで起動

リポジトリ同梱のMakefileターゲットを叩くだけです。

make -C packages/twenty-docker postgres-on-docker
make -C packages/twenty-docker redis-on-docker

postgres:16のコンテナ起動に加えて、default と test のデータベース作成、起動完了の待機までMakefileが面倒を見てくれます。イメージのpullを含めて2〜3分でした。

ポートは5432(PostgreSQL)、6379(Redis)、3000(サーバー)、3001(フロント)を使います。既存の開発環境と衝突しやすい番号なので、起動前に確認しておくと安全です。

lsof -nP -iTCP:5432 -iTCP:6379 -iTCP:3000 -iTCP:3001 -sTCP:LISTEN

4. .envの準備

.env.example をコピーして、APP_SECRET だけランダム値に差し替えます。

cp packages/twenty-front/.env.example packages/twenty-front/.env
cp packages/twenty-server/.env.example packages/twenty-server/.env
sed -i '' "s|APP_SECRET=replace_me_with_a_random_string|APP_SECRET=$(openssl rand -base64 32)|" packages/twenty-server/.env

.env.example の中身がlocalhostのPostgreSQL/Redisを指すローカル開発向けデフォルトになっているので、書き換えはこの1箇所で済みました。

5. yarn install — 大量のwarningが出るが正常

yarn install

実測で2分24秒でした。このとき YN0004: ... lists build scripts, but all build scripts have been disabled というwarningが大量に出ます。

一見エラーに見えますが、Twentyが .yarnrc.yml で依存パッケージのビルドスクリプトをデフォルト無効化しているためのもので、正常な挙動です。サプライチェーン攻撃への対策として意図的にこの設定になっています。

6. DB初期化と起動

npx nx database:reset twenty-server   # マイグレーション + シードデータ投入
npx nx start                          # サーバー + ワーカー + フロントを一括起動

DB初期化は1分45秒、起動してからフロントとサーバーが応答するまでは1分弱でした。

動作確認

http://localhost:3001 を開くとログイン画面が表示されます。

開発用の .env では SIGN_IN_PREFILLED=true が設定されており、シードユーザーの tim@apple.dev(パスワードも同じ)が最初から入力されています。そのままサインインするとCRM画面に入れます。

シードデータとして599社の企業データが投入済みで、People・Opportunities・Tasks・Workflowsといった主要オブジェクトも一通り触れる状態です。GraphQL APIも http://localhost:3000/graphql で応答することを確認できました。

予想と違った点

一番意外だったのは、ログイン画面が最初から日本語で表示されたことです。Twentyはi18n対応済みで、ブラウザのロケールに追従します。海外製のOSSは英語UIを覚悟していたので、初回起動から日本語で使い始められるのは嬉しい誤算でした。

もうひとつは環境構築体験の洗練度です。所要時間の実測は次の通りで、cloneを除けば合計約10分でした。

DB作成まで面倒を見るMakefile、コピーするだけで動く .env.example、ログイン情報のプリフィルなど、開発者が最初につまずくポイントが先回りして潰されています。モノレポは20パッケージある大規模なものですが、体験としては軽快でした。

おわりに

環境構築は「cloneが重い」以外に大きなハマりどころがなく、Twentyの開発体験の良さを感じる結果になりました。

ここから実際のCRMとしての使い勝手やカスタマイズ性を見ていきます。試してわかったことは、またこのブログで紹介する予定です。