호드 통합

설치

MSI 인스톨러(Windows)

이러한 방식으로 에이전트를 설치하면 Windows 알림 영역에 에이전트 상태를 표시하는 백그라운드 애플리케이션도 설치됩니다. 또한 머신이 대기 상태일 때만 에이전트가 실행되도록 환경설정할 수 있습니다.

이러한 방식으로 설치된 에이전트는 새 호드 버전에 맞게 수동으로 업그레이드해야 합니다.

서버에서 다운로드

호드 서버는 호드 에이전트의 다운로드 소스로 사용될 수 있습니다. 이 방식으로 에이전트를 배포하면 에이전트가 서버에 추가된 새 버전으로 자동 업그레이드됩니다.

브라우저에서 설치하려면 호드 대시보드에서 Server > Agents 메뉴 항목으로 이동하여 Download Agent 링크를 클릭합니다.

아니면 다음 명령을 사용하여 명령줄을 통해 에이전트를 다운로드할 수 있습니다. 여기에 참조된 AUTH-TOKEN 파라미터는 관리 사용자가 http://[HORDE-SERVER-URL]/account 페이지에 로그인하여 Get agent software download token 링크를 클릭하면 얻을 수 있습니다.

Windows(PowerShell)

    Invoke-WebRequest -Uri https://[HORDE-SERVER-URL]/api/v1/agentsoftware/default/zip -OutFile C:\Horde\HordeAgent.zip -Headers @{ 'Authorization' = 'Bearer [AUTH-TOKEN]' }
    Expand-Archive -LiteralPath C:\Horde\HordeAgent.zip -DestinationPath C:\Horde -Force
Copy full snippet

Invoke-WebRequest -Uri https://[HORDE-SERVER-URL]/api/v1/agentsoftware/default/zip -OutFile C:\Horde\HordeAgent.zip -Headers @{ 'Authorization' = 'Bearer [AUTH-TOKEN]' } Expand-Archive -LiteralPath C:\Horde\HordeAgent.zip -DestinationPath C:\Horde -Force

-Headers 파라미터 및 값은 인증되지 않은 서버 사용 시 필요하지 않습니다.

Mac 및 Linux

    curl https://[HORDE-SERVER-URL]/api/v1/agentsoftware/default/zip --output ~/Horde/HordeAgent.zip -H "Authorization: Bearer [AUTH-TOKEN]"
    unzip -o ~/Horde/HordeAgent.zip -d ~/Horde/
Copy full snippet

curl https://[HORDE-SERVER-URL]/api/v1/agentsoftware/default/zip --output ~/Horde/HordeAgent.zip -H "Authorization: Bearer [AUTH-TOKEN]" unzip -o ~/Horde/HordeAgent.zip -d ~/Horde/

-H 파라미터 및 값은 인증되지 않은 서버 사용 시 필요하지 않습니다.

구성

일반

에이전트 세팅은 Agent.json 파일을 통해 환경설정할 수 있습니다. Windows에서 이 파일은 C:\ProgramData\Epic\Horde\Agent\Agent.json 에 저장됩니다. 다른 플랫폼에서는 기본적으로 애플리케이션 디렉터리 하위의 Data 폴더에 저장됩니다. 이 파일의 세팅은 에이전트 실행 파일과 함께 배포된 appsettings.json 파일 상위에 적용됩니다.

모든 호드 관련 세팅은 최고 수준 키 horde 하위에, 미들웨어 및 표준 .NET 세팅은 다른 루트 키 하위에 저장됩니다.

서버 프로파일

ServerProfiles 프로퍼티를 통해 에이전트의 Agent.json 파일에 여러 호드 서버로 연결하기 위한 세팅을 포함할 수 있습니다. 여러 프로파일을 구성하면 여러 환경(예: 개발 vs. 프로덕션)에서 호드를 실행할 때 유용할 수 있으며, 각 서버 프로파일에는 이름, 서버 URL, 인증 토큰이 포함됩니다.

서버 프로파일은 이름으로 참조됩니다. 기본 프로파일은 Server 프로퍼티를 통해 환경설정하거나, 에이전트 실행 시 -Server=.. 명령줄 실행인자를 통해 환경설정합니다.

에이전트 디플로이를 스크립팅할 때 서버에서 호스팅하는 빌드에 기본적으로 원하는 환경설정이 포함되도록 수정하거나, 환경설정 파일을 다운로드한 후 에이전트의 SetServer 명령을 사용하여 환경설정 파일을 수정할 수 있습니다. 이 명령은 다음과 같이 호출할 수 있습니다.

    dotnet HordeAgent.dll SetServer -Name=.. -Url=.. -Token=...
Copy full snippet

dotnet HordeAgent.dll SetServer -Name=.. -Url=.. -Token=...

-Default 실행인자를 추가하면 기본적으로 이 서버가 사용되도록 환경설정됩니다. 사용 가능한 옵션의 전체 목록은 -Help 실행인자로 실행하세요.

등록

관리 사용자로 로그인한 상태에서 http://[HORDE-SERVER-URL]/account 페이지로 이동하면 Get agent registration token 링크가 포함되어 있습니다. 이 토큰은 기본 에이전트 환경설정 파일에 임베딩되거나 SetServer 명령으로 전달될 수 있습니다(위 내용 참고).

에이전트가 서버로 처음 연결되면, 고유한 연결 토큰을 자체적으로 생성합니다.

Windows에서 연결 토큰은 다음 위치에 저장됩니다.

	C:\Users[User]\AppData\Local\Epic Games\Horde\Agent\servers.json
Copy full snippet

C:\Users[User]\AppData\Local\Epic Games\Horde\Agent\servers.json

(일반 사용자 계정에서 실행하는 경우)

    C:\Windows\system32\config\systemprofile\AppData\Local\Epic Games\Horde\Agent\servers.json
Copy full snippet

C:\Windows\system32\config\systemprofile\AppData\Local\Epic Games\Horde\Agent\servers.json

(서비스로 실행하는 경우)

Mac/Linux에서 연결 토큰은 다음 위치에 저장됩니다.

    ~/.local/share/Horde.Agent/servers.json
Copy full snippet

~/.local/share/Horde.Agent/servers.json

서비스로 실행하기

Windows

MSI 인스톨러를 실행하면 호드 에이전트가 기본적으로 백그라운드 서비스로 실행되도록 환경설정됩니다. 서버에서 직접 에이전트를 다운로드하여 수동으로 환경설정하는 경우, 서비스는 다음 명령을 실행하여 등록할 수 있습니다.

    dotnet HordeAgent.dll service install [-UserName=..] [-Password=..]
Copy full snippet

dotnet HordeAgent.dll service install [-UserName=..] [-Password=..]

-UserName 및 -Password 는 서비스를 실행할 계정의 크리덴셜을 지정합니다.

서비스는 다음 명령을 사용하여 제거할 수 있습니다.

    dotnet HordeAgent.dll service uninstall
Copy full snippet

dotnet HordeAgent.dll service uninstall

Mac

Daemon 환경설정을 설명하는 /Library/LaunchAgents/epic.hordeagent.plist 파일을 생성합니다({{ HORDE_SERVICE_ACCOUNT }} 변수를 적절히 대체).

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>RunAtLoad</key>
        <true/>

        <key>ProgramArguments</key>
        <array>
            <string>/usr/local/bin/dotnet</string>
            <string>HordeAgent.dll</string>
            <string>service</string>
            <string>run</string>
            <string>-server=Prod</string>
            <string>-workingdir=/Users/{{ HORDE_SERVICE_ACCOUNT }}/Build</string>
        </array>

        <key>EnvironmentVariables</key>
        <dict>
            <key>PATH</key>
            <string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
        </dict>

        <key>GroupName</key>
        <string>admin</string>

        <key>WorkingDirectory</key>
        <string>/Users/{{ HORDE_SERVICE_ACCOUNT }}/Horde</string>

        <key>UserName</key>
        <string>{{ HORDE_SERVICE_ACCOUNT }}</string>

        <key>KeepAlive</key>
        <true/>

        <key>Label</key>
        <string>epic.hordeagent</string>

        <key>StandardErrorPath</key>
        <string>/Users/{{ HORDE_SERVICE_ACCOUNT }}/Library/Logs/hordeagent_error.log</string>

        <key>ExitTimeOut</key>
        <integer>10</integer>
    </dict>
    </plist>
Copy full snippet

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>RunAtLoad</key> <true/> <key>ProgramArguments</key> <array> <string>/usr/local/bin/dotnet</string> <string>HordeAgent.dll</string> <string>service</string> <string>run</string> <string>-server=Prod</string> <string>-workingdir=/Users/{{ HORDE_SERVICE_ACCOUNT }}/Build</string> </array> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string> </dict> <key>GroupName</key> <string>admin</string> <key>WorkingDirectory</key> <string>/Users/{{ HORDE_SERVICE_ACCOUNT }}/Horde</string> <key>UserName</key> <string>{{ HORDE_SERVICE_ACCOUNT }}</string> <key>KeepAlive</key> <true/> <key>Label</key> <string>epic.hordeagent</string> <key>StandardErrorPath</key> <string>/Users/{{ HORDE_SERVICE_ACCOUNT }}/Library/Logs/hordeagent_error.log</string> <key>ExitTimeOut</key> <integer>10</integer> </dict> </plist>

크기 제한을 초과한 /etc/newsyslog.conf 로그 파일을 다음과 같이 조정합니다(선택 사항).

    append '/Library/Logs/hordeagent_error.log 700 2 1000 * J'
Copy full snippet

append '/Library/Logs/hordeagent_error.log 700 2 1000 * J'

plist 외부에서 정의하려는 호드 에이전트 환경 변수를 다음과 같이 설정합니다(선택 사항).

    launchctl setenv Horde:WorkingDirectory {horde_working_directory}
Copy full snippet

launchctl setenv Horde:WorkingDirectory {horde_working_directory}

다음과 같이 Daemon을 실행합니다.

    launchctl load -w /Library/LaunchAgents/epic.hordeagent.plist
Copy full snippet

launchctl load -w /Library/LaunchAgents/epic.hordeagent.plist

Linux

에이전트 서비스를 실행할 사용자를 생성합니다. 언리얼 에디터는 Linux에서 루트로 실행될 수 없으므로, 호드 에이전트 서비스는 비루트 사용자로 실행되어야 합니다. 에이전트의 작업 디렉터리는 해당 사용자가 재귀적으로 소유해야 합니다. 사용자는 호드 에이전트를 재시작/셧다운/자동 스케일링하기 위해 sudo 액세스 권한이 있어야 합니다.

다음과 같이 /etc/systemd/system/horde-agent.service 에 서비스 디스크립터 파일을 생성합니다({{ HORDE_PATH }} , {{ HORDE_WORKING_DIRECTORY }} , {{ HORDE_SERVICE_ACCOUNT }} 변수를 적절히 대체).

    [Unit]
    Description=Horde Agent

    [Service]
    ExecStart=dotnet {{ HORDE_PATH }} -WorkingDir={{ HORDE_WORKING_DIRECTORY }}
    WorkingDirectory={{ HORDE_WORKING_DIRECTORY }}

    Restart=always
    RestartSec=5
    SyslogIdentifier=horde-agent

    StandardOutput=append:{{ HORDE_WORKING_DIRECTORY }}/log.txt
    StandardError=append:{{ HORDE_WORKING_DIRECTORY }}/err-log.txt

    User={{ HORDE_SERVICE_ACCOUNT }}

    [Install]
    WantedBy=multi-user.target
Copy full snippet

[Unit] Description=Horde Agent [Service] ExecStart=dotnet {{ HORDE_PATH }} -WorkingDir={{ HORDE_WORKING_DIRECTORY }} WorkingDirectory={{ HORDE_WORKING_DIRECTORY }} Restart=always RestartSec=5 SyslogIdentifier=horde-agent StandardOutput=append:{{ HORDE_WORKING_DIRECTORY }}/log.txt StandardError=append:{{ HORDE_WORKING_DIRECTORY }}/err-log.txt User={{ HORDE_SERVICE_ACCOUNT }} [Install] WantedBy=multi-user.target

다음과 같이 Daemon을 실행합니다.

    systemctl daemon-reload
Copy full snippet

systemctl daemon-reload

작업 디렉터리

에이전트에서 사용하는 데이터(Perforce 워크스페이스, 캐시, 스크래치 공간)의 기본 위치는 Windows의 경우 C:\ProgramData\HordeAgent 이며 Mac/Linux의 경우 애플리케이션 디렉터리입니다.

이 경로는 에이전트의Agent.json 파일에서 WorkingDir 프로퍼티를 사용하여 오버라이드할 수 있습니다.

에이전트가 디스크를 데이터로 채우는 런어웨이 작업에 영향을 받지 않도록 하려면 에이전트가 시스템 디스크 외의 드라이브에 데이터를 저장하도록 하는 것이 좋습니다. 또한 Windows에서 %TEMP% 및 %TMP% 환경 변수를 이 드라이브로 설정하는 것을 권장합니다.

네트워크 공유 마운트

에이전트의 Agent.json 파일에 있는 Shares 프로퍼티를 사용하면 에이전트가 작업에 착수하기 전에 시작 시 특정 네트워크 공유를 마운트하도록 환경설정할 수 있습니다.

GPU 액세스

호드에서 실행되는 특정 작업(특히 테스트)은 GPU에 액세스해야 합니다. 그러나 에이전트를 Windows 서비스로 실행하면 GPU에 액세스할 수 없습니다. 이 문제를 해결하기 위해 에이전트는 인터랙티브 세션에서 일반 Windows 사용자로 실행해야 합니다. 이는 다양한 방식으로 구현할 수 있는데, 데스크톱의 PowerShell 스크립트에서 에이전트를 실행하는 방법, NSSM과 같은 외부 툴을 사용하는 방법 등이 있습니다. 에이전트 프로세스가 예상치 못하게 종료되는 경우 재시작되게 하는 것이 중요합니다.

대부분의 에이전트는 GPU 액세스가 필요하지 않으므로 이 지원이 필요한 인터랙티브 에이전트만을 위한 별도의 풀을 생성하는 것이 좋습니다.

Linux 및 Wine

Wine은 Windows 애플리케이션이 Unix와 같은 시스템에서 실행되도록 활성화하는 호환성 레이어로, Linux의 에이전트는 Wine을 통해 원격 계산 작업을 실행할 수 있습니다. Windows 대신 Linux에서 워크로드를 실행하면 OS 부팅 시간이 빨라지고, 디스크 I/O 퍼포먼스가 개선되고, 라이선스 비용이 사라지는 등의 여러 이점이 있습니다.

Wine을 활성화하려면 wineExecutablePath 환경설정 옵션에서 wine64 에 대한 경로를 에이전트 세팅 문서에 설명된 대로 설정해야 합니다. Bash의 래퍼 스크립트는 Wine으로 전송된 모든 파라미터를 수정하는 데 사용할 수 있습니다. 이 경우 필수 파일 경로를 환경설정합니다. 빌드 실행 시 언리얼 빌드 툴에 대한 -UBAHordeAllowWine 플래그를 기본값이기도 한 true로 설정해야 합니다. 이러한 전제 조건이 충족되면 에이전트는 계산 작업 실행 시 Wine을 사용하려고 시도하며, 이를 통해 cl.exe , link.exe 와 같은 Windows 애플리케이션과의 호환성을 유지하는 한편 Linux에서 실행하는 데 따른 이점도 누릴 수 있습니다.

#!/bin/bash
# Wine을 위한 래퍼 스크립트로, 실행할 Windows 애플리케이션에서 들어오는 명령줄 실행인자를 수정하기 위한 후크 포인트를 제공합니다.
# 현재 이 스크립트는 UnrealBuildAccelerator(UBA)를 실행하는 원격 실행 작업에서 주로 호출됩니다.
export WINEDEBUG=-all
export WINEARCH=win64
export WINEPREFIX=/opt/horde/wine-data

# UE_HORDE_SHARED_DIR가 Wine 내부에 존재할 C:\를 가리키도록 덮어씁니다.
# 따라서 위에 지정된 WINEPREFIX 아래에 마운트됩니다.
export UE_HORDE_SHARED_DIR="C:\\Uba"

if [ -n "$${UE_HORDE_TERMINATION_SIGNAL_FILE}" ]; then
  # Linux 경로를 Wine으로/Wine에서 매핑하는 Z:\ 아래 Windows 경로로 다시 씁니다(슬래시를 백슬래시로 대체).
  export UE_HORDE_TERMINATION_SIGNAL_FILE="Z:$${UE_HORDE_TERMINATION_SIGNAL_FILE//\//\\}"
fi

/usr/local/bin/wine64 "$@"
Copy full snippet

#!/bin/bash # Wine을 위한 래퍼 스크립트로, 실행할 Windows 애플리케이션에서 들어오는 명령줄 실행인자를 수정하기 위한 후크 포인트를 제공합니다. # 현재 이 스크립트는 UnrealBuildAccelerator(UBA)를 실행하는 원격 실행 작업에서 주로 호출됩니다. export WINEDEBUG=-all export WINEARCH=win64 export WINEPREFIX=/opt/horde/wine-data # UE_HORDE_SHARED_DIR가 Wine 내부에 존재할 C:\를 가리키도록 덮어씁니다. # 따라서 위에 지정된 WINEPREFIX 아래에 마운트됩니다. export UE_HORDE_SHARED_DIR="C:\\Uba" if [ -n "$${UE_HORDE_TERMINATION_SIGNAL_FILE}" ]; then # Linux 경로를 Wine으로/Wine에서 매핑하는 Z:\ 아래 Windows 경로로 다시 씁니다(슬래시를 백슬래시로 대체). export UE_HORDE_TERMINATION_SIGNAL_FILE="Z:$${UE_HORDE_TERMINATION_SIGNAL_FILE//\//\\}" fi /usr/local/bin/wine64 "$@"