Installer un serveur Horde pour Unreal Engine (Windows, Linux, Mac)
Publié : 16 sept. 2025, 09:25
Présentation, installation et parametrage d'un serveur Horde pour Unreal Engine.
Installation
Windows : Programme d'installation MSI
Les versions Windows de MongoDB et Redis sont incluses dans le programme d'installation et lancées par Horde au démarrage (Horde les fermera également à la fin de son exécution). Cette installation convient pour les installations à petite échelle et pour tester Horde, mais il est préférable d'héberger les bases de données séparément dans les scénarios de production.
Linux : Docker
Les images pour héberger Horde via Docker sont disponibles via l'organisation Epic Games sur GitHub. Notez que vous devez être connecté à GitHub avec un compte associé à un compte Epic Games.
https://github.com/orgs/EpicGames/packages/container/package/horde-server
Pour télécharger une image, créez d'abord un jeton d'accès personnel GitHub (PAT) à partir de la section développeur de la page des paramètres de votre compte et transmettez-le comme mot de passe à :
Pour télécharger l'image:
Notez que dans ce formulaire, une instance externe MongoDB et Redis doit être configurée via un fichier de configuration ou une variable d'environnement (voir ci-dessous). L'exécution de plusieurs serveurs Horde derrière un équilibreur de charge ne nécessite pas de configuration explicite tant que chaque serveur pointe vers la même instance MongoDB et Redis.
Linux : Docker Compose
Docker Compose simplifie la configuration d'une installation basée sur Docker en fournissant un groupe préconfiguré de conteneurs Docker, qui comprend des instances de MongoDB et Redis.
Tout comme le programme d'installation MSI, cette méthode convient pour tester Horde ou le déployer dans des environnements à petite échelle. Pour accéder aux images précompilées, reportez-vous à la section Docker ci-dessus. La configuration Docker Compose nécessaire se trouve dans le fichier Engine/Source/Programs/Horde.Server/docker-compose.yml
À partir du même répertoire, démarrez les conteneurs avec :
Pour plus d'informations, consultez les commentaires dans le fichier YAML.
Mac : Homebrew
Nous ne fournissons pas de binaires précompilés pour exécuter le serveur sur Mac, mais il est relativement simple d'installer tous les prérequis à l'aide de Homebrew.
1. Installez le SDK .NET 8.
2. Installez MongoDB.
Installez Redis.
4. Lancez Horde.
Les variables d'environnement ci-dessous utilisent la syntaxe ASP.NET standard ; vous pouvez modifier les valeurs dans server.json si vous préférez.
Compilation à partir du code source
Le code source du serveur Horde se trouve dans Engine/Source/Programs/Horde/Horde.Server/....
Vous pouvez compiler et exécuter le serveur à partir de Visual Studio à l'aide de la solution située dans Engine/Source/Programs/Horde/Horde.sln, ou à partir de la ligne de commande via les commandes dotnet build ou dotnet publish.
Les images Docker peuvent être compilées à l'aide du script BuildGraph situé dans Engine/Source/Programs/Horde/BuildHorde.xml, en utilisant le fichier Dockerfile situé dans Engine/Source/Programs/Horde.Server/Dockerfile.
Il est recommandé d'utiliser le script BuildGraph plutôt que d'exécuter directement le fichier Dockerfile, car il place les fichiers pertinents dans un répertoire temporaire avant d'exécuter docker build, ce qui empêche le démon Docker de copier l'arborescence source UE entière dans l'environnement conteneurisé avant la construction.
La ligne de commande pour construire des images Docker à l'aide de BuildGraph est la suivante :
Le programme d'installation Windows peut être créé à partir du même script BuildGraph avec une ligne de commande similaire :
Paramètres
Généralités
Les paramètres du serveur sont configurés via le fichier Server.json. Sous Windows, ce fichier est stocké dans C:\ProgramData\Epic\Horde\Server\Server.json. Sur les autres plateformes, il est stocké par défaut dans le dossier Data sous le répertoire de l'application. Les paramètres de ce fichier s'appliquent en plus de ceux du fichier appsettings.json distribué avec l'exécutable du serveur.
Tous les paramètres spécifiques à Horde sont stockés sous la clé de niveau supérieur Horde, les paramètres middleware et .NET standard se trouvant sous d'autres clés racines.
En tant qu'application ASP.NET, la configuration de l'application Horde prend en charge les fonctionnalités suivantes :
- Les propriétés individuelles peuvent être remplacées par des variables d'environnement à l'aide de la syntaxe ASP.NET standard (voir MSDN). Par exemple, la chaîne de connexion à la base de données peut être transmise à l'aide de la variable d'environnement Horde__MongoConnectionString.
- L'environnement de déploiement peut être configuré à l'aide de la variable d'environnement ASPNETCORE_ENVIRONMENT. Les valeurs standard pour Horde sont Production, Development et Local.
- Un fichier de configuration spécifique au déploiement peut être créé sous le nom appsettings.{Environment}.json (par exemple appsettings.Local.json), qui sera fusionné avec d'autres paramètres.
Notez que les fichiers de configuration du serveur (Server.json, appsettings.json, etc.) diffèrent du fichier de configuration global (globals.json). Le fichier de configuration du serveur est déployé avec le serveur. Il contient les paramètres de déploiement/d'infrastructure, tandis que le fichier de configuration global peut être stocké dans le contrôle de révision et mis à jour dynamiquement pendant la durée de vie du serveur. Voir Config > Orientation pour plus d'informations.
MongoDB
La chaîne de connexion MongoDB peut être spécifiée via la propriété MongoConnectionString dans le fichier Server.json ou la variable d'environnement Horde__MongoConnectionString. La chaîne de connexion doit respecter la syntaxe standard MongoDB, par exemple :
Horde implémente de nombreuses opérations sous forme d'opérations de comparaison et d'échange. Il est donc important que toutes les lectures soient configurées pour utiliser l'instance de base de données principale à l'aide de l'argument readPreference=primary lors de l'utilisation d'un ensemble de répliques. L'utilisation d'une instance secondaire pour les lectures peut entraîner des blocages, car le serveur obtient des documents obsolètes dans un cycle de lecture-modification-écriture.
La connexion MongoDB peut être configurée pour utiliser un ensemble de certificats fiables via la propriété MongoPublicCertificate. Par exemple, lors de l'exécution sur AWS à l'aide de DocumentDB, cette propriété peut être définie pour utiliser le bundle de certificats combinés d'Amazon en plaçant le fichier global-bundle.pem dans le répertoire d'application du serveur.
Redis
Le serveur Redis est configuré via la propriété RedisConnectionConfig dans le fichier Server.json ou via la variable d'environnement Horde__MongoConnectionString. Cette chaîne est formatée comme un serveur et un port simples, par exemple :
Ports
Par défaut, Horde est configuré pour servir les données via HTTP non crypté en utilisant le port 5000. Les agents communiquent avec le serveur Horde en utilisant gRPC via HTTP/2 non crypté sur le port 5002 par défaut. Ces paramètres sont affichés sur la console lors du démarrage du serveur.
Un port distinct est utilisé pour gRPC, car Kestrel (le serveur web .NET) ne prend pas en charge le trafic HTTP/2 non crypté sur le même port que le trafic HTTP/1. Ce port distinct pour le trafic HTTP/2 non TLS peut être utile lorsque Horde est placé derrière un proxy inverse. Si un port HTTPS est configuré, tout le trafic peut utiliser ce port.
Les paramètres d'utilisation des ports sont définis dans Server.json :
- Pour désactiver la transmission de données via HTTP, définissez la propriété HttpPort sur zéro.
- Pour configurer le port HTTP/2 secondaire utilisé, définissez la propriété Http2Port (ou définissez-la sur zéro pour la désactiver).
HTTPS
Pour servir des données via HTTPS, définissez la propriété HttpsPort dans le fichier Server.json.
Configurez le certificat pour Kestrel (le serveur Web NET Core) en définissant le certificat par défaut dans le même fichier.
Multiplateforme :
Windows (à l'aide du magasin de certificats système) :
> L'objet Kestrel doit être ajouté à la racine du fichier, et non à l'intérieur de l'objet Horde.
D'autres méthodes de configuration des certificats pour Kestrel sont répertoriées sur MSDN.
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-8.0#configure-https
Le trafic HTTP/1.1 et HTTP/2.0 peut être pris en charge via le port HttpsPort. Le trafic non chiffré peut être désactivé en définissant HttpPort et Http2Port sur zéro.
Il arrive que le serveur fournisse des liens vers lui-même (le document de découverte OIDC utilisé lors de l'utilisation du système de compte interne de Horde, par exemple), et il est important que ces URL correspondent au certificat HTTPS. Par défaut, cette URL est dérivée du nom DNS déclaré du serveur, mais elle peut être remplacée par la propriété ServerUrl.
Pour configurer un certificat auto-signé à des fins de test, consultez la section Tutoriels > Certificats auto-signés.
Surveillance
Horde utilise Serilog pour la journalisation et est configuré pour générer des fichiers journaux en texte brut et JSON dans le répertoire de l'application sous Linux et dans le dossier C:\ProgramData\HordeServer sous Windows. La sortie en texte brut est écrite par défaut dans stdout, mais la sortie Json peut être activée à l'aide de la propriété LogJsonToStdOut dans Server.json.
Les données de profilage et de télémétrie pour le serveur sont acheminées via OpenTelemetry. Les paramètres de capture de télémétrie sont répertoriés ici.
Modes d'exécution
Afin de séparer le trafic de requêtes plus léger des opérations d'arrière-plan plus lourdes, le serveur Horde peut être configuré pour fonctionner dans différents modes d'exécution. Vous pouvez les configurer via le paramètre RunMode.
Authentification
Horde prend en charge OpenID Connect (OIDC) pour l'authentification à l'aide d'un fournisseur d'identité externe. OIDC est une norme d'authentification largement utilisée, et Okta, AWS, Azure, Google, Facebook et bien d'autres implémentent des fournisseurs d'identité compatibles avec celle-ci.
La page Démarrage > Authentification explique comment configurer le système de compte interne de Horde et le fournisseur OIDC.
Les paramètres suivants dans Server.json sont nécessaires pour configurer un fournisseur OIDC externe :
- AuthMethod : définissez cette option sur OpenIdConnect.
- OidcAuthority : URL de l'autorité OIDC. Vous pouvez vérifier que l'URL spécifiée ici est correcte en accédant à {{Url}}/.well-known/openid-configuration dans un navigateur, ce qui devrait renvoyer le document de découverte OIDC.
- OidcClientId : identifie l'application (Horde) auprès du fournisseur OIDC. Elle est générée par le fournisseur OIDC.
- OidcClientSecret : valeur secrète fournie par le fournisseur OIDC pour identifier l'application qui demande l'autorisation.
En outre, les paramètres suivants peuvent être spécifiés :
- OidcRequestedScopes : spécifie les champs d'application demandés au fournisseur OIDC. Les champs d'application déterminent l'accès que Horde demande au fournisseur OIDC et les revendications qui seront renvoyées et disponibles pour vérification dans les ACL Horde. La signification de ces valeurs est spécifique à la configuration de votre fournisseur OIDC.
- OidcClaimNameMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez d'afficher le nom réel d'un utilisateur.
- OidcClaimEmailMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez d'afficher l'adresse e-mail d'un utilisateur.
- OidcClaimHordePerforceUserMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez de déterminer le nom d'utilisateur Perforce d'un utilisateur.
Consultez Config > Permissions pour connaître les autres options d'authentification.
Référence
Pour obtenir la liste complète des propriétés valides dans le fichier de configuration du serveur, consultez Server.json (Serveur).
https://dev.epicgames.com/documentation/en-us/unreal-engine/horde-settings-for-unreal-engine#serversettings
Installation
Windows : Programme d'installation MSI
Les versions Windows de MongoDB et Redis sont incluses dans le programme d'installation et lancées par Horde au démarrage (Horde les fermera également à la fin de son exécution). Cette installation convient pour les installations à petite échelle et pour tester Horde, mais il est préférable d'héberger les bases de données séparément dans les scénarios de production.
Linux : Docker
Les images pour héberger Horde via Docker sont disponibles via l'organisation Epic Games sur GitHub. Notez que vous devez être connecté à GitHub avec un compte associé à un compte Epic Games.
https://github.com/orgs/EpicGames/packages/container/package/horde-server
Pour télécharger une image, créez d'abord un jeton d'accès personnel GitHub (PAT) à partir de la section développeur de la page des paramètres de votre compte et transmettez-le comme mot de passe à :
Code : Tout sélectionner
docker login ghcr.ioCode : Tout sélectionner
docker pull ghcr.io/epicgames/horde-server:latestLinux : Docker Compose
Docker Compose simplifie la configuration d'une installation basée sur Docker en fournissant un groupe préconfiguré de conteneurs Docker, qui comprend des instances de MongoDB et Redis.
Tout comme le programme d'installation MSI, cette méthode convient pour tester Horde ou le déployer dans des environnements à petite échelle. Pour accéder aux images précompilées, reportez-vous à la section Docker ci-dessus. La configuration Docker Compose nécessaire se trouve dans le fichier Engine/Source/Programs/Horde.Server/docker-compose.yml
À partir du même répertoire, démarrez les conteneurs avec :
Code : Tout sélectionner
docker compose upMac : Homebrew
Nous ne fournissons pas de binaires précompilés pour exécuter le serveur sur Mac, mais il est relativement simple d'installer tous les prérequis à l'aide de Homebrew.
1. Installez le SDK .NET 8.
Code : Tout sélectionner
brew install dotnet-sdkCode : Tout sélectionner
brew tap mongodb/brew
brew update
brew install mongodb-community
brew services start mongodb-communityCode : Tout sélectionner
brew install redis
brew services start redisLes variables d'environnement ci-dessous utilisent la syntaxe ASP.NET standard ; vous pouvez modifier les valeurs dans server.json si vous préférez.
Code : Tout sélectionner
export Horde__MongoConnectionString=mongodb://localhost:27017 e
xport Horde__HttpPort=37107
export Horde__Http2Port=37109
cd Engine/Source/Programs/Horde/Horde.Server
dotnet runCompilation à partir du code source
Le code source du serveur Horde se trouve dans Engine/Source/Programs/Horde/Horde.Server/....
Vous pouvez compiler et exécuter le serveur à partir de Visual Studio à l'aide de la solution située dans Engine/Source/Programs/Horde/Horde.sln, ou à partir de la ligne de commande via les commandes dotnet build ou dotnet publish.
Les images Docker peuvent être compilées à l'aide du script BuildGraph situé dans Engine/Source/Programs/Horde/BuildHorde.xml, en utilisant le fichier Dockerfile situé dans Engine/Source/Programs/Horde.Server/Dockerfile.
Il est recommandé d'utiliser le script BuildGraph plutôt que d'exécuter directement le fichier Dockerfile, car il place les fichiers pertinents dans un répertoire temporaire avant d'exécuter docker build, ce qui empêche le démon Docker de copier l'arborescence source UE entière dans l'environnement conteneurisé avant la construction.
La ligne de commande pour construire des images Docker à l'aide de BuildGraph est la suivante :
Code : Tout sélectionner
RunUAT.bat BuildGraph -Script=Engine/Source/Programs/Horde/BuildHorde.xml -Target="Build HordeServer"Code : Tout sélectionner
RunUAT.bat BuildGraph -Script=Engine/Source/Programs/Horde/BuildHorde.xml -Target="Build Horde Installer"Paramètres
Généralités
Les paramètres du serveur sont configurés via le fichier Server.json. Sous Windows, ce fichier est stocké dans C:\ProgramData\Epic\Horde\Server\Server.json. Sur les autres plateformes, il est stocké par défaut dans le dossier Data sous le répertoire de l'application. Les paramètres de ce fichier s'appliquent en plus de ceux du fichier appsettings.json distribué avec l'exécutable du serveur.
Tous les paramètres spécifiques à Horde sont stockés sous la clé de niveau supérieur Horde, les paramètres middleware et .NET standard se trouvant sous d'autres clés racines.
En tant qu'application ASP.NET, la configuration de l'application Horde prend en charge les fonctionnalités suivantes :
- Les propriétés individuelles peuvent être remplacées par des variables d'environnement à l'aide de la syntaxe ASP.NET standard (voir MSDN). Par exemple, la chaîne de connexion à la base de données peut être transmise à l'aide de la variable d'environnement Horde__MongoConnectionString.
- L'environnement de déploiement peut être configuré à l'aide de la variable d'environnement ASPNETCORE_ENVIRONMENT. Les valeurs standard pour Horde sont Production, Development et Local.
- Un fichier de configuration spécifique au déploiement peut être créé sous le nom appsettings.{Environment}.json (par exemple appsettings.Local.json), qui sera fusionné avec d'autres paramètres.
Notez que les fichiers de configuration du serveur (Server.json, appsettings.json, etc.) diffèrent du fichier de configuration global (globals.json). Le fichier de configuration du serveur est déployé avec le serveur. Il contient les paramètres de déploiement/d'infrastructure, tandis que le fichier de configuration global peut être stocké dans le contrôle de révision et mis à jour dynamiquement pendant la durée de vie du serveur. Voir Config > Orientation pour plus d'informations.
MongoDB
La chaîne de connexion MongoDB peut être spécifiée via la propriété MongoConnectionString dans le fichier Server.json ou la variable d'environnement Horde__MongoConnectionString. La chaîne de connexion doit respecter la syntaxe standard MongoDB, par exemple :
Code : Tout sélectionner
mongodb://username:password@host:27017?replicaSet=rs0&readPreference=primaryLa connexion MongoDB peut être configurée pour utiliser un ensemble de certificats fiables via la propriété MongoPublicCertificate. Par exemple, lors de l'exécution sur AWS à l'aide de DocumentDB, cette propriété peut être définie pour utiliser le bundle de certificats combinés d'Amazon en plaçant le fichier global-bundle.pem dans le répertoire d'application du serveur.
Redis
Le serveur Redis est configuré via la propriété RedisConnectionConfig dans le fichier Server.json ou via la variable d'environnement Horde__MongoConnectionString. Cette chaîne est formatée comme un serveur et un port simples, par exemple :
Code : Tout sélectionner
127.0.0.1:6379Ports
Par défaut, Horde est configuré pour servir les données via HTTP non crypté en utilisant le port 5000. Les agents communiquent avec le serveur Horde en utilisant gRPC via HTTP/2 non crypté sur le port 5002 par défaut. Ces paramètres sont affichés sur la console lors du démarrage du serveur.
Un port distinct est utilisé pour gRPC, car Kestrel (le serveur web .NET) ne prend pas en charge le trafic HTTP/2 non crypté sur le même port que le trafic HTTP/1. Ce port distinct pour le trafic HTTP/2 non TLS peut être utile lorsque Horde est placé derrière un proxy inverse. Si un port HTTPS est configuré, tout le trafic peut utiliser ce port.
Les paramètres d'utilisation des ports sont définis dans Server.json :
- Pour désactiver la transmission de données via HTTP, définissez la propriété HttpPort sur zéro.
- Pour configurer le port HTTP/2 secondaire utilisé, définissez la propriété Http2Port (ou définissez-la sur zéro pour la désactiver).
HTTPS
Pour servir des données via HTTPS, définissez la propriété HttpsPort dans le fichier Server.json.
Configurez le certificat pour Kestrel (le serveur Web NET Core) en définissant le certificat par défaut dans le même fichier.
Multiplateforme :
Code : Tout sélectionner
"Kestrel": {
"Certificates": { "
Default": {
"Path": "C:\\cert\\test.pfx",
"Password": "my-password"
}
}
}Code : Tout sélectionner
"Kestrel": {
"Certificates": {
"Default":
{
"Subject": "my-domain.com",
// Use the 'Personal' certificate store on the local machine
"Store": "My",
"Location": "LocalMachine"
}
}
}D'autres méthodes de configuration des certificats pour Kestrel sont répertoriées sur MSDN.
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-8.0#configure-https
Le trafic HTTP/1.1 et HTTP/2.0 peut être pris en charge via le port HttpsPort. Le trafic non chiffré peut être désactivé en définissant HttpPort et Http2Port sur zéro.
Il arrive que le serveur fournisse des liens vers lui-même (le document de découverte OIDC utilisé lors de l'utilisation du système de compte interne de Horde, par exemple), et il est important que ces URL correspondent au certificat HTTPS. Par défaut, cette URL est dérivée du nom DNS déclaré du serveur, mais elle peut être remplacée par la propriété ServerUrl.
Pour configurer un certificat auto-signé à des fins de test, consultez la section Tutoriels > Certificats auto-signés.
Surveillance
Horde utilise Serilog pour la journalisation et est configuré pour générer des fichiers journaux en texte brut et JSON dans le répertoire de l'application sous Linux et dans le dossier C:\ProgramData\HordeServer sous Windows. La sortie en texte brut est écrite par défaut dans stdout, mais la sortie Json peut être activée à l'aide de la propriété LogJsonToStdOut dans Server.json.
Les données de profilage et de télémétrie pour le serveur sont acheminées via OpenTelemetry. Les paramètres de capture de télémétrie sont répertoriés ici.
Modes d'exécution
Afin de séparer le trafic de requêtes plus léger des opérations d'arrière-plan plus lourdes, le serveur Horde peut être configuré pour fonctionner dans différents modes d'exécution. Vous pouvez les configurer via le paramètre RunMode.
Authentification
Horde prend en charge OpenID Connect (OIDC) pour l'authentification à l'aide d'un fournisseur d'identité externe. OIDC est une norme d'authentification largement utilisée, et Okta, AWS, Azure, Google, Facebook et bien d'autres implémentent des fournisseurs d'identité compatibles avec celle-ci.
La page Démarrage > Authentification explique comment configurer le système de compte interne de Horde et le fournisseur OIDC.
Les paramètres suivants dans Server.json sont nécessaires pour configurer un fournisseur OIDC externe :
- AuthMethod : définissez cette option sur OpenIdConnect.
- OidcAuthority : URL de l'autorité OIDC. Vous pouvez vérifier que l'URL spécifiée ici est correcte en accédant à {{Url}}/.well-known/openid-configuration dans un navigateur, ce qui devrait renvoyer le document de découverte OIDC.
- OidcClientId : identifie l'application (Horde) auprès du fournisseur OIDC. Elle est générée par le fournisseur OIDC.
- OidcClientSecret : valeur secrète fournie par le fournisseur OIDC pour identifier l'application qui demande l'autorisation.
En outre, les paramètres suivants peuvent être spécifiés :
- OidcRequestedScopes : spécifie les champs d'application demandés au fournisseur OIDC. Les champs d'application déterminent l'accès que Horde demande au fournisseur OIDC et les revendications qui seront renvoyées et disponibles pour vérification dans les ACL Horde. La signification de ces valeurs est spécifique à la configuration de votre fournisseur OIDC.
- OidcClaimNameMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez d'afficher le nom réel d'un utilisateur.
- OidcClaimEmailMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez d'afficher l'adresse e-mail d'un utilisateur.
- OidcClaimHordePerforceUserMapping : spécifie une liste de revendications à vérifier, par ordre de préférence, lorsque vous essayez de déterminer le nom d'utilisateur Perforce d'un utilisateur.
Consultez Config > Permissions pour connaître les autres options d'authentification.
Référence
Pour obtenir la liste complète des propriétés valides dans le fichier de configuration du serveur, consultez Server.json (Serveur).
https://dev.epicgames.com/documentation/en-us/unreal-engine/horde-settings-for-unreal-engine#serversettings