# Deployments Learn about deployments and their lifecycle - concepts and best practices for deeper understanding. ## 🗺️ Orchestration Start new servers within seconds to meet capacity demands with our cloud native edge computing approach. We treat servers as [cattle rather than pets](https://cloudscaling.com/blog/cloud-computing/the-history-of-pets-vs-cattle/) - replacing faulty instances entirely instead of nursing each one manually. {% hint style="info" %} Your orchestration choice will **impact your devops cost, server cost, and scalability**. {% endhint %} {% hint style="success" %} [Reach out in Discord](https://discord.gg/MmJf8fWjnt) to learn about hybrid orchestration options and optimizing your hosting cost. {% endhint %} To fully understand all pros and cons, let’s compare various orchestration methods. ### Match-Bound Golden standard for modern studios providing the **easiest integration with best cost efficiency**. 👍 **Advantages** * Best cost efficiency - scaling in real time to meet player demand minute by minute. * Lowest devops cost due to region-less hosting, Edgegap automates 99% of tasks. * Lowest ping due to 615+ sites in Edgegap’s public cloud infrastructure. * Fastest scale up (burst-ability) in case of unexpected traffic spike. * Highest standard of security and player cheating prevention (server authority). * Minimal impact of unexpected server crash on players, only affecting a single match. 👎 **Disadvantages** * Adopting a new orchestration mental model requires some ramp up effort initially. * Servers running longer than 24 hours will be automatically terminated. 🧩 **Best Suited For** * Latency-sensitive games - **when netcode optimization can't overcome high ping:** * First Person Shooters, Fighting Games, VR & XR (virtual and extended reality), … * Games with an **upper limit on match duration by design**, * Battle Royale, PvPvE[^1], Coop Shooters, MOBA, Sports Games, ARPGs & Dungeon Crawlers, … 🔎 **Discoverability** * Start new games when sufficient players join [matchmaking](https://docs.edgegap.com/learn/matchmaking "mention"). * Add players to [replace leavers in existing matches with backfill](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#backfill). * Let players browse servers and pick from a list with [server-browser](https://docs.edgegap.com/learn/server-browser "mention"). * [Implement custom or third party game backend to discover servers](https://docs.edgegap.com/advanced-features/managed-clusters#nakama-by-heroic-labs). {% hint style="info" %} Edgegap automatically scales all 615+ server locations up/down based on player activity in each region. Prepare for success - seamlessly [scale to 14 million concurrent users in 60 minutes](https://edgegap.com/resources/performance-benchmark). {% endhint %} ### Regional Standby Traditional model for **persistent worlds with user-generated content and social MMO games**. 👍 **Advantages** * Familiar and easy to understand, old-school approach for battle-scarred veterans. * Highest standard of security and player cheating prevention (server authority). * Easily predictable cost based on monthly commitment. 👎 **Disadvantages** * Higher hosting cost - each region requires one or more idle standby servers (burst capacity). * Higher devops cost - scaling, operations, and maintenance duplicated per region. * Regions with smaller player base experience high ping due to joining servers far away. 🧩 **Best Suited For** * Persistent worlds with user-generated content stored on server even when players go offline. * MMOs, Sandboxes with base building or object placement, Extraction Shooters, ... * latency-tolerant games - **when server authoritative real-time physics aren’t required**: * mobile games, Coop Games, TCGs/CCGs, Turn-Based Strategies, … * Asynchronous multiplayer, **where server crashes have minimal impact on player experience:** * race against ghosts, loot enemy base, timer-based building/farming games, … * applications with heavy initialization process - when preparing servers takes minutes. 🔎 **Discoverability** * Let players browse servers and pick from a list with [server-browser](https://docs.edgegap.com/learn/server-browser "mention"). * [Implement custom or third party game backend to discover servers](https://docs.edgegap.com/advanced-features/managed-clusters#nakama-by-heroic-labs). {% hint style="info" %} See [managed-clusters](https://docs.edgegap.com/learn/advanced-features/managed-clusters "mention") for **self-hosting your microservices and backend services** on Edgegap. {% endhint %} ### Peer to Peer Shift development efforts from ~~dedicated servers~~ to **relay netcode for non-competitive games**. Related topics: listen servers, player-host authority, NAT punch-through. 👍 **Advantages** * Lowest hosting cost, requiring only Relay servers to solve NAT punch-through. * Lowest devops cost - maintenance required only for client builds and distribution channels. * Minimal impact of unexpected server crash on players, only affecting a single match. * Easy to implement and fast time to prototype, without any backend development required. 👎 **Disadvantages** * Increased peer-to-peer netcode development effort requiring concurrent programming skills. * Worst ping times and most sensitive to unfavorable network conditions (e.g. mobile internet). * Weakest security, vulnerable to man-in-the-middle attacks and session hijacking. * Risk dropping sessions when host leaves unless you implement custom host migration. 🧩 **Best Suited For** * Coop & casual games - **when cheating doesn’t take away from fun or break the game**, * Kids Games, Exploration Games, Adventures, … 🔎 **Discoverability** * [Implement custom or third party game backend to discover servers](https://docs.edgegap.com/advanced-features/managed-clusters#nakama-by-heroic-labs). {% hint style="success" %} See our [Distributed Relays](https://docs.edgegap.com/docs/distributed-relay-manager) for service enabling peer to peer with best in class latency and security. {% endhint %} ## 📍 Server Placement No matter which orchestration method you choose, picking the right server location for a group of players is critical in ensuring the best possible ping, and optimal player experience. Learn about different strategies for server placement, and how they impact your players. {% hint style="info" %} Your server placement strategy will **impact your players’ experience, retention, and your game reviews**. {% endhint %} {% hint style="success" %} **Edgegap deploys in the** [**best possible location**](#server-score) **with available capacity**, for fast and low-latency matches. {% endhint %}
{% hint style="info" %} See [#deployment-balance-points](#deployment-balance-points "mention") to **analyze server placement in real time**, at scale. {% endhint %} ### Server Score Server score strategy uses Edgegap’s patented methodology, which **optimizes placement of servers for each match individually**. Performs non-intrusive telemetry to approximate each player’s network proximity to our server locations and choose the server which delivers best: * **responsiveness** - provides lowest ping for all players on average, * **fairness** - provides a balanced and fair ping for all players. {% hint style="success" %} Our [Matchmaker](https://docs.edgegap.com/learn/matchmaking) uses **Server Score strategy by default, to ensure best possible experience**. To use this strategy with [Deploy APIs](https://docs.edgegap.com/api/#tag/Deployments), input players’ public IPs or geo coordinates in your deploy request. {% endhint %} **Unresponsive placement** - server is far away, high ping for all players:
**Unfair placement** - uneven ping, one player is at a disadvantage:
**Good placement example** - responsive and fair ping for all players:
{% hint style="info" %} This strategy is **especially effective for hosting a group of players far away from each other** (North America vs. Europe, or West coast vs. East coast), frequently the case with pre-made lobbies. {% endhint %} ### Geolocation Alternatively, **provide players' latitude & longitude coordinates or coordinates of a preferred server location** instead of leveraging automated telemetry. This approach requires additional client-side geo-lookup implementation, fully relying on game developer’s solution. {% hint style="warning" %} Geolocation strategy is not recommended for [#match-bound](#match-bound "mention") orchestration, except for applications with strict regulatory requirements for inter-regional data transfers, or when player IP is unavailable. {% endhint %} {% hint style="success" %} To use this strategy with [Deploy APIs](https://docs.edgegap.com/api/#tag/Deployments), list players’ public IPs or geo coordinates in your deploy request. {% endhint %} ### Region Lock Servers may be placed using a crudely generalized region parameter, either: * automatically chosen for the player, based on their metadata (player account database), or * selected by the player during matchmaking, allowing placement with high client-server latency. {% hint style="danger" %} **Using this strategy alone is not recommended as it may result in poor network performance.** {% endhint %} {% hint style="success" %} Using **region selection as a pre-filter in combination with another strategy** is a better alternative. {% endhint %} ## 🟢 Connection Quality Some games (and some players) are more sensitive to latency or lag than others. While player reports are a great indicator of incidents or regression bugs at scale, **players may lack deep understanding of networking concepts** and are quick to assign blame to studios, netcode, or servers. Root cause of some issues may be hidden from players, so cooperation of studio and hosting provider may be crucial. **Edgegap’s priority is always to provide the best possible service.** If you’re receiving numerous player reports, experiencing widespread outages, or repeated issues, please reach out to us immediately through a support ticket in our platform. {% hint style="info" %} If you need help, [please reach out to us over Discord](https://discord.gg/MmJf8fWjnt). For live games support see our [ticketing system](https://edgegap.atlassian.net/servicedesk/customer/portal/3). {% endhint %} #### Low Latency Player latency is a combination of latency from transferring data between: * **physical devices -** the physical signal travelling across [Internet networking topology](https://en.wikipedia.org/wiki/Internet#Routing), * **host to host** - resulting from protocol, transport, and security measures, * **process to process** - resulting from (un)boxing and processing data in client/server. Edgegap reduces physical latency by placing servers closer to your players for shorter responses and lower number of network hops. With locations across 17 cloud and bare metal providers, you get **best-in-class ping for players anywhere in the world**. Server and internet coverage globally (not only with Edgegap) is limited due to factors like: * **infrastructure availability** - internet connection quality in a given region may not be sufficient, * **natural factors** - highly complex server racks require mostly stable environment. #### High Availability Availability of servers in various locations around the world will vary over time, changing multiple times throughout the day. Edgegap automatically **scales up/down** locations **on demand**, considering: * **burst traffic** - deployments made within a 15 minute period, * **vCPU requirements** - more vCPU per deployment increases overall demand for specific location, * **provider offering** - some remote locations have less provider options available, * **machine availability** - some locations may only offer 4 vCPU or 8 vCPU machines, * **studio requests** for testing, quality assurance, early access, closed betas, or tournaments. All applications' deploy requests are combined to assess location demand. All organizations have equal allocation priority by default, with the **possibility to add private server pools for enterprise customers requiring specific hardware or locations**. {% hint style="success" %} Please **reach out to us to plan a release**, or if you have any requests regarding location availability. {% endhint %} #### Player Issue Resolution Player issues may be rooted in server bugs or provider incidents, but may also arise from third parties such as local ISPs, game services, bugs in low level libraries, infrastructure providers, or other sources. When troubleshooting player reports or incidents, consider factors: * **matchmaking quality** - players should be close to each other (same region) for [#server-placement](#server-placement "mention") to yield best results: * see [matchmaking](https://docs.edgegap.com/learn/matchmaking "mention") and [ping-beacons](https://docs.edgegap.com/learn/orchestration/ping-beacons "mention") for our recommendations, * see [#player-tracing](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#player-tracing "mention") to learn how to find server logs related to player reports, * **regional issues:** * localized Internet Service Providers (ISPs) may be resolving an incident momentarily, * some regions (e.g. China, Russia) may be restricted due to localized sanctions, * **caching level** - Edgegap will prioritize fast deployments in cached locations: * [activate caching to deploy your servers within seconds](https://docs.edgegap.com/learn/application-and-versions#other-parameters-optional), * **maximum time to deploy** - deployments may fail due to slow and heavy initialization process: * see [#safety-guardrails](https://docs.edgegap.com/learn/application-and-versions#safety-guardrails "mention") to increase the timeout period, * delay initialization steps until absolutely necessary, * **server image or integration issues**. {% hint style="success" %} **Display deployment IDs in client match history UI** to trace player reports when troubleshooting. {% endhint %} {% hint style="info" %} Notify users about widespread bugs, temporary issues, and outages to mitigate negative sentiment. {% endhint %} ## 🔄 Deployment Lifecycle Edgegap deployments go through several lifecycle stages, denoted by deployment status. #### 1. Start a Deployment A deployment for **testing purposes** may be started with: * [unreal-engine](https://docs.edgegap.com/unreal-engine "mention") - Docker Extension or plugin for Unreal Engine projects, * [unity](https://docs.edgegap.com/unity "mention") - plugin for Unity projects, * [Dashboard Web UI](https://app.edgegap.com/deployment-management/deployments/list) - easy to use web interface for testing server integration. A deployment for **live production environment** should be started with: * [matchmaking](https://docs.edgegap.com/learn/matchmaking "mention") - find other players and start servers on-demand ([#match-bound](#match-bound "mention")). * [server-browser](https://docs.edgegap.com/learn/server-browser "mention") - pre-warm servers with long initialization ([#regional-standby](#regional-standby "mention")). * [Deploy API](https://docs.edgegap.com/api/#tag/Deployments/operation/deploy) - server-to-server customized integration (custom scaling). {% hint style="success" %} **Save** `request_id` **(Deployment ID) and tag Deployments** to identify and troubleshoot issues later. {% endhint %} {% hint style="info" %} When testing with [Deploy API](https://docs.edgegap.com/api/#tag/Deployments/operation/deploy), you may override default Dockerfile `CMD` with custom command. {% endhint %} #### 2. Deploying Once a deployment is started, our system will perform a number of steps in rapid succession: * Telemetry - we’re measuring network responsivity from available data centers to each player, * Deployment - we’re reserving capacity and preparing to start your server container, * Container Boot - we’re starting the container, installing dependencies, and initializing, * Post Processing - we’re adding log storage, monitoring, and finalizing the deployment. {% hint style="success" %} **Enable** [**Active Caching in your App Version**](https://docs.edgegap.com/learn/application-and-versions#active-caching) **to deploy servers within seconds.** {% endhint %} {% hint style="warning" %} **Too Many Requests 429** - to ensure stability and prevent surprise invoices, we rate limit your organization at **40 req/s**. [Contact us](mailto:info@edgegap.com) to plan releases, estimate launch traffic, and prepare for success. {% endhint %} #### 3. Deployment Ready Your container is fully initialized and your server is starting up now. For a few seconds to a minute, your server may be still initializing and may not respond to player requests until your game engine (or custom runtime) is fully ready to accept player connections. {% hint style="success" %} Once the deployment is Ready, **retry player connection until successful**, or until pre-defined client timeout. {% endhint %} {% hint style="danger" %} **Unexpected crash of server will cause your server to restart automatically.** [Server state may be lost](https://docs.edgegap.com/learn/persistence#state-management). {% endhint %} #### 4. Deployment Error Your deployment may end up in Error state at any point in time, for unexpected reasons. This is more likely to happen while testing your integration, or testing new server builds. **You are not charged for deployments in Error, which are automatically stopped after 24 hours.** Troubleshooting steps: * Verify Edgegap Service Status with [our uptime monitoring page](https://status.edgegap.com/). * Try testing your server container locally using Docker Desktop to rule out Edgegap issues. {% hint style="info" %} If you need help, [please reach out to us over Discord](https://discord.gg/MmJf8fWjnt). For live games support see our [ticketing system](https://edgegap.atlassian.net/servicedesk/customer/portal/3). {% endhint %} {% hint style="success" %} **When asking for help,** **include your deployment ID and any useful details** so we can investigate promptly! {% endhint %} #### 5. Deployment Stopped **We never stop your servers without your directive**, to prevent impacting your players’ experience negatively. Your deployment may be stopped for these reasons: * **Self-Stop via** [**DELETE\_URL**](#injected-environment-variables) - deployment stopped itself after players left and match ended, * see [Unreal Engine](https://docs.edgegap.com/unreal-engine#stop-deployments) and [Unity](https://docs.edgegap.com/unity#stop-deployments) guides for stopping deployments correctly, * **Stop from your backend** - your backend stopped this deployment using [Deployments API](https://docs.edgegap.com/api/#tag/Deployments/operation/deployment-delete), * **Game Max Duration** - the allotted time in your [#safety-guardrails](https://docs.edgegap.com/learn/application-and-versions#safety-guardrails "mention") has expired, * [private-fleets](https://docs.edgegap.com/learn/orchestration/private-fleets "mention") Host running your deployment was deleted through a scheduled action. {% hint style="info" %} Once a deployment is stopped, **we trigger graceful termination** by sending `SIGTERM` signal to your main process, allowing a short termination period. Once expired, a `SIGKILL` signal is sent to stop deployment. {% endhint %} ## 👀 Observability Allow game servers to interoperate with third parties and gain operational insights. ### Discoverability Once Ready, deployment is assigned a URL ([fqdn](https://en.wikipedia.org/wiki/Fully_qualified_domain_name)) and an external port for each internal port. {% hint style="success" %} Use **deployment tags (up to 40 chars) to easily mark your deployments** and [#filter-deployments](#filter-deployments "mention"). {% endhint %} {% hint style="info" %} **Outbound traffic (to clients or backend) from your game servers is never blocked** or filtered. {% endhint %} #### **Websockets (WS) and Secure Websockets (WSS)** To use websocket-based netcode with Edgegap, you have two options: * **managed certificate**, set up in 1 minute without writing any code: * configure your [application-and-versions](https://docs.edgegap.com/learn/orchestration/application-and-versions "mention") to **use Websocket (WS) and Enable TLS Upgrade,** * use Edgegap URL to connect clients (e.g. `https://5fa53fa00a57.pr.edgegap.net/`) * **self-managed certificate**, if you want to use your own custom domain: * configure your [application-and-versions](https://docs.edgegap.com/learn/orchestration/application-and-versions "mention") to **use Secure Websocket (WSS)**, * configure your own TLS certificate flow with a custom DNS record (e.g. on [Cloudflare](https://www.cloudflare.com/application-services/products/ssl/)). {% hint style="danger" %} Uncaught server exceptions will cause the deployment's container to restart and invalidate TLS security. In such case, [stop your server](#id-5.-deployment-stopped) and [rematch players to a new deployment](https://docs.edgegap.com/matchmaking#custom-lobby). [Server state may be lost](https://docs.edgegap.com/learn/persistence#state-management). {% endhint %} ### Injected Variables Game servers often need additional information, such as server IP, internal port values, or other. Injecting read-only environment variables is a reliable cloud-agnostic way to pass parameters. {% hint style="success" %} Get variable values using [GetEnvironmentVariable in C#](https://learn.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable?view=net-8.0) or [GetEnvironmentVariable in C++](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/GenericPlatform/FGenericPlatformMisc/GetEnvironmentVariable). {% endhint %} {% hint style="info" %} See [App Version Variables](https://docs.edgegap.com/learn/application-and-versions#injected-variables) and [Matchmaker Variables](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#injected-variables) in addition to Deployment Variables below. {% endhint %} #### **Custom Variables** Define up to 20 custom variables for each deployment, each containing up to 4KB of string data. {% hint style="warning" %} **Avoid using reserved names (below), your custom variables will be overwritten otherwise!** {% endhint %} Access important information by reading variables injected to your servers by Edgegap: #### **Identifiers** * **`ARBITRIUM_REQUEST_ID`** - e.g. `f68e011bfb01` . * Unique deployment ID, also referred to as request ID. Used to retrieve more information. * Deployment URLs always have format `{ARBITRIUM_REQUEST_ID}.pr.edgegap.net`. * **`ARBITRIUM_PUBLIC_IP`** - e.g. `162.254.141.66` . * Public IP address of this host, can be used to connect instead of URL. * **`ARBITRIUM_HOST_ID`** - e.g. `alpha-north-america-70364ef8` . * Unique identifier of the machine hosting your deployment, shared with other deployments. * **`ARBITRIUM_DEPLOYMENT_TAGS`** - e.g. `tag1,tag2` . * Comma-delimited user-defined deployment tags, [useful for easy searching and filtering](#filter-deployments). * **`ARBITRIUM_PRIVATE_FLEET_ID`** - e.g. `PUBLIC_CLOUD` , or fleet ID if hosted on [private-fleets](https://docs.edgegap.com/learn/orchestration/private-fleets "mention"). #### Resource Specifications * **`ARBITRIUM_HOST_IN_PRIVATE_FLEET`** - e.g. `false` , indicating if hosted on [private-fleets](https://docs.edgegap.com/learn/orchestration/private-fleets "mention"). * **`ARBITRIUM_HOST_BASE_CLOCK_FREQUENCY`** - e.g. `2000` , processor frequency in MHz. * **`ARBITRIUM_DEPLOYMENT_VCPU_UNITS`** - e.g. `256`, allocated vCPU units (1024 = 1 vCPU). * **`ARBITRIUM_DEPLOYMENT_MEMORY_MB`** - e.g. `512`, allocated RAM in MB (1024 = 1 GB). #### **Lifecycle Management** * **`ARBITRIUM_DELETE_URL`** - e.g. `https://api.edgegap.com/v1/self/stop/9f511e17/660`. * Callable from the deployment, [deployment will be gracefully stopped](#id-5.-deployment-stopped). * Requires unique one-time `ARBITRIUM_DELETE_TOKEN` in `Authorization` header. * **`ARBITRIUM_DELETE_TOKEN`** - e.g. `7df4cd933df87084b34ae80d8abde293`. * **`ARBITRIUM_CONTEXT_URL`** - e.g. `https://api.edgegap.com/v1/context/9170f5211e17/17`. * Only callable from the deployment, returns more deployment details. * Requires unique `ARBITRIUM_CONTEXT_TOKEN` in `Authorization` header. * **`ARBITRIUM_CONTEXT_TOKEN`** - e.g. `dfaf50b9333b9ee07b22ed247e4a17e6`. #### **Discoverability** * **`ARBITRIUM_PORT_GAMEPORT_INTERNAL`** - e.g. `7777` , internal port for server listener. * **`ARBITRIUM_PORT_GAMEPORT_EXTERNAL`** - e.g. `31504` , external port for client connections. * External port values are randomized for each deployment for security purposes. * **`ARBITRIUM_PORT_GAMEPORT_PROTOCOL`** - e.g. `UDP` , protocol of your netcode transport. {% hint style="success" %} Examples assume you have named your port `gameport` (default). **Each port adds an additional set of sanitized** [#port-mapping](https://docs.edgegap.com/learn/application-and-versions#port-mapping "mention") **variables:** `@Super Port!` ⇒ `ARBITRIUM_PORT_SUPER_PORT_INTERNAL` . {% endhint %} * **`ARBITRIUM_BEACON_ENABLED`** - e.g. `true`, if deploying on [private-fleets](https://docs.edgegap.com/learn/orchestration/private-fleets "mention") with [ping-beacons](https://docs.edgegap.com/learn/orchestration/ping-beacons "mention"). * **`ARBITRIUM_HOST_BEACON_PUBLIC_IP`** - e.g. `139.177.198.69` , public IP of the closest beacon. * **`ARBITRIUM_HOST_BEACON_PORT_UDP_EXTERNAL`** - e.g. `30199`, for ping measurement over UDP. * **`ARBITRIUM_HOST_BEACON_PORT_TCP_EXTERNAL`** - e.g. `30456`, for ping measurement over TCP. #### **Structured Information (JSON as string)** {% hint style="info" %} Environment variables are **stored as stringified JSONs**, parse them using an SDK or a custom method. {% endhint %}
ARBITRIUM_DEPLOYMENT_LOCATION:
- Detailed information about deployment location. ```json ARBITRIUM_DEPLOYMENT_LOCATION="{ "city": "Montreal", "country": "Canada", "continent": "North America", "administrative_division": "Quebec", "timezone": "Eastern Time", "latitude": 45.513707, "longitude": -73.619073 }" ```
ARBITRIUM_PORTS_MAPPING:
- Detailed information about your internal and external ports. ```json ARBITRIUM_PORTS_MAPPING="{ "ports": { "gameport": { "name": "Game Port", "internal": 7777, "external": 31504, "protocol": "UDP" }, "webport": { "name": "Web Port", "internal": 8888, "external": 31553, "protocol": "TCP" } } }" ```
### Dashboard Monitoring Our [Dashboard](https://app.edgegap.com/) provides utilities to monitor your server scalability and assist with operations. #### Analytics {% hint style="success" %} Find [analytics dashboards in the sidebar menu](https://app.edgegap.com/analytics/dashboards/list) under category Server Hosting & Orchestration. {% endhint %} :star2: [**Upgrade to Pay as You Go tier**](https://app.edgegap.com/user-settings?tab=memberships) **to unlock detailed server performance metrics and insights:** * **General Insights:** monitor releases with live server count per version + resource usage overview, * **CPU Insights**: troubleshoot lagging servers due to processor-heavy operations, * **Memory Insights**: mitigate server restarts due to exceeding allocated memory, * **Networking Insights:** detect inefficient networking patterns and optimize netcode.
#### Deployment Map {% hint style="success" %} Find deployment map in [your deployment details page on Dashboard](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Preview deployment location, available locations, and estimated player locations on the map:
#### Deployment Balance Points {% hint style="success" %} Find deployment balance points heatmap in [your application details page on Dashboard](https://app.edgegap.com/application-management/applications/list). {% endhint %} Preview deployment balance points heatmap and filter by [application-and-versions](https://docs.edgegap.com/learn/orchestration/application-and-versions "mention"). Balance points are approximate locations with equal network proximity to each player in a given deployment:
{% hint style="warning" %} Balance point hotspots in strange locations (e.g. Greenland) indicate matchmaking of players far from each other. Learn about [#connection-quality](#connection-quality "mention") and [ping-beacons](https://docs.edgegap.com/learn/orchestration/ping-beacons "mention") to optimize your matchmaking. {% endhint %} #### Deployment Logs {% hint style="success" %} Find deployment logs in [your deployment details page on Dashboard](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Deployment logs display information about [#deployment-lifecycle](#deployment-lifecycle "mention"):
#### Container Logs {% hint style="success" %} Find container logs in [your deployment details page on Dashboard](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Inspect your game server’s logs in case of issues, or when debugging:
{% hint style="warning" %} **Once deployment stops, container logs are deleted.** Set up [third party S3 log storage](https://docs.edgegap.com/docs/endpoint-storage) to save logs. {% endhint %} #### Container Metrics {% hint style="success" %} Find container metrics in [your deployment details page on Dashboard](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Review container metrics (processor, memory, networking) to: * identify common connection issues when [#troubleshooting](#troubleshooting "mention"), * detect inefficient implementation patterns causing spikes in resource usage, * pinpoint inefficient resource usage in particular scenarios, * verify changes in your server’s resource usage during optimization, * benchmark your server initialization resource consumption and duration. History metrics display value averages with 1 minute time period, available in Free tier. :star2: [**Upgrade to Pay as You Go tier**](https://app.edgegap.com/user-settings?tab=memberships) **to unlock precise metrics with 1 second time intervals.**
{% hint style="info" %} [Contact us](mailto:info@edgegap.com) prior to your release to request live hosting support for large scale releases. {% endhint %} ### Context & Status Additional deployment information can be retrieved in JSON format: * from inside the deployment (game server), using [Deployment Context API](https://docs.edgegap.com/api/#tag/Context/operation/context-get), * from outside the deployment (backend / third party), using [Deployment Status API](https://docs.edgegap.com/api/#tag/Deployments/operation/deployment-status-get). {% hint style="info" %} Context API (from deployment) requires Context API token, while Status API uses your Edgegap token. {% endhint %} {% hint style="warning" %} **Too Many Requests 429** - we rate limit your organization at **20 req/s** for Context and Status API endpoints. Use [#injected-environment-variables](#injected-environment-variables "mention") and [Webhooks](https://docs.edgegap.com/docs/deployment/arbitrium-deploy-webhook) for a scalable solution. {% endhint %} ### Filter Deployments To quickly search amongst all deployments, you can [use our dashboard](https://app.edgegap.com/deployment-management/deployments/list):
{% hint style="success" %} Alternatively, let players **pick a persistent (always online) server** from a list with [server-browser](https://docs.edgegap.com/learn/server-browser "mention"). {% endhint %} [List deployments with API](https://docs.edgegap.com/api/#tag/Deployments/operation/deployments-get) and apply filters with backend integrations:
Deployment AttributeOperatorsExample Value
statuseq or neq"ready" or "error"
request_ideq "7e709a0d8efd"
in or nin[ "7e709a0d8efd", "4ba353100b4b" ]
tagseq or neq"tagA"
in or nin[ "tagA", "tagB" ]
created_ateq or lte or gte2025-05-12T20:03:20Z
applicationeq or neq"my-app"
in or nin[ "my-app", "my-other-app" ]
versioneq or neq"1.0.0"
in or nin[ "1.0.0", "prod" ]
fleet_nameeq or neq"my-app-fleet-europe"
in or nin[ "fleet-eu", "fleet-us" ]
ilike"%-eu%"
host_nameeq or neq"alpha-north-america-95fab093"
in or nin[ "alpha-north-america-95fab093" ]
ilike"%north-america%"
{% hint style="info" %} Each attribute can have at most 1 filter operator in a single request. See [api](https://docs.edgegap.com/docs/api "mention") for more. {% endhint %} Sort results by multiple fields in the order they appear in request: | Deployment Attribute | Order | | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | | [`created_at`](#id-1.-start-a-deployment) | [`asc`](#user-content-fn-11)[^11] or [`desc`](#user-content-fn-12)[^12] | | [`available_session_sockets`](https://docs.edgegap.com/docs/session) | [`asc`](#user-content-fn-13)[^13] or [`desc`](#user-content-fn-14)[^14] | Example filter queries:
List Deployments in Error to troubleshoot and remove. Encoded URL: ``` https://api.edgegap.com/v1/deployments?query={"filters":[{"field":"status","operator":"eq","value":"error"},{"field":"application","operator":"eq","value":"my-app"},{"field":"version","operator":"eq","value":"green"}],"order_by":[{"field":"created_at","order":"desc"}]} ``` Formatted JSON query: ```json { "filters": [ { "field": "status", "operator": "eq", "value": "error" }, { "field": "application", "operator": "eq", "value": "my-app" }, { "field": "version", "operator": "eq", "value": "green" } ], "order_by": [ { "field": "created_at", "order": "desc" } ] } ```
List Deployments with outdated App version to confirm a release is complete. Encoded URL: ``` https://api.edgegap.com/v1/deployments?query={"filters":[{"field":"status","operator":"eq","value":"ready"},{"field":"application","operator":"eq","value":"my-app"},{"field":"version","operator":"eq","value":"blue"}],"order_by":[{"field":"created_at","order":"desc"}]} ``` Formatted JSON query: ```json { "filters": [ { "field": "status", "operator": "eq", "value": "ready" }, { "field": "application", "operator": "eq", "value": "my-app" }, { "field": "version", "operator": "eq", "value": "blue" } ], "order_by": [ { "field": "created_at", "order": "desc" } ] } ```
{% hint style="success" %} Don’t forget to add the `Authorization` header with your Edgegap API token in the request. {% endhint %} ### Webhooks & Postbacks Receive simple HTTP notifications in your game backend for changes in [#deployment-lifecycle](#deployment-lifecycle "mention") by specifying a webhook URL in your [deployment API request](https://docs.edgegap.com/docs/api/dedicated-servers#post-deployments). Available for: * On Ready: deployment container [started successfully](#id-1.-start-a-deployment) (server starts initializing after this), * On Error: deployment couldn't be started and a [#id-4.-deployment-error](#id-4.-deployment-error "mention") occurred, * On Terminate: [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") and game server is no longer reachable. Ready and Error webhooks will never be triggered for the same deployment.
Example Webhook Payload ```json { "request_id": "f68e011bfb01", "application": "my-game-server", "version": "2024.01.30-16.23.00-UTC", "fqdn": "f68e011bfb01.pr.edgegap.net", "public_ip": "162.254.141.66", "deployed_at": "2026-02-10T20:35:48Z", "termination_scheduled_at": "2026-02-10T21:35:48Z", "ports": { "gameport": { "external": 31504, "internal": 7777, "protocol": "UDP", "name": "gameport", "tls_upgrade": false, "link": "f68e011bfb01.pr.edgegap.net:31504", "proxy": null } }, "location": { "city": "Montreal", "country": "Canada", "continent": "North America", "administrative_division": "Quebec", "timezone": "Eastern Time", "latitude": 45.513707, "longitude": -73.619073 }, "tags": [ "tag1", "tag2" ], "host_id": "alpha-north-america-70364ef8", "host_in_private_fleet": false, "private_fleet_id": "PUBLIC_CLOUD", "vcpu_units": 256, "memory_mib": 512 } ```
{% hint style="warning" %} **Webhooks are not retried**, so if your backend does not process the request due to rate limiting or an error, the webhook may be lost. Use webhooks only for **non-critical use cases or debugging purposes**. {% endhint %} {% hint style="info" %} Webhooks observe deployment lifecycle, but are not aware of your scene/level initialization state. To observe loading progress of your scene/level, implement a custom webhook in your game server. {% endhint %} ## 🚨 Troubleshooting When troubleshooting deployments: 1. verify there are no errors in your [#deployment-logs](#deployment-logs "mention") and [#container-logs](#container-logs "mention"), 2. run your server locally to rule out integration bugs, 3. review troubleshooting steps on this page, 4. reach out to us in [Community Discord](https://discord.gg/MmJf8fWjnt) and include your deployment ID. {% hint style="info" %} See [#player-issue-resolution](#player-issue-resolution "mention") for our recommendations on navigating player community feedback. {% endhint %}
Can’t connect clients to server - Request timed out., 请求超时 , ConnectionFailed , or Port verification failed. * First, make sure that the deployment is Ready, and there are no runtime exceptions or errors in your deployment log. If your deployment stopped, inspect logs in our [Dashboard](https://app.edgegap.com/deployment-management/deployments/list). * If you’re using Mirror netcode you need to have ["Auto Start Server”](https://mirror-networking.gitbook.io/docs/hosting/edgegap-hosting-plugin-guide#build-and-push) selected in your `NetworkManager` , rebuild, push, and redeploy your server. * If you’re using FishNet netcode you need to enable [“Start on Headless”](https://fish-networking.gitbook.io/docs/manual/components/managers/server-manager#settings-are-general-settings-related-to-the-servermanager) in your `ServerManager`, rebuild, push, and redeploy your server. * If you’re using Photon Fusion 2 netcode, please ensure that your server is passing the deployment public IP, external port and the `roomCode` on the server, and the same room code in the client in the [“NeworkRunner.StartGame”](https://doc.photonengine.com/fusion/current/manual/network-runner#creating-or-joining-a-room) parameter `StartGameArgs`. Deployment ID (e.g. `b63e6003b19f`) is a great choice as it’s globally unique and easily accessible to client by [Matchmaker](https://docs.edgegap.com/learn/matchmaking/matchmaker-in-depth) assignment and to the [#injected-environment-variables](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#injected-environment-variables "mention"). * Next, please verify that your port setting in your server build’s netcode settings matches the internal port in your [App version](https://app.edgegap.com/application-management/applications/list). You can change the port mapping by editing the [App version](https://app.edgegap.com/application-management/applications/list) without rebuilding. Find your protocol in your netcode integration. * Please ensure that your game client is connecting to the **external port** shown on your Deployment details page, this value will be always randomized due to security reasons. * If you’re using Secure Websocket (WSS) protocol in your netcode integration, please ensure that your [App version](https://app.edgegap.com/application-management/applications/list) port configuration for the WSS port has TLS Upgrade enabled. * Are you located in China and are using [Smart Fleets](https://docs.edgegap.com/docs/deployment/session/fleet-manager/fleet)? Your connection may be blocked by the Great Firewall. Consider adding a server located in China to your fleet, or using a VPN to connect.
My deployment stopped/restarted and I can’t access it’s logs anymore. * In case the server process crashes due to an exception, our system will attempt restarting the server automatically. Consider testing your server locally to uncover the root cause. * We only keep logs for the duration of the deployment, if you wish to inspect logs after deployment stops, please [integrate a third party log storage](https://docs.edgegap.com/docs/deployment/endpoint-storage). * See [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") to discover all causes for stopping your deployment.
My deployment stopped automatically after X minutes. * Free Tier deployments have a 60 minute time limit, please consider upgrading your account. * All deployments will be terminated after 24 hours of runtime following our server sanitization policy, for infrastructure maintenance, and to prevent racking up unexpected costs when deployment wasn’t shut down properly. For long-running servers, consider using [private-fleets](https://docs.edgegap.com/learn/orchestration/private-fleets "mention") with [persistence](https://docs.edgegap.com/learn/orchestration/persistence "mention"). * See [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") to discover all causes for stopping your deployment.
My deployment is ready but I’m not able to connect for several minutes afterwards. * Once a deployment is Ready, your game engine initialization begins. This process may take anywhere from seconds to minutes, and the server doesn’t accept to player connections during this period. * Consider optimizing your server initialization to decrease this time period. * Game clients should retry connection in 1 second intervals for a limited amount of time (depending on your initialization duration), after which they return to matchmaking. * Consider adding a loading scene so the server can perform initialization (and travel in case of Unreal Engine) at the same time as clients, while synchronizing state of both.
My Meta Quest device throws HTTP 0: Cannot resolve destination host . * When building Unity apps for Android target, your Internet Access permission may be removed from the output APK client build artifact automatically. * Re-add the permissions in (requires rebuilding client afterwards): * Project Settings / OpenXR / :gear: Meta Quest Support / Force Remove Internet Permissions (uncheck). * Player Settings / Internet Access (set to require).
What will happen if a player leaves my deployment? * By default, servers don’t reject player connections. Authenticating players is up to your devs, since many different methods and player authentication providers can be used. * Game clients may store connection information locally to attempt reconnecting in case of unexpected client crashes. * To allow players to join games in progress, consider using [#backfill](https://docs.edgegap.com/matchmaking/matchmaker-in-depth#backfill "mention") or [Sessions](https://docs.edgegap.com/docs/deployment/session).
My server shows 100% CPU utilization after becoming ready. * This may not be an issue, as game engines tend to perform CPU-heavy operations during server initializations. If the CPU usage doesn’t drop after 2-3 minutes from deployment start, you may need to optimize your server or increase app version resources. * Reducing tick rate can impact CPU usage as the server performs less messaging operations. * If you’re using Mirror netcode you need to have ["Auto Start Server”](https://mirror-networking.gitbook.io/docs/hosting/edgegap-hosting-plugin-guide#build-and-push) selected in your `NetworkManager` , rebuild, push, and redeploy your server. * If you’re using FishNet netcode you need to enable [“Start on Headless”](https://fish-networking.gitbook.io/docs/manual/components/managers/server-manager#settings-are-general-settings-related-to-the-servermanager) in your `ServerManager`, rebuild, push, and redeploy your server. * You’re limited to 1.5 vCPU and 3GB of memory (RAM) in Free Tier. * You may increase allocated resources when creating a new app version. You can duplicate your App version in our Dashboard and adjust these values as needed, without rebuilding your server or image.
My deployment is restarting repeatedly and shows error `OOM kill` . * This behavior is caused by exceeding allocated memory amount. Consider optimizing memory usage with object pooling, compression, or removing unneeded objects in your scene. * Ensure your project is loading the default scene containing your `NetworkManager` and the scene is included in Unity’s Build Settings. * You’re limited to 1.5 vCPU and 3GB of memory (RAM) in Free Tier. * You may increase allocated resources when creating a new app version. You can duplicate your App version in our Dashboard and adjust these values as needed, without rebuilding your server or image.
Sometimes, my server’s memory (RAM) usage spikes to a high value, is that a problem? * As long as you stay within the allocated app version memory amount, this is not an issue. * Exceeding the allocated app version memory amount will cause \`OOM kill\` (see above).
Will my server performance be impacted by other servers running on the same machine? * No, our platform ensures that allocated resources will not be used by other studios, or other servers on shared infrastructure. With Edgegap, there are no noisy neighbors.
[^1]: sessions may last up to 24 hours [^2]: equals [^3]: not equals [^4]: request\_id (deployment ID) [^5]: in array [^6]: not in array [^7]: lower than or equal [^8]: greater than or equal [^9]: in array [^10]: case insensitive pattern matching: * use `%` for any sequence * use `_` for any one character [^11]: ascending, oldest first [^12]: descending, newest first [^13]: ascending, full first [^14]: descending, empty first