설치
MSI 인스톨러(Windows)
MongoDB 및 Redis의 Windows 빌드는 인스톨러에 포함되어 있으며, 시작 시 호드에서 실행되고 종료 시에도 호드에서 닫힙니다. 이 설치 방법은 소규모 설치와 호드 테스트에 적합하며, 프로덕션 시나리오에서는 별도로 데이터베이스를 호스팅하는 것이 선호됩니다.
Docker(Linux)
Docker를 통한 호드 호스팅에 대한 이미지는 GitHub의 에픽게임즈 조직을 통해 이용할 수 있습니다. 이 링크를 따라 하려면 에픽게임즈 계정과 연결된 계정으로 GitHub에 로그인해야 한다는 점에 유의하세요.
이미지를 다운로드하려면 먼저 계정 세팅 페이지의 개발자 섹션에서 GitHub 개인 액세스 토큰(Personal Access Token, PAT)을 생성하여 다음 위치에 비밀번호로 전달합니다.
docker login ghcr.io
이미지를 다운로드하려면 다음을 사용합니다.
docker pull ghcr.io/epicgames/horde-server:latest
이 형식에서 외부 MongoDB 및 Redis 인스턴스는 환경설정 파일 또는 환경 변수를 통해 환경설정해야 한다는 점에 유의하세요(아래 내용 참고).
로드 밸런서가 적용된 다수의 호드 서버를 실행하는 경우 각 서버가 동일한 MongoDB 및 Redis 인스턴스를 가리키는 한 명시적인 환경설정이 필요하지 않습니다.
Linux에서 Docker 컨테이너를 사용하는 것은 에픽이 선호하는 호드 실행 방식입니다.
Docker Compose(Linux)
Docker Compose는 MongoDB 및 Redis의 인스턴스를 포함하는 Docker 컨테이너의 사전 환경설정된 그룹을 제공하여 Docker 기반 설치의 구성을 간소화합니다.
MSI 인스톨러와 마찬가지로, 이 방법은 호드를 테스트하거나 소규모 환경에서 디플로이하기에 적합합니다. 사전 빌드된 이미지에 액세스하려면 위의 Docker 섹션을 참고하세요. 필요한 Docker Compose 환경설정은 Engine/Source/Programs/Horde.Server/docker-compose.yml 파일 내부에서 찾을 수 있습니다.
동일한 디렉터리에서 다음을 사용하여 컨테이너를 시작하세요.
docker compose up
추가적인 안내는 YAML 파일 내 코멘트를 확인하세요.
Homebrew(Mac)
Mac에서 서버를 실행하기 위한 사전 빌드된 바이너리를 제공하지는 않지만, Homebrew를 사용하면 비교적 직관적으로 모든 필수 구성 요소를 설치할 수 있습니다.
-
.NET 8 SDK를 설치합니다.
brew install dotnet-sdk -
MongoDB를 설치합니다.
brew tap mongodb/brew brew update brew install mongodb-community brew services start mongodb-community -
Redis를 설치합니다.
brew install redis brew services start redis -
호드를 실행합니다. 아래 환경 변수는 표준 ASP.NET 구문을 사용합니다. 원한다면 대신 server.json에서 값을 수정할 수 있습니다.
export Horde__MongoConnectionString=mongodb://localhost:27017 export Horde__HttpPort=37107 export Horde__Http2Port=37109 cd Engine/Source/Programs/Horde/Horde.Server dotnet run
소스에서 빌드하기
호드 서버의 소스 코드는 Engine/Source/Programs/Horde/Horde.Server/... 에 있습니다.
서버는 Engine/Source/Programs/Horde/Horde.sln 에 있는 솔루션을 사용하여 Visual Studio에서 빌드 및 실행하거나, dotnet build 또는 dotnet publish 명령을 통해 명령줄에서 빌드 및 실행할 수 있습니다.
Docker 이미지는 Engine/Source/Programs/Horde.Server/Dockerfile 의 Dockerfile을 사용하여 Engine/Source/Programs/Horde/BuildHorde.xml 에서 BuildGraph 스크립트를 통해 빌드할 수 있습니다.
Dockerfile을 바로 실행하는 경우 BuildGraph 스크립트를 사용하는 것이 권장됩니다. docker build 를 실행하기 전에 관련 파일을 임시 디렉터리에 스테이징하여, Docker Daemon이 빌드 전에 전체 UE 소스 트리를 컨테이너화된 환경에 복사하는 것을 방지해 주기 때문입니다.
BuildGraph를 사용하여 Docker 이미지를 빌드하기 위한 명령줄은 다음과 같습니다.
RunUAT.bat BuildGraph -Script=Engine/Source/Programs/Horde/BuildHorde.xml -Target="Build HordeServer"
Windows 인스톨러는 동일한 BuildGraph 스크립트에서 다음과 비슷한 명령줄로 빌드할 수 있습니다.
RunUAT.bat BuildGraph -Script=Engine/Source/Programs/Horde/BuildHorde.xml -Target="Build Horde Installer"
세팅
일반
서버 세팅은 Server.json 파일을 통해 환경설정할 수 있습니다. Windows에서 이 파일은 C:\ProgramData\Epic\Horde\Server\Server.json 에 저장되어 있습니다. 다른 플랫폼에서는 기본적으로 애플리케이션 디렉터리 하위의 Data 폴더에 저장됩니다. 이 파일의 세팅은 서버 실행 파일과 함께 배포된 appsettings.json 파일 상위에 적용됩니다.
모든 호드 관련 세팅은 최고 수준 키 Horde 하위에, 미들웨어 및 표준 .NET 세팅은 다른 루트 키 하위에 저장됩니다.
ASP.NET 애플리케이션으로서 호드의 애플리케이션 환경설정은 다음 기능을 지원합니다.
- 표준 ASP.NET 구문을 사용하여 환경 변수 를 통해 개별 프로퍼티를 오버라이드할 수 있습니다(MSDN 참고). 예를 들어 데이터베이스 연결 스트링은
Horde__MongoConnectionString환경 변수를 사용하여 전달할 수 있습니다. - 디플로이 환경은 ASPNETCORE_ENVIRONMENT 환경 변수를 사용하여 환경설정할 수 있습니다. 호드의 표준 값은
Production,Development,Local입니다. appsettings.{Environment}.json(예:appsettings.Local.json)이라는 디플로이별 환경설정 파일을 생성할 수 있습니다. 이 파일은 다른 세팅과 병합됩니다.
서버 환경설정 파일(Server.json, appsettings.json 등)은 글로벌 환경설정 파일(globals.json)과 다르다는 점에 유의하세요. 서버 환경설정 파일은 서버와 함께 디플로이됩니다. 서버 환경설정 파일에는 디플로이/인프라 세팅이 포함되는 반면, 글로벌 환경설정 파일은 리비전 컨트롤에 저장되며 서버의 수명 동안 동적으로 업데이트될 수 있습니다. 자세한 내용은 환경설정 > 오리엔테이션을 참고하세요.
MongoDB
MongoDB 연결 스트링은 Server.json 파일의 MongoConnectionString 프로퍼티나 Horde__MongoConnectionString 환경 변수를 통해 지정할 수 있습니다. 연결 스트링은 다음 예시와 같은 표준 MongoDB 구문이어야 합니다.
mongodb://username:password@host:27017?replicaSet=rs0&readPreference=primary
호드는 수많은 작업을 CAS(Compare-And-Swap) 작업으로 구현하므로, 사본 세트 사용 시 모든 읽기가 readPreference=primary 실행인자를 통해 주요 데이터베이스 인스턴스를 사용하도록 환경설정하는 것이 중요합니다. 읽기에 보조 인스턴스를 사용하면 서버가 읽기-수정-쓰기 주기에서 구버전 문서를 얻게 되므로 교착 상태가 발생할 수 있습니다.
MongoDB 연결은 MongoPublicCertificate 프로퍼티를 통해 신뢰할 수 있는 인증서 세트를 사용하도록 환경설정할 수 있습니다. 예를 들어 AWS에서 DocumentDB를 사용하여 실행하는 경우, global-bundle.pem 파일을 서버의 애플리케이션 디렉터리에 배치하여 이 프로퍼티가 Amazon의 결합된 인증서 번들을 사용하도록 설정할 수 있습니다.
Redis
Redis 서버는 Server.json 파일의 RedisConnectionConfig 프로퍼티나 Horde__MongoConnectionString 환경 변수를 통해 환경설정할 수 있습니다. 이 스트링의 포맷은 다음 예시와 같이 일반 서버 및 포트로 지정됩니다.
127.0.0.1:6379
포트
기본적으로 호드는 포트 5000을 사용하여 암호화되지 않은 HTTP를 통해 데이터를 제공하도록 환경설정됩니다. 에이전트는 기본적으로 포트 5002의 암호화되지 않은 HTTP/2를 통해 gRPC를 사용하여 호드 서버와 통신합니다. 이러한 세팅은 서버가 시작되는 동안 콘솔에 반영됩니다.
Kestrel(.NET 웹 서버)은 암호화되지 않은 HTTP/2 트래픽을 동일한 포트에서 HTTP/1 트래픽으로 지원하지 않으므로, gRPC에는 별도의 포트가 사용됩니다. 비 TLS HTTP/2 트래픽을 위한 이 별도의 포트는 호드를 리버스 프록시 뒤에 배치할 때 유용할 수 있습니다. HTTPS 포트가 환경설정되면 모든 트래픽이 해당 포트를 사용할 수 있습니다.
포트 사용에 대한 세팅은 다음과 같이 Server.json에서 정의됩니다.
- HTTP를 통한 데이터 제공을 비활성화하려면
HttpPort프로퍼티를 0으로 설정합니다. - 사용되는 보조 HTTP/2 포트를 환경설정하려면
Http2Port프로퍼티를 설정하고, 비활성화하려면 해당 프로퍼티를 0으로 설정합니다.
HTTPS
HTTPS를 통해 데이터를 제공하려면 Server.json 파일의 HttpsPort 프로퍼티를 설정합니다.
같은 파일에서 기본 인증서를 설정하여 Kestrel(NET Core의 웹 서버)을 위한 인증서를 환경설정합니다.
크로스 플랫폼:
"Kestrel": {
"Certificates": {
"Default": {
"Path": "C:\\cert\\test.pfx",
"Password": "my-password"
}
}
}
Windows(시스템 인증서 스토어 사용):
"Kestrel": {
"Certificates": {
"Default":
{
"Subject": "my-domain.com",
// 로컬 머신에서 '개인' 인증서 스토어를 사용합니다.
"Store": "My",
"Location": "LocalMachine"
}
}
}
Kestrel 오브젝트는 Horde 오브젝트 내부가 아닌, 파일의 루트 범위에 추가해야 합니다.
Kestrel을 위한 인증서를 환경설정하는 다른 방법은 MSDN에 나열되어 있습니다.
HTTP/1.1 및 HTTP/2.0 트래픽은 모두 HttpsPort 를 통해 제공할 수 있습니다. 암호화되지 않은 트래픽은 HttpPort 및 Http2Port 를 0으로 설정하여 비활성화할 수 있습니다.
서버가 링크를 자체적으로 다시 제공하는 경우가 있으며(예: 호드의 내부 계정 시스템 사용 시 사용되는 OIDC Discovery 문서) 이러한 URL이 HTTPS 인증서와 일치하는 것이 중요합니다. 기본적으로 이 URL은 서버의 보고된 DNS 이름에서 파생되지만, ServerUrl 프로퍼티를 통해 오버라이드할 수 있습니다.
테스트용으로 자체 서명된 인증서를 구성하려면 튜토리얼 > 자체 서명된 인증서를 참고하세요.
모니터링
호드는 로깅에 Serilog를 사용하며, Linux의 애플리케이션 디렉터리 및 Windows의 C:\ProgramData\HordeServer 폴더로 일반 텍스트 및 JSON 로그 파일을 생성하도록 환경설정되어 있습니다. 일반 텍스트 출력은 기본적으로 stdout으로 작성되지만, Server.json의 LogJsonToStdOut 프로퍼티를 사용하여 Json 출력을 활성화할 수 있습니다.
서버의 프로파일링 및 원격 측정 데이터는 OpenTelemetry를 통해 라우팅됩니다. 원격 측정 캡처에 대한 세팅은 여기에 나열되어 있습니다.
RunMode
무거운 백그라운드 작업에서 가벼운 요청 트래픽을 분리하기 위해, 호드 서버는 다양한 RunMode에서 실행되도록 환경설정할 수 있습니다. 이는 RunMode 세팅을 통해 환경설정할 수 있습니다.
인증
호드는 외부 ID 제공자를 사용하는 인증을 위해 OpenID Connect(OIDC)를 지원합니다. OIDC는 광범위하게 사용되는 인증 표준으로서, Okta, AWS, Azure, Google, Facebook을 비롯한 수많은 플랫폼이 OIDC와 호환되는 ID 제공자를 구현합니다.
시작하기 > 인증 페이지에 호드의 내부 계정 시스템과 OIDC 제공자를 환경설정하는 방법이 설명되어 있습니다.
외부 OIDC 제공자를 환경설정하려면 Server.json의 다음 세팅이 필요합니다.
AuthMethod:OpenIdConnect로 설정합니다.OidcAuthority: OIDC 인증 기관의 URL입니다. 브라우저에서{{Url}}/.well-known/openid-configuration으로 이동하여 여기에 지정된 URL이 올바른지 확인할 수 있습니다. 이 URL은 OIDC Discovery 문서를 반환해야 합니다.OidcClientId: OIDC 제공자에 대해 애플리케이션(호드)을 식별합니다. OIDC 제공자에 의해 생성됩니다.OidcClientSecret: 인증을 요청하는 애플리케이션을 식별하기 위해 OIDC 제공자가 제공하는 암호 값입니다.
또한 다음 세팅을 지정할 수 있습니다.
OidcRequestedScopes: OIDC 제공자에서 요청한 스코프를 지정합니다. 스코프는 호드가 OIDC 제공자에게 요청하는 액세스 및 반환되어 호드 ACL에서 확인하는 데 사용할 수 있는 클레임을 결정합니다. 이러한 값의 의미는 OIDC 제공자 환경설정에 한정됩니다.OidcClaimNameMapping: 사용자의 실제 이름을 표시하려고 시도할 때 확인할 클레임 목록을 선호하는 순서로 지정합니다.OidcClaimEmailMapping: 사용자의 이메일 주소를 표시하려고 시도할 때 확인할 클레임 목록을 선호하는 순서로 지정합니다.OidcClaimHordePerforceUserMapping: 사용자의 Perforce 사용자 이름을 결정하려고 시도할 때 확인할 클레임 목록을 선호하는 순서로 지정합니다.
기타 인증 옵션은 환경설정 > 권한을 참고하세요.
레퍼런스
서버 환경설정 파일의 유효한 전체 프로퍼티 목록은 Server.json(서버)을 참고하세요.