로컬 설정

콘트리뷰터(기여자)나 호기심 많은 개발자를 위한 가이드로서, Twenty를 로컬에서 실행하고자 하는 분들에게 드리는 안내입니다.

​

사전 준비

리눅스 및 맥OS

Twenty를 설치하고 사용하기 전에, 먼저 컴퓨터에 다음을 설치하세요:

• Git
• Node v24.5.0
• yarn v4
• nvm

npm은 사용할 수 없으며, 대신 yarn을 사용해야 합니다. Yarn은 이제 Node.js와 함께 제공되기 때문에 별도로 설치할 필요가 없습니다. 아직 하지 않았다면 corepack enable을 실행하여 Yarn을 사용할 수 있도록 설정하세요.

윈도우 (WSL)

1. WSL 설치 PowerShell을 관리자 권한으로 열고 다음을 실행하세요:

wsl --install

이제 컴퓨터를 재시작하라는 프롬프트가 나타날 것입니다. 그렇지 않으면 수동으로 재시작하세요.

재시작 후, powershell 창이 열리고 Ubuntu가 설치됩니다. 이 작업은 다소 시간이 걸릴 수 있습니다. Ubuntu 설치 시 사용자 이름과 암호를 만드는 프롬프트가 나타납니다.

2. Git 설치 및 구성

sudo apt-get install git

git config --global user.name "Your Name"

git config --global user.email "[e-mail]"

3. nvm, node.js 및 yarn 설치

적절한 node 버전을 설치하기 위해 nvm을 사용하세요. .nvmrc는 모든 기여자가 동일한 버전을 사용하도록 보장합니다.

sudo apt-get install curl

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

nvm을 사용하려면 터미널을 닫았다가 다시 여세요. 그런 다음 다음 명령어를 실행하세요.

nvm install # installs recommended node version

nvm use # use recommended node version

corepack enable

---

​

1단계: Git 복제

터미널에서 다음 명령어를 실행하세요.

SSH (권장)

아직 SSH 키를 설정하지 않은 경우, 여기를 참조하여 설정하는 방법을 배우세요.

git clone [e-mail]:twentyhq/twenty.git

HTTPS

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

​

2단계: 루트 위치 설정

cd twenty

다음 단계의 모든 명령어는 프로젝트 루트에서 실행하세요.

​

3단계: PostgreSQL 데이터베이스 설정

리눅스

옵션 1 (권장): 데이터베이스를 로컬에서 프로비저닝하려면: Linux 기기에 Postgresql을 설치하려면 다음 링크를 사용하십시오: Postgresql 설치

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

참고: 권한 오류를 피하기 위해 psql 명령어 앞에 sudo -u postgres를 추가해야 할 수 있습니다.

옵션 2: 도커가 설치된 경우:

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

맥 OS

옵션 1 (권장): brew로 로컬에서 데이터베이스를 프로비저닝하려면:

  brew install postgresql@16
  export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
  brew services start postgresql@16
  psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"

PostgreSQL 서버가 실행 중인지 확인하려면 다음을 실행하세요:

  brew services list

설치 시 기본적으로 postgres 사용자가 생성되지 않을 수 있습니다. macOS에서 Homebrew로 설치할 경우, 설치 시스템 계정과 일치하는 PostgreSQL 역할이 생성됩니다(예: “john”). 대신 사용자의 macOS 사용자 이름(예: “john”)과 일치하는 PostgreSQL 역할을 생성합니다.# PostgreSQL 접속psql postgres 또는 psql -U $(whoami) -d postgres

  # Connect to PostgreSQL
  psql postgres
  or
  psql -U $(whoami) -d postgres

psql 프롬프트에서(postgres=#), 다음을 실행하세요:

 # List existing PostgreSQL roles
 \du

출력은 다음과 비슷해야 합니다:

 Role name | Attributes  | Member of
 -----------+-------------+-----------
 john      | Superuser   | {}

postgres 역할이 나열되지 않으면 다음 단계를 계속하십시오. postgres 역할을 수동으로 만드세요:

 CREATE ROLE postgres WITH SUPERUSER LOGIN;

이는 로그인 액세스가 있는 슈퍼유저 역할 postgres를 생성합니다.

역할 이름 | 속성  | 소속
-----------+-------------+-----------
postgres  | 슈퍼유저   | {}
john      | 슈퍼유저   | {}

옵션 2: 도커가 설치된 경우:

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

윈도우 (WSL)

다음 단계는 모두 WSL 터미널(가상 머신 내)에서 실행됩니다.

옵션 1: Postgresql을 로컬에서 프로비저닝하려면: Linux 가상 머신에 Postgresql을 설치하려면 다음 링크를 사용하세요: Postgresql 설치

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

참고: 권한 오류를 피하기 위해 psql 명령어 앞에 sudo -u postgres를 추가해야 할 수 있습니다.

옵션 2: 도커가 설치된 경우: WSL에서 Docker를 실행하면 추가적인 복잡성이 발생합니다. 이 옵션은 Docker Desktop WSL2를 켠 상태에서의 추가 설정 단계를 수반할 수 있다는 점에서 편안할 때만 사용하십시오.

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

이제 localhost:5432에서 데이터베이스에 액세스할 수 있으며, 사용자 postgres와 비밀번호 postgres 를 사용합니다.

​

4단계: Redis 데이터베이스 (캐시) 설정

Twenty는 최상의 성능을 제공하기 위해 redis 캐시가 필요합니다.

리눅스

옵션 1: Redis를 로컬에서 프로비저닝하려면: 리눅스 기기에 Redis를 설치하려면 다음 링크를 사용하십시오: Redis 설치

옵션 2: 도커가 설치된 경우:

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

맥 OS

옵션 1 (권장): brew로 Redis를 로컬에서 프로비저닝하려면:

brew install redis

redis 서버를 시작하세요: brew services start redis

옵션 2: 도커가 설치된 경우:

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

윈도우 (WSL)

옵션 1: Redis를 로컬에서 프로비저닝하려면: Linux 가상 머신에 Redis를 설치하려면 다음 링크를 사용하세요: Redis 설치

옵션 2: 도커가 설치된 경우:

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

클라이언트 GUI가 필요한 경우에는 redis insight (무료 버전 제공)을 권장합니다.

​

5단계: 환경 변수 설정

프로젝트를 구성하기 위해 환경 변수나 .env 파일을 사용하세요. 자세한 내용은 여기에서 확인하세요.

/front와 /server의 .env.example 파일을 복사하세요:

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

멀티 워크스페이스 모드: 기본적으로 Twenty는 하나의 워크스페이스만 생성할 수 있는 단일 워크스페이스 모드로 실행됩니다. 멀티 워크스페이스 지원을 활성화하려면(서브도메인 기반 기능을 테스트할 때 유용합니다), 서버의 .env 파일에서 IS_MULTIWORKSPACE_ENABLED=true로 설정하세요. 자세한 내용은 멀티 워크스페이스 모드를 참조하세요.

​

6단계: 의존성 설치

Twenty 서버를 빌드하고 데이터베이스에 몇 가지 데이터를 시드하기 위해, 다음 명령어를 실행하세요:

yarn

npm이나 pnpm은 작동하지 않음을 주의하세요.

​

7단계: 프로젝트 실행

리눅스

리눅스 배포판에 따라 Redis 서버가 자동으로 시작될 수 있습니다. 시작되지 않는다면, 각 배포판에 맞는 Redis 설치 가이드를 확인하세요.

맥 OS

Redis가 이미 실행 중이어야 합니다. 그렇지 않으면 다음을 실행하세요:

brew services start redis

윈도우 (WSL)

리눅스 배포판에 따라 Redis 서버가 자동으로 시작될 수 있습니다. 시작되지 않는다면, 각 배포판에 맞는 Redis 설치 가이드를 확인하세요.

다음 명령어로 데이터베이스를 설정하세요:

npx nx database:reset twenty-server

서버, 워커 및 프론트엔드 서비스를 시작하세요:

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

또한, 모든 서비스를 한 번에 시작할 수도 있습니다:

npx nx start

​

8단계: Twenty 사용하기

프론트엔드

Twenty의 프론트엔드는 http://localhost:3001에서 실행됩니다. 기본 데모 계정을 사용하여 로그인할 수 있습니다: [e-mail] (비밀번호: [e-mail])

백엔드

• Twenty의 서버는 http://localhost:3000에서 실행됩니다.
• GraphQL API는 http://localhost:3000/graphql에서 액세스할 수 있습니다
• REST API는 http://localhost:3000/rest에서 액세스할 수 있습니다

​

문제 해결

문제가 발생하면 문제 해결에서 해결책을 확인하십시오.