> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ko/web-games.md).

# 웹 게임(JS/TS) - 시작하기

Edgegap에서 첫 JavaScript 또는 TypeScript 전용 서버를 배포하세요. 최소한의 Node.js 템플릿, 업로드, 그리고 브라우저 멀티플레이어 게임을 위한 전 세계 배포를 다루는 실습 가이드입니다.

실습하며 배우고 Edgegap에서 첫 전용 서버를 배포하세요. 이 가이드가 끝날 때쯤이면 비용 없이 Edgegap으로 전용 서버를 배포하게 됩니다.

{% hint style="info" %}
**이 가이드는 최소한의 Node.js WebSocket 서버 템플릿을 사용합니다**, 브라우저 게임 클라이언트라면 무엇이든 작동합니다 - Three.js, Babylon.js, PlayCanvas, Phaser, 또는 직접 만든 엔진도 가능합니다. Colyseus 같은 프레임워크로 빌드한 서버나 Bun 및 Deno에서 실행되는 서버도 같은 단계를 따릅니다.
{% endhint %}

## ✔️ 준비

시작하기 전에, 반드시 [Edgegap에서 무료 계정을 생성하세요](https://app.edgegap.com/auth/register) (신용카드 정보는 필요하지 않습니다). 다음을 할 수 있습니다 [그 후 팀원을 초대할 수 있습니다](https://app.edgegap.com/user-settings?tab=organizations), 아직 Edgegap 계정이 없어도 됩니다.

**개발 환경에서 몇 가지 필수 항목을 구성하세요:**

<details>

<summary><a href="https://nodejs.org/en/download">Node.js 22 이상 설치</a></summary>

* [공식 소스에서 Node.js를 설치하세요](https://nodejs.org/en/download), 최신 LTS 릴리스를 권장합니다.
* 다음 명령을 실행하여 설치를 확인하세요 `node -v` 를 명령줄에서.

</details>

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Docker Desktop(또는 Docker CLI) 설치</a></summary>

* [공식 소스에서 Docker Desktop을 설치하세요](https://www.docker.com/products/docker-desktop/) (계정이 필요하지 않습니다).
* 설치를 완료한 후 컴퓨터를 다시 시작하세요.

</details>

{% hint style="info" %}
**서버 빌드에 자신 있으신가요?** 다음으로 건너뛰기 [#customize-image](#customize-image "mention") 또는 [고급 기능](https://docs.edgegap.com/ko/learn/advanced-features.md) 을 더 보려면.
{% endhint %}

## ⚙️ 1. 계정 연결

JavaScript 서버에는 엔진 플러그인이 필요하지 않습니다. 명령줄과 우리의 [대시보드](https://app.edgegap.com/) 를 사용해 서버를 빌드, 업로드, 배포할 수 있습니다.

☑️ 대시보드에 로그인한 뒤 [컨테이너 레지스트리](https://app.edgegap.com/registry-management/repositories/list). 다음을 메모하세요 **프로젝트 이름** 과 **레지스트리 자격 증명** (사용자 이름과 토큰)은 다음 단계에서 필요합니다.

☑️ 로그인하세요 [Edgegap의 컨테이너 레지스트리](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md) 에 Docker로 로그인하고, 레지스트리 프로젝트 이름, 사용자 이름, 토큰을 사용하세요:

{% tabs %}
{% tab title="Bash (리눅스)" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell (윈도우)" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

☑️ 다음이 보이는지 확인하세요 `로그인 성공` 를 명령줄에서.

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🔧 2. 게임 서버 빌드

Windows, Mac, Linux 중 어떤 기계를 사용하든, **서버는 Linux 런타임에서 실행됩니다**, 대부분의 클라우드 제공업체(Edgegap 포함)가 현재 Linux에서 실행되기 때문입니다. 좋은 소식 - JavaScript는 크로스 플랫폼이므로 교차 컴파일할 것이 없으며, 다음 단계에서 Docker가 Linux용 종속성을 설치합니다.

☑️ **서버용 새 폴더를 두 개의 파일과 함께 만드세요.** 이 최소 템플릿은 WebSocket 연결을 받아 모든 메시지를 연결된 모든 플레이어에게 전달합니다. 나중에 이 전달 부분을 게임 로직으로 바꾸세요.

{% tabs %}
{% tab title="TypeScript - node.js 22.18+ (권장)" %}
{% hint style="info" %}
Node.js 22.18+는 TypeScript 파일을 직접 실행합니다(어노테이션 제거), 빌드 단계가 필요 없습니다.
{% endhint %}

1. 다음의 `server.ts` 템플릿을 프로젝트에 복사하세요(이미 있는 경우 제외):<br>

   <pre class="language-javascript" data-title="server.ts" data-expandable="true" data-collapsed-line-count="10"><code class="lang-javascript">import http from 'node:http'
   import { WebSocketServer } from 'ws'
   import { DeploymentEnvironment } from '@edgegap/sdk'

   const port = Number(process.env.PORT ?? 7777)
   const deployment = process.env.ARBITRIUM_REQUEST_ID ? DeploymentEnvironment.fromEnv(process.env) : null

   const server = http.createServer((_request: http.IncomingMessage, response: http.ServerResponse) => response.end('ok\n'))
   const wss = new WebSocketServer({ server })

   wss.on('connection', (socket) => {
     console.log(`player connected (${wss.clients.size} online)`)
     socket.on('message', (data) => {
       for (const client of wss.clients) client.send(data.toString())
     })
     socket.on('close', () => console.log(`player left (${wss.clients.size} online)`))
   })

   server.listen(port, '0.0.0.0', () => {
     console.log(`listening on 0.0.0.0:${port}`)
     console.log(deployment ? `deployment ${deployment.requestId} in ${deployment.location?.city}` : 'running locally')
   })

   process.on('SIGTERM', () => {
     for (const client of wss.clients) client.close(1001, 'server stopping')
     server.close(() => process.exit(0))
   })
   </code></pre>
2. 다음의 `package.json` 프로젝트에 추가하세요(또는 기존 파일과 병합하세요).<br>

   <pre class="language-json" data-title="package.json" data-expandable="true" data-collapsed-line-count="10"><code class="lang-json">{
     "name": "my-game-server",
     "private": true,
     "type": "module",
     "engines": {
       "node": ">=22"
     },
     "scripts": {
       "start": "node server.ts"
     },
     "dependencies": {
       "@edgegap/sdk": "^1.1.0",
       "ws": "^8.18.3"
     }
   }
   </code></pre>
3. 에디터용 타입 정의를 설치하세요:<br>

   <pre class="language-bash" data-collapsed-line-count="10"><code class="lang-bash">npm install --save-dev @types/node @types/ws
   </code></pre>

{% hint style="warning" %}
**타입 제거는 제거 가능한 구문만 지원합니다.** 피하세요 `enum`, `namespace`, 그리고 생성자 매개변수 속성, 또는 [서버를 번들링하세요](#customize-image).
{% endhint %}
{% endtab %}

{% tab title="JavaScript(이전 node.js)" %}

1. 다음의 `server.js` 템플릿을 프로젝트에 복사하세요(이미 있는 경우 제외):<br>

   <pre class="language-javascript" data-title="server.js" data-expandable="true" data-collapsed-line-count="10"><code class="lang-javascript">import http from 'node:http'
   import { WebSocketServer } from 'ws'
   import { DeploymentEnvironment } from '@edgegap/sdk'

   const port = Number(process.env.PORT ?? 7777)
   const deployment = process.env.ARBITRIUM_REQUEST_ID ? DeploymentEnvironment.fromEnv(process.env) : null

   const server = http.createServer((_request, response) => response.end('ok\n'))
   const wss = new WebSocketServer({ server })

   wss.on('connection', (socket) => {
     console.log(`player connected (${wss.clients.size} online)`)
     socket.on('message', (data) => {
       for (const client of wss.clients) client.send(data.toString())
     })
     socket.on('close', () => console.log(`player left (${wss.clients.size} online)`))
   })

   server.listen(port, '0.0.0.0', () => {
     console.log(`listening on 0.0.0.0:${port}`)
     console.log(deployment ? `deployment ${deployment.requestId} in ${deployment.location?.city}` : 'running locally')
   })

   process.on('SIGTERM', () => {
     for (const client of wss.clients) client.close(1001, 'server stopping')
     server.close(() => process.exit(0))
   })
   </code></pre>
2. 다음의 `package.json` 프로젝트에 추가하세요(또는 기존 파일과 병합하세요).<br>

   <pre class="language-json" data-title="package.json" data-expandable="true" data-collapsed-line-count="10"><code class="lang-json">{
     "name": "my-game-server",
     "private": true,
     "type": "module",
     "engines": {
       "node": ">=22"
     },
     "scripts": {
       "start": "node server.js"
     },
     "dependencies": {
       "@edgegap/sdk": "^1.1.0",
       "ws": "^8.18.3"
     }
   }
   </code></pre>

{% endtab %}
{% endtabs %}

{% hint style="success" %}
`@edgegap/sdk` 는 선택 사항이며, 이 템플릿은 이를 사용해 [주입된 변수](#injected-variables) Edgegap에서. 우리의 [JavaScript SDK](https://docs.edgegap.com/ko/web-games/matchmaking.md) 를 사용해 [#session-automation](#session-automation "mention"), 또는 서드파티 매치메이커를 추가하세요.
{% endhint %}

☑️ 종속성을 설치하고 서버를 로컬에서 시작하세요:

{% code collapsedlinecount="10" %}

```bash
npm install
npm start
```

{% endcode %}

☑️ 다음이 보이는지 확인하세요 `0.0.0.0:7777에서 수신 대기 중` 과 `로컬에서 실행 중` 를 콘솔에서 확인한 뒤, 다음 명령으로 서버를 종료하세요 `Ctrl+C`.

{% hint style="success" %}
서버 빌드는 주소 `0.0.0.0` 와 포트 `7777`를 사용해야 합니다. 포트를 사용자 지정한 경우, 다음 항목에도 같은 값을 지정하세요 [앱 및 버전](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) 한 뒤에 [#id-5.-upload-to-edgegap](#id-5.-upload-to-edgegap "mention").
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🐋 3. 서버 컨테이너화

개발자 팀과 함께 작업하면 코드를 공유해야 합니다. 문제가 발생했을 때 듣고 싶은 마지막 말은 “내 환경에서는 잘 돼”일 것입니다. 게임 서버는 전 세계 수천 대의 서버 머신에서 안정적으로 실행되어야 합니다.

서버를 안정적으로 만들기 위해 Docker를 사용합니다 - 운영 체제 수준까지 서버 코드의 모든 종속성이 어디서 어떻게 서버가 시작되든 항상 정확히 동일하도록 보장하는 가상화 소프트웨어입니다.

{% hint style="info" %}
시청을 권장합니다 ["로컬에 설치하지 마세요" (비디오)](https://www.youtube.com/watch?v=J0NuOlA2xDc\&ab_channel=Coderized). **Docker를 사용할 때 Dockerhub를 사용할 필요는 없습니다**Docker ≠ Dockerhub. Docker를 프로그래밍 엔진으로 보고 Dockerhub를 앱 스토어로 생각하세요.
{% endhint %}

☑️ 먼저 다음을 실행하세요 `docker version` 를 명령줄에서 실행해 완료했는지 확인하세요 [#preparation](#preparation "mention").

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Docker Desktop(또는 Docker CLI) 설치</a></summary>

* [공식 소스에서 Docker Desktop을 설치하세요](https://www.docker.com/products/docker-desktop/) (계정이 필요하지 않습니다).
* 설치를 완료한 후 컴퓨터를 다시 시작하세요.

</details>

☑️ **Dockerfile과 `.dockerignore` 파일을 서버 폴더에 추가하세요**, 이미지의 레시피입니다:

{% tabs %}
{% tab title="TypeScript - node.js 22.18+ (권장)" %}
{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.ts ./
USER node
CMD ["node", "server.ts"]
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript(이전 node.js)" %}
{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./
USER node
CMD ["node", "server.js"]
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% code title=".dockerignore" collapsedlinecount="10" %}

```
node_modules
.git
*.md
```

{% endcode %}

{% hint style="info" %}
**서버를 다음으로 시작하세요 `node`, 아닌 `npm start`.** Edgegap은 `SIGTERM` 을 배포가 중지될 때 보내며, 이를 받는 것은 컨테이너의 메인 프로세스뿐입니다 - 우아한 종료를 구현하려면 이를 처리하세요.
{% endhint %}

☑️ 이미지 이름과 태그를 선택하여 이미지를 빌드하세요:

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 \
  -t registry.edgegap.com/<project>/<game-name>:<tag> .
```

{% endcode %}

* **이미지 이름** 은 배송 전에 서버 빌드를 라벨링하는, 원하는 고유한 식별자입니다.
  * 보통 게임 이름을 포함하며 - 예를 들어 “my-game-server”와 같습니다.
  * 앞에 `registry.edgegap.com/<project>/` 를 3단계의 프로젝트 이름과 함께 사용하세요 [#id-1.-connect-account](#id-1.-connect-account "mention"), 나중에 업로드할 수 있도록.
* **이미지 태그** 는 이미지의 특정 버전을 가리키는 식별자입니다.
  * “빌드 아티팩트”라는 용어는 때때로 이미지의 특정 버전을 가리키는 데 사용됩니다.
  * 태그에는 타임스탬프가 훌륭한 기본 옵션입니다. 예를 들어 `2026.11.02-16.25.00-UTC` .
* **플랫폼** `linux/amd64` 는 ARM 아키텍처 머신(macOS M1, M2, M3 등..)에서 빌드하더라도 이미지가 Edgegap 서버에서 실행되도록 보장합니다.

{% hint style="danger" %}
:x: **금지 - 기존 태그를 덮어쓰거나 다음을 사용하지 마세요. `latest`  태그** - 이렇게 하면 오래된 캐시가 배포됩니다.\
:white\_check\_mark: **권장 - 버전 태그를 항상 올리고** 새 빌드를 배포하세요.
{% endhint %}

☑️ 빌드가 끝날 때까지 기다리고, 명령줄에 새 오류가 없는지 확인하세요. 이 단계를 완료하면 **로컬 머신에 새 이미지가 나타납니다**. 이는 Docker Desktop의 Local(기본값) 아래 Images 탭에서 확인하거나, Docker CLI에서 다음을 실행해 확인할 수 있습니다 `docker images` .

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🧪 4. 서버를 로컬에서 테스트

업로드하고 배포하기 전에(약간의 시간이 걸릴 수 있음) 서버 이미지가 제대로 작동하는지 확인하기 위해 로컬(사용자 기기)에서 배포하고 게임 클라이언트를 연결해 보겠습니다.

☑️ 이미지에서 새 컨테이너를 시작하세요:

{% code collapsedlinecount="10" %}

```bash
docker run -p 7777/tcp registry.edgegap.com/<project>/<game-name>:<tag>
```

{% endcode %}

* `-p {내부 포트}/{프로토콜}` 서버 포트를 공개하고 매핑합니다 `7777` 임의의 외부 포트로. WebSocket은 TCP 프로토콜을 사용합니다.
* ARM 아키텍처 머신(macOS M1, M2, M3 등..)을 사용 중이라면 매개변수 `--platform=linux/amd64` .

☑️ 다음이 보이는지 확인하세요 `0.0.0.0:7777에서 수신 대기 중` 를 명령줄에 추가하세요. 이 단계를 완료하면 **새 컨테이너가 시작됩니다** 개발 머신에서.

{% hint style="info" %}
자세한 내용은 Docker Desktop / Containers 또는 Docker CLI 명령을 참조하세요 `docker ps` .
{% endhint %}

☑️ 이제 **로컬 Docker 컨테이너에 게임 클라이언트를 연결하여** 서버 이미지가 제대로 작동하는지 확인할 차례입니다. 브라우저 탭 두 개를 열고, 각 탭에서 개발자 도구 콘솔(`F12`)을 연 뒤 다음을 사용해 컨테이너에 연결하세요:

* `localhost` 를 서버 IP 대신 사용하고,
* Docker Desktop / Containers에서 찾은 무작위 외부 포트 값을 사용하세요.

{% code collapsedlinecount="10" %}

```javascript
const socket = new WebSocket('ws://localhost:<external port>')
socket.onmessage = (event) => console.log('received', event.data)
```

{% endcode %}

☑️ 한 탭에서 다음으로 메시지를 보내세요 `socket.send('hello')` 그리고 두 탭 모두에 다음이 로그되는지 확인하세요 `hello를 받음`.

<figure><img src="https://1562312210-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FCDGTUe5ests3DI3u9rTV%2Fimage.png?alt=media&amp;token=8c4799d8-0622-4142-91a5-93fd1816149c" alt=""><figcaption></figcaption></figure>

☑️ 로컬 서버 컨테이너에 연결하여 문제없이 플레이할 수 있는지 확인한 후에는 기기의 리소스를 다른 프로그램용으로 확보하기 위해 컨테이너를 삭제할 수 있습니다 🗑️

✅ 이제 다음 단계로 진행할 수 있습니다.

## ☁️ 5. Edgegap에 업로드

서버를 온라인으로 배포할 시간입니다! 이제 이미지가 플레이어를 성공적으로 호스팅할 수 있으므로 이를 Edgegap에 업로드하여 전 세계 어디에서나 실행할 수 있습니다. 이 가이드에서는 [**Edgegap의 컨테이너 레지스트리**](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md) (이미지 저장소).

☑️ 이미지를 Edgegap의 컨테이너 레지스트리에 업로드하세요:

{% code collapsedlinecount="10" %}

```bash
docker push registry.edgegap.com/<project>/<game-name>:<tag>
```

{% endcode %}

{% hint style="success" %}
컴퓨터에 저장된 모든 이미지 이름과 태그를 찾으려면 **Docker Desktop / 이미지**.
{% endhint %}

☑️ 업로드가 끝날 때까지 기다리고, 명령줄에 새 오류가 없는지 확인하세요. 이 단계를 완료하면 [빌드 아티팩트가 Edgegap의 컨테이너 레지스트리에 업로드됩니다](https://app.edgegap.com/registry-management/repositories/list).

☑️ 우리의 [대시보드](https://app.edgegap.com/application-management/applications/list) 를 열고 새 애플리케이션을 생성하세요. 다음 옵션을 구성할 수 있습니다(또는 기본값 유지):

* **애플리케이션 이름** Edgegap에서는 이미지 이름과 같게 하거나 사용자 지정할 수 있습니다.
* **애플리케이션 버전** Edgegap에서는 태그와 같게 하거나 사용자 지정할 수 있습니다.
  * 버전 이름에는 타임스탬프가 좋은 옵션입니다. 예를 들어 `2026.11.02-16.25.00-UTC` .
  * 여러 애플리케이션 버전이 같은 이미지 태그를 가리킬 수 있습니다. 예: `v1.1.0` 과 `dev` .
  * 에 대해 더 알아보기 [앱 및 버전](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md) 은 나중에.
* **이미지** 단계 [#id-3.-containerize-server](#id-3.-containerize-server "mention"), 저장소와 태그를 선택하세요.
* **리소스** 0.25 vCPU와 512MB 메모리면 이 템플릿으로 시작하기에 충분합니다.

☑️ 이제 새 애플리케이션 버전의 포트를 정의하라는 안내가 표시됩니다:

* **포트** `7777` 단계의 서버 포트와 일치하는 [#id-2.-build-game-server](#id-2.-build-game-server "mention"),
* **프로토콜** `WS` (WebSocket),
* **TLS 업그레이드** 사용,
* **이름** `gameport`.

{% hint style="info" %}
**TLS 업그레이드를 사용하면 브라우저가 보안 WebSocket으로 연결할 수 있습니다** (`wss://`). 다음을 통해 제공되는 페이지는 `https://` 보안되지 않은 `ws://` 연결을 열 수 없으므로, 브라우저 게임에서는 TLS 업그레이드를 활성화한 상태로 유지하세요.
{% endhint %}

{% hint style="info" %}
무료 티어는 애플리케이션 2개, 버전 2개, 그리고 컨테이너 레지스트리 저장소 10GB로 제한됩니다.
{% endhint %}

{% hint style="success" %}
**코딩 에이전트를 사용 중이신가요?** 다음을 확인하세요 [MCP 통합](https://docs.edgegap.com/ko/docs/mcp.md) 편집기를 떠나지 않고도 애플리케이션, 버전, 배포를 만들 수 있습니다.
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

## 🚀 6. 클라우드에 배포

이 가이드의 마지막 단계로, 이 단계를 완료하면 전 세계 어디에서든 플레이어가 접속할 수 있는 Edgegap 클라우드에 서버가 배포됩니다.

☑️ **애플리케이션과 버전을 선택하세요** 배포를 위해 이전 단계에서.

☑️ 준비가 되면, 누르세요 **클라우드에 배포**, 도달할 때까지 기다리세요 [/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-3.-deployment-ready](https://docs.edgegap.com/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-3.-deployment-ready "mention"). 이 단계를 완료하면 결과적으로 [새 배포가 시작됩니다](https://app.edgegap.com/deployment-management/deployments/list) 귀하의 Edgegap 계정에서.

☑️ 콘솔 출력에 새로운 오류가 없는지 확인하세요. 또한 다음이 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#container-logs) 오류를 표시하지 않는지 및 귀하의 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#container-metrics) 가(이) vCPU 또는 메모리의 100% 자원 사용을 나타내지 않는지 확인하세요. 그렇지 않으면 새 플레이어 연결이 거부되거나 서버가 재시작 루프에 갇힐 수 있습니다. 문제 해결 단계는 아래를 참고하세요.

☑️ 이제 최종 테스트를 수행하고 **게임 클라이언트를 클라우드 배포에 연결합니다**. 다음을 가져오세요 **배포의 호스트** 를 서버 IP 대신 사용하고 **외부 포트** 를 `gameport`, 그리고 브라우저 콘솔에서 보안 WebSocket으로 연결하세요:

{% code collapsedlinecount="10" %}

```javascript
const socket = new WebSocket('wss://<host>:<external port>')
socket.onmessage = (event) => console.log('received', event.data)
```

{% endcode %}

<figure><img src="https://1562312210-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fz9xjzvZwKSIp9IeC9qo8%2Fimage.png?alt=media&amp;token=e3f345ac-848d-4469-b66f-3655cd393cf3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Edgegap 클라우드에서 배포의 외부 포트는 임의로 선택되어 잠재적 공격자(해커)가 피해를 일으키기 전에 속도가 느려지고 탐지되도록 합니다.
{% endhint %}

{% hint style="warning" %}
**테스트 시 VPN 비활성화** 보다 현실적인 조건을 위해 그리고 [저지연 배포를 받으려면](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#server-placement).
{% endhint %}

☑️ 배포에 문제없이 연결할 수 있음을 확인하고 테스트를 마쳤다면, **배포 중지** 다음 빌드를 위해 계정의 용량을 확보하려면.

* 문제가 발생한 경우, [배포의 대시보드 로그를 검사하세요](https://app.edgegap.com/deployment-management/deployments/list).
* 문제를 해결할 수 없다면, 저희는 [커뮤니티 디스코드](https://discord.gg/NgCnkHbsGp) 에서 도와드릴 수 있으며 기꺼이 지원하겠습니다.

🙌 Edgegap에서의 첫 배포를 축하합니다! 더 알아보고 싶다면 계속 읽어보세요.

## 👉 다음 단계

클라이언트/서버 구성이 작동하면, 반드시 **프로젝트 복사본을 저장하세요** (git과 같은 버전 관리 소프트웨어를 사용하여) 문제가 발생했을 때 항상 작업 내역을 추적할 수 있도록.

서버 수명주기 및 검색 가능성과 관련된 주제를 더 알아보려면 계속 읽으세요.

{% hint style="info" %}
도움이 필요하시면 [디스코드를 통해 문의해 주세요](https://discord.gg/MmJf8fWjnt). 실시간 게임 지원은 저희의 [티켓 시스템](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 배포 중지

매치가 끝나거나(또는 플레이어가 떠나면), 비용을 절감하기 위해 배포를 중지할 수 있습니다. [비어 있거나 일부만 채워진 배포를 계속 실행하면 불필요하게 비용이 늘어날 수 있습니다!](https://edgegap.com/blog/how-session-fill-rate-affects-your-multiplayer-hosting-costs)

서버 코드에서 배포를 중지하면, Edgegap이 다음을 서버로 보냅니다 `SIGTERM` :

{% code collapsedlinecount="10" %}

```javascript
const stopDeployment = () =>
  fetch(deployment.selfStopUrl, {
    method: 'DELETE',
    headers: { authorization: deployment.selfStopToken }
  }) // 예제는 배포의 자체 중지 정보를 읽기 위해 JavaScript SDK를 사용합니다
```

{% endcode %}

{% hint style="success" %}
**호출하세요 `stopDeployment` 매치가 끝났을 때, 모든 플레이어가 떠났을 때, 또는 아무도 연결되지 않은 상태가** 배포 시작 후 적절한 시간 내에.
{% endhint %}

{% hint style="warning" %}
연결하세요 [엔드포인트 스토리지](https://docs.edgegap.com/ko/docs/endpoint-storage.md) 배포 로그를 저장하려면, 그렇지 않으면 삭제됩니다!
{% endhint %}

### 주입된 변수

주입된 환경 변수를 통해 배포 ID, 서버 IP 주소, 서버 위치 등 유용한 정보를 읽을 수 있습니다. 각 배포에는 자동으로 다음이 포함됩니다:

* [배포 변수](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#injected-environment-variables) - Edgegap이 자동으로 제공합니다,
* [매치메이킹 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-environment-variables) - Edgegap이 다음을 사용할 때 자동으로 제공합니다 [매치메이킹](https://docs.edgegap.com/ko/learn/matchmaking.md),
* [앱 버전 변수](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#injected-variables) - 사용자가 구성할 수 있는 사용자 지정 키-값 쌍입니다.

다음을 사용해 변수를 읽으세요 `process.env`, 또는 선택 사항인 SDK로 이를 타입이 있는 객체로 파싱하세요:

{% code collapsedlinecount="10" %}

```javascript
import { DeploymentEnvironment } from '@edgegap/sdk'
import { MatchEnvironment } from '@edgegap/sdk/matchmaking'

const deployment = DeploymentEnvironment.fromEnv(process.env)
const match = MatchEnvironment.fromEnv(process.env)
```

{% endcode %}

{% hint style="info" %}
파싱은 결코 예외를 던지지 않으므로, 동일한 서버가 로컬에서도 실행됩니다. 누락된 변수는 단일 경고로 나열됩니다.
{% endhint %}

### 세션 자동화

개발자나 QA 팀과 함께 새 빌드를 테스트할 때는 세션 단계가 종종 생략되고, 플레이어는 세션 관련 기능을 하드코딩하거나 비활성화한 상태로 배포에 직접 연결됩니다. 이렇게 하면 개발 반복 속도가 빨라지고 세션의 부작용이 서버 기능과 분리됩니다.

{% hint style="warning" %}
**배포를 수동으로 시작하고 URL과 포트를 붙여넣는 방식으로는 라이브 게임에 충분하지 않습니다.**
{% endhint %}

다음을 위한 인기 있는 게임 흐름 자동화 [플레이어 세션](https://docs.edgegap.com/ko/learn/orchestration/player-sessions.md) 그리고 서버 확장을 다음 중 하나로:

{% columns %}
{% column width="33.33333333333333%" %}
[매치메이킹](https://docs.edgegap.com/ko/learn/matchmaking.md):

* 경쟁 게임
* 온디맨드 매치
* 실력 평점 및/또는\
  사용자 지정 규칙
  {% endcolumn %}

{% column width="33.33333333333333%" %}
[서버 브라우저](https://docs.edgegap.com/ko/learn/server-browser.md):

* 지속형 또는 소셜
* 긴 세션
* 자동 할당 및/또는\
  사용자 지정 검색
  {% endcolumn %}

{% column width="33.33333333333333%" %}
사용자 지정 백엔드:

* 라이브 게임 마이그레이션
* [v2 API로 배포](https://docs.edgegap.com/ko/docs/api/dedicated-servers.md)
* [웹훅 모니터링](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#webhooks)
  {% endcolumn %}
  {% endcolumns %}

{% hint style="success" %}
다음 선택 사항을 사용해 브라우저 게임에 매치메이킹을 추가하세요 [JavaScript SDK](https://docs.edgegap.com/ko/web-games/matchmaking.md), 그룹 클라이언트와 서버 백필 자동화도 포함됩니다.
{% endhint %}

### 샘플

[Three.js와 권위형 Node.js 서버로 만든 다섯 가지 브라우저 멀티플레이어 미니게임에서 영감을 얻어보세요.](https://docs.edgegap.com/ko/docs/sample-projects/web-games/threejs-minigames.md) 브라우저에서의 매치메이킹, 여러 게임을 위한 하나의 이미지, 팀 배정, 매치가 끝나면 스스로 중지되는 배포를 포함합니다.

{% hint style="success" %}
[게임 샘플 둘러보기](https://docs.edgegap.com/ko/docs/sample-projects.md) 영감을 얻고 프로젝트를 진행할 자신감을 키우세요.
{% endhint %}

### 사용 최적화

서버 사용량을 최적화하기 위한 시작 팁 몇 가지:

**틱 레이트가 높을수록 업데이트가 더 많아져 CPU 사용량과 데이터 송신량이 늘어납니다.**

* 브라우저 게임은 흔히 초당 30\~60틱으로 시뮬레이션하고 플레이어에게는 10\~20Hz로 상태를 보내며, 클라이언트는 업데이트 사이를 보간합니다. 우리의 Three.js 샘플은 초당 20번 업데이트를 보냅니다.
* Node.js는 게임 루프를 단일 스레드에서 실행하므로, 느린 틱은 모든 플레이어의 메시지를 지연시킵니다. 한 경기당 플레이어 수가 많거나(10명 이상), 복잡한 물리 시뮬레이션, 또는 많은 봇 상대/아군이 있는 게임이라면 특히 주의하세요. 다음으로 서버를 프로파일링해 병목 지점을 찾으세요 `node --cpu-prof` 을 사용해.
* JSON 메시지는 디버깅하기 쉽고, 바이너리 메시지(`ArrayBuffer`)는 자주 상태를 업데이트할 때 데이터 송신량을 줄여줍니다.

**어떤 네트워킹 프로토콜을 선택해야 할까요? 먼저 작동하게 만들고, 그다음 더 좋게 만드세요.**

* 브라우저는 원시 UDP나 TCP 연결을 열 수 없고, WebSocket, WebRTC, WebTransport만 가능합니다. WebSocket은 가장 다양한 기기와 네트워크에서 호환성을 제공하는 훌륭한 기본 선택입니다.
* 빠르게 진행되는 일부 게임은 신뢰성 없는 전송을 위해 WebRTC 데이터 채널이나 WebTransport를 실험하고 싶을 수 있지만, 분명 추가 개발 노력이 필요합니다. 이것이 목표 사용자에게 중요한지 스스로 물어보세요.
* 싸움은 신중하게 고르세요. 게임 개발에는 도전 과제가 넘쳐납니다.

### 이미지 사용자 지정

단계의 Dockerfile [#id-3.-containerize-server](#id-3.-containerize-server "mention") 은 빌드 크기 최적화, 불필요한 종속성, 또는 더 복잡한 시작 프로세스가 필요할 때 사용자 지정할 수 있습니다. 이제 몇 가지 “직접 해보는” 팁과 모범 사례를 공유하겠습니다.

**멀티 스테이지 빌드로 서버를 단일 파일로 번들링하세요.**

* 다음과 같은 번들러는 [esbuild](https://esbuild.github.io/) TypeScript를 컴파일하고 코드와 종속성을 하나의 파일로 합치므로 최종 이미지에 `node_modules` 또는 소스 파일이 필요 없습니다. 절감 효과는 종속성 트리의 크기가 커질수록 커집니다.
* 다음으로 esbuild를 설치하세요 `npm install --save-dev esbuild` 그리고 Dockerfile을 다음으로 바꾸세요:

{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY server.js ./
RUN npx esbuild server.js --bundle --platform=node --target=node22 --outfile=dist/server.cjs

FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist/server.cjs ./
USER node
CMD ["node", "server.cjs"]
```

{% endcode %}

**항상 정상적으로 동작하는 서버 빌드를 사용하고 있는지 확인하세요.**

* 문제가 커스텀 Dockerfile과 관련된 것이라고 단정하기 전에, 서버 빌드가 정상적으로 시작될 수 있는지와 게임 엔진의 빌드 과정에서 예외나 오류가 발생하지 않았는지 확인하세요.

**업로드하기 전에 항상 로컬에서 테스트하세요.**

* 이미지를 로컬에서 테스트하면 업로드가 완료될 때까지 기다리는 동안 많은 시간을 절약할 수 있습니다. 또한 Edgegap 리소스가 전혀 필요하지 않으므로 완전히 무료입니다 ✨
* 로컬에서 테스트할 때는 내부 포트를 올바르게 설정했는지 확인하세요:

  ```bash
  docker run \
    -p 7777/udp \
    -e ARBITRIUM_PORTS_MAPPING='{"ports":{"gameport":{"internal":7777}}}' \
    'registry.edgegap.com/<repository>:<tag>'
  ```

**기본 사항을 제대로 이해했는지 확인하세요. 모든 Dockerfile에는 몇 가지 필수 명령이 필요합니다:**

* `FROM {image}` 는 기본 이미지입니다. 보통 장기 지원되는 Linux를 사용하지만, Linux 기반 기본 이미지라면 어떤 것이든 괜찮습니다. 보통 Docker Hub에 저장된 공개 이미지입니다. Dockerfile 참고는 여기입니다. [Dockerfile 참고는 여기](https://docs.docker.com/reference/dockerfile/#from).
* `COPY {source} {destination}` 호스트 머신의 Linux 서버 빌드를 이미지 안으로 복사하여 나중에 시작할 수 있게 합니다. [Dockerfile 참고는 여기](https://docs.docker.com/reference/dockerfile/#copy).
* `USER {user}` 다음 뒤에 와야 합니다 [useradd(우분투) 명령](https://manpages.ubuntu.com/manpages/bionic/man8/useradd.8.html) 또는 이에 상응하는 명령 뒤에 와야 하며, 모든 것을 `root` 로 실행하지 않는 것이 가장 좋습니다. [Dockerfile 참고는 여기](https://docs.docker.com/reference/dockerfile/#user).
* `CMD {command}` 가 마지막 줄이 되며, 대부분 다음을 호출합니다: `StartServer.sh` 또는 서버가 모든 설정 완료 후 올바르게 초기화되도록 하는 어떤 종류의 시작 스크립트입니다. [Dockerfile 참고는 여기](https://docs.docker.com/reference/dockerfile/#cmd).
* 사용하지 마세요 `VOLUME` - 이런 방식으로는 Edgegap에서 로컬 스토리지를 마운트할 수 없습니다. 대신 Endpoint Storage 기능을 고려하고 S3 버킷을 사용하세요. 다음을 참조하세요: [Endpoint Storage](https://docs.edgegap.com/docs/deployment/endpoint-storage),
* `EXPOSE 7777/UDP`  는 필요하지 않습니다! 이것은 실제로 컨테이너 외부에서 내부 서버 포트를 사용할 수 있게 만드는 것이 아니라, 개발자를 위한 힌트일 뿐이며 포트는
  * 다음과 함께 로컬에서 테스트할 때 공개되어야 합니다 `docker run <image> -p 7777/udp` ,
  * 또는 다음에 매핑되어야 합니다 [Edgegap 포트 매핑](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#other-parameters-optional).

**매개변수 선언은 가능한 가장 늦은 시점까지 미루세요. 서버 빌드 시간이 길기 때문에 구성 가능성 > 조합 가능성입니다.** [**이 접근 방식을 Dockerfile 명령에 적용하면 빌드와 업로드를 더 빠르게 할 수 있습니다.**](https://medium.com/@esotericmeans/optimizing-your-dockerfile-dc4b7b527756)

* 시나리오: 배포 단계, 버전, 게임 모드, 맵, 서버당 플레이어 수, 백업 빈도 또는 이와 유사한 매개변수를 정의해야 합니다.
* 나쁜 해결책: 매개변수 조합마다 별도의 이미지를 만드는 것입니다. 이 접근 방식으로 얻는 이점은 거의 없는데, 이미지를 다시 빌드하는 데 모든 시간을 쓰게 됩니다.
* 더 나은 해결책 - 구성 매개변수를 필요한 시점에 대체하세요:
  1. 배포 매개변수 - 배포 직전에 제공됨 - 환경 변수로 전달되는 매치메이킹 선택자, 또는 배포 시점에 환경 변수를 전달하는 사용자 정의 세션 관리 시스템,
  2. 버전 매개변수 - 앱 버전의 모든 배포에서 공유됨 - 배포 단계, 아티팩트 태그, 타사 비밀 및 엔드포인트 등; 그런 다음
  3. 하나의 단일 이미지 - 실행될 때 모든 구성 옵션을 포함하고 로드합니다.

**Edgegap 배포에서 데이터베이스를 실행하지 마세요.**

* Edgegap 배포는 장시간 실행되는 프로세스를 위한 것이 아니며, 장시간 실행된 후 사전 통지 없이 종료될 수 있습니다. 이런 방식으로 실행되는 데이터베이스(분산형이라도)는 종료될 수 있으며, 돌이킬 수 없는 데이터 손실로 이어질 수 있습니다. 데이터베이스가 필요하다면 타사 DBaaS를 고려해 주세요.
* 다음 기능 사용을 고려하세요: [Managed Clusters](https://app.edgegap.com/cluster-management/clusters/list) 데이터베이스와 장기 실행 서비스를 호스팅하는 데 사용합니다.
