> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 로컬 서버

> 로컬 Twenty Docker 서버를 관리합니다. 시작, 중지, 업그레이드, 병렬 테스트 인스턴스 및 수동 SDK 설정을 수행할 수 있습니다.

## 로컬 서버 관리

로컬 Twenty 컨테이너를 제어하려면 `yarn twenty docker:*`를 사용하세요:

| 명령                                     | 하는 일                          |
| -------------------------------------- | ----------------------------- |
| `yarn twenty docker:start`             | 서버 시작(필요하면 이미지를 가져옴)          |
| `yarn twenty docker:start 2.2.0`       | 특정 서버 버전을 시작합니다               |
| `yarn twenty docker:start --port 3030` | 사용자 지정 포트에서 시작                |
| `yarn twenty docker:stop`              | 서버 중지(데이터 보존)                 |
| `yarn twenty docker:status`            | URL, 버전 및 로그인 자격 증명 표시        |
| `yarn twenty docker:logs`              | 서버 로그 스트리밍                    |
| `yarn twenty docker:reset`             | 데이터를 모두 삭제하고 새로 시작            |
| `yarn twenty docker:upgrade`           | `twenty-app-dev` 최신 이미지를 가져오기 |
| `yarn twenty docker:upgrade 2.2.0`     | 특정 버전으로 업그레이드합니다              |

데이터는 두 개의 Docker 볼륨에 저장되어 재시작 후에도 유지됩니다(PostgreSQL은 `twenty-app-dev-data`, 파일은 `twenty-app-dev-storage`). `reset`을 사용하여 모든 것을 삭제하세요.

## 서버 버전 고정하기

버전을 전달하지 않으면, `docker:start`는 `package.json`의 앱 `engines.twenty` 범위에서 버전을 결정합니다. 이 범위는 앱이 설치될 때 서버가 검증에 사용하는 범위와 같습니다. 이 명령은 해당 범위를 만족하는 가장 최근에 게시된 `twenty-app-dev` 이미지를 시작하며, 해당 필드가 없거나 게시된 버전이 범위와 일치하지 않으면 `latest`로 대체합니다:

```json filename="package.json" theme={null}
{
  "engines": {
    "twenty": ">=2.2.0"
  }
}
```

단일 실행에서만 범위를 재정의하려면 버전을 명시적으로 전달하세요: `yarn twenty docker:start 2.3.0`. 이미 다른 버전에서 컨테이너가 존재하는 경우, `docker:start`는 해당 컨테이너를 제자리에서 업그레이드합니다(데이터 볼륨을 유지하면서 컨테이너를 재생성).

## 서버 이미지 업그레이드

`yarn twenty docker:upgrade`는 최신 이미지를 가져와 다이제스트를 비교하고, 실제로 변경 사항이 있을 때만 컨테이너를 다시 생성합니다. 데이터 볼륨은 유지되며 — 컨테이너만 교체됩니다. 새 이미지를 가져왔고 컨테이너가 실행 중이었다면, 업그레이드는 자동으로 새 컨테이너를 시작합니다; 이후 `yarn twenty docker:start`를 실행하여 상태가 정상(healthy)이 될 때까지 기다리세요.

```bash filename="Terminal" theme={null}
yarn twenty docker:upgrade            # Latest
yarn twenty docker:upgrade 2.2.0      # Specific version
```

`yarn twenty docker:status`로 실행 중인 버전을 확인하세요(컨테이너에 포함된 `APP_VERSION`을 표시합니다).

## 병렬 테스트 인스턴스 실행

완전히 분리된 두 번째 인스턴스를 관리하려면 모든 `docker:*` 명령에 `--test`를 전달하세요 — 메인 개발 데이터를 건드리지 않고 통합 테스트를 실행하거나 실험할 때 유용합니다:

| 명령                                  | 하는 일                         |
| ----------------------------------- | ---------------------------- |
| `yarn twenty docker:start --test`   | 테스트 인스턴스를 시작합니다(기본 포트는 2021) |
| `yarn twenty docker:stop --test`    | 중지                           |
| `yarn twenty docker:status --test`  | 상태 표시                        |
| `yarn twenty docker:logs --test`    | 로그 스트리밍                      |
| `yarn twenty docker:reset --test`   | 데이터 삭제                       |
| `yarn twenty docker:upgrade --test` | 이미지 업그레이드                    |

테스트 인스턴스는 자체 컨테이너(`twenty-app-dev-test`), 전용 볼륨(`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), 구성으로 실행되며, 메인 인스턴스와 충돌 없이 나란히 실행됩니다. `--test`를 `--port`와 함께 사용하여 2021을 재정의하세요.

## 수동 설정(스캐폴더 없이)

기존 프로젝트에 SDK를 추가하는 경우 스캐폴더 단계를 건너뜁니다:

```bash filename="Terminal" theme={null}
yarn add twenty-sdk twenty-client-sdk
```

`package.json`에 스크립트를 추가하세요:

```json filename="package.json" theme={null}
{
  "scripts": {
    "twenty": "twenty"
  }
}
```

이제 `yarn twenty dev`, `yarn twenty docker:start` 등을 실행할 수 있습니다.

<Note>
  `twenty-sdk`를 전역으로 설치하지 마세요 — 각 프로젝트에 고정하여 각 앱이 자체 버전을 사용하도록 하세요.
</Note>