Nakama는 Heroic Labs가 만든 오픈소스 게임 백엔드 서버로, Go로 작성되어 있으며 사용자 인증/소셜 그래프/채팅/실시간 및 턴제 멀티플레이어/매치메이킹/리더보드/토너먼트/파티/인앱결제 검증/알림 등 게임 서비스에 필요한 기능을 하나의 서버 바이너리로 제공합니다. CockroachDB 또는 Postgres 호환 DB를 저장소로 쓰며, Lua/JavaScript(TypeScript)/Go 네이티브 코드로 서버 로직을 확장할 수 있는 런타임을 내장하고 있습니다.
main.go의 진입점은 CLI 서브커맨드(migrate, check, healthcheck, 기본 서버 실행)를 분기 처리합니다. 서버는 config를 파싱한 뒤 pgx 드라이버로 CockroachDB/Postgres에 연결하고, 시작 시 데이터베이스 스키마를 migrate 커맨드로 적용해야 합니다(docker-compose.yml에서 'migrate up' 후 서버 기동 순서를 볼 수 있음). API는 apigrpc/ 디렉터리의 .proto로 정의된 gRPC 서비스와 grpc-gateway를 통해 REST/HTTP로도 노출되며, 포트 7349(gRPC), 7350(HTTP/WS), 7351(콘솔)을 사용합니다(Dockerfile EXPOSE로 확인). 커스텀 게임 로직은 data/modules/ 아래 Lua 스크립트(internal/gopher-lua 임베디드 VM으로 실행)나 Go 플러그인, TS/JS로 작성해 런타임에 로드되며, 'check' 서브커맨드로 런타임 모듈 경로의 문법을 사전 검증할 수 있습니다. 운영 콘솔(console/)은 gRPC 서비스(console.proto)와 미리 빌드된 정적 웹 UI(console/ui/dist)를 내장 서빙하여 대시보드로 접근 가능합니다. 배포는 build/Dockerfile로 멀티스테이지 빌드되어 Debian 슬림 이미지에 담기며 tini로 프로세스를 관리하고 자체 healthcheck 커맨드를 제공합니다.
- STEP 01
docker-compose.yml을 그대로 실행하면 cockroachdb 컨테이너가 먼저 healthy 상태가 될 때까지 기다린 뒤, nakama 컨테이너가 'migrate up'으로 DB 스키마를 적용하고 이어서 서버를 기동하는 것을 로그로 확인하게 됩니다.
- STEP 02
서버가 뜨면 7350(클라이언트 API), 7349(gRPC), 7351(콘솔) 포트가 열리고, 브라우저로 localhost:7351에 접속하면 console/ui/dist에 내장된 대시보드 UI(로그인 화면)가 로드됩니다.
- STEP 03
data/modules/ 아래 match.lua, tournament.lua 같은 예제 Lua 모듈이 서버 시작 로그에 로드 메시지로 출력되는 것을 볼 수 있고, 'nakama check' 커맨드로 모듈 문법 오류를 사전에 잡아볼 수 있습니다.
- STEP 04
prometheus 서비스가 함께 뜨면서 nakama의 9100 포트를 스크레이핑하기 시작하고, localhost:9090에서 프로메테우스 UI로 메트릭 쿼리가 가능해집니다.
- STEP 05
직접 go build -trimpath -mod=vendor로 빌드를 시도하면 CGO_ENABLED와 gcc/libc6-dev 같은 네이티브 빌드 의존성이 필요함을 Dockerfile 빌드 단계에서 알 수 있습니다.
- STEP 06
커스텀 Go 플러그인을 작성하려면 heroiclabs/nakama-pluginbuilder 이미지를 사용해 별도 컨테이너에서 빌드해야 한다는 점을 build/pluginbuilder/Dockerfile을 통해 알게 됩니다.
로컬에서는 CockroachDB(또는 Postgres)와 함께 뜨는 완전한 게임 백엔드 서버 인스턴스를 얻게 되며, 클라이언트 SDK(Unity, Unreal, Godot, JS 등)로 연결해 인증·리더보드·매치메이킹·채팅 API를 바로 호출할 수 있습니다. 또한 웹 기반 운영 콘솔에서 유저/스토리지/리더보드 데이터를 조회·수정할 수 있고, Lua/JS/Go로 서버측 커스텀 로직(RPC, 매치 핸들러, IAP 검증 등)을 배포해 게임 특화 백엔드로 확장한 결과물을 얻습니다.
서버 단독으로는 동작하지 않고 CockroachDB 또는 Postgres 호환 DB가 반드시 필요하며, 최초 기동 전 migrate up으로 스키마를 적용해야 합니다.
docker-compose.yml에 명시된 이미지 태그(registry.heroiclabs.com/heroiclabs/nakama:3.37.0)는 소스 레포의 최신 코드와 버전이 다를 수 있어, 직접 소스로 빌드하려면 별도 Dockerfile 빌드 과정이 필요합니다.
Go 네이티브 런타임 플러그인을 쓰려면 CGO_ENABLED=1과 gcc 등 네이티브 툴체인, 그리고 전용 pluginbuilder 이미지가 필요해 크로스플랫폼 빌드가 다소 번거롭습니다.
콘솔 UI는 미리 빌드된 정적 파일(dist)로 제공되므로, UI 소스 자체를 수정·재빌드하려면 이 레포에 포함되지 않은 별도 프론트엔드 소스가 필요할 수 있습니다.
실시간 멀티플레이어, 리더보드, 소셜/채팅, 인앱결제 검증 등을 자체 인프라로 직접 운영하고 싶은 게임/앱 개발팀에 적합하며, Unity·Unreal·Godot 등 주요 엔진용 클라이언트 SDK 생태계와 함께 쓰도록 설계되어 있습니다. docker-compose.yml, Dockerfile, main.go의 서브커맨드 구조, apigrpc/console의 proto 정의, data/modules의 실제 Lua 예제 코드까지 파일 근거가 구체적이고 상호 일관되므로, 직접 설치해보지 않아도 '문서상 주장'과 '실제 코드/설정 구조'가 일치한다는 판단은 신뢰할 만합니다. 다만 실제 프로덕션 배포 성능이나 스케일링 특성은 코드만으로 확인할 수 없는 영역이라 별도 검증이 필요합니다.