Skip to content

Application Build Management

Application Build Management is the process of creating and maintaining builds for your Application. An ApplicationBuild defines the software that will be deployed by our system. It can be a game server or a utility (side car). Whenever you have a software update, you must upload the new build to our system and create an ApplicationBuild for it before it can be deployed.

Prerequisites

Before you can create an ApplicationBuild element, you must first create:

Please refer to the Application Management chapter for more information on creating these elements.

Additionally you must have uploaded a build archive to your origin node.

ApplicationBuild elements

An ApplicationBuild is represented by the following element:

The process flow of creating an ApplicationBuild is visualized in the ApplicationBuild process flow below.

ApplicationBuild process flow

The following diagram is a simple overview depicting the process of creating an ApplicationBuild. Note that you must first define an Application before you can start this process. The chapter after that provides an example for more detail.

The ApplicationBuild creation process can be summarized as follows:

Figure 1: ApplicationBuild creation process

ApplicationBuild creation example

Uploading a file

When you have requested an i3D.net hosted origin node, or when you have setup and registered your self-hosted origin node, you can upload your build archive there.

This is the first step; uploading your build(s) to your origin. Note that in the future you will be able to upload your builds via our control panel as well.

Fetching the ID of your uploaded file (i3D.net hosted origin)

When the upload is finished our system will index the files in your account and make them all available via /v3/buildProvisioning/storage/file. Take note of the file IDs, you will need these when creating the ApplicationBuild element below.

GET /v3/buildProvisioning/storage/file

JSON response data BuildProvisioningFile: 

[
    {
        "id": "3878562502763646783",
        "buildProvisionRegistrationId": "7495746709577092943",
        "filename": "test.test",
        "fileSize": "976353",
        "md5CheckSum": "d41d8cd98f00b204e9800998ecf8427e",
        "createdAt": 1595485988,
        "changedAt": 0,
        "deletedAt": 0
    }
]

Create ApplicationBuild (using an i3D.net provided origin node)

POST /v3/applicationBuild

JSON request data ApplicationBuild: 

{
  "name": "Bluewolf",
  "applicationId": "245926280441350104",
  "executable": "bw",
  "startupParameters": "-p VAR_GAME_PORT",
  "osId": 151,
  "label": [
    {
      "key": "version",
      "value": "1.1"
    }
  ],
  "applicationBuildFile": {
    "buildProvisioningRegistrationId": "7495746709577092943",
    "buildProvisioningFileId": "3878562502763646783",
    "version": "1.1"
  }
}

Here we take the values for buildProvisioningFileId and buildProvisioningRegistrationId from the previous GET /v3/buildProvisioning/storage/file request.

Create ApplicationBuild (using a self-hosted origin node)

POST /v3/applicationBuild

JSON request data ApplicationBuild: 

{
  "name": "Bluewolf",
  "applicationId": "245926280441350104",
  "executable": "bw",
  "startupParameters": "-p VAR_GAME_PORT",
  "osId": 151,
  "label": [
    {
      "key": "version",
      "value": "1.1"
    }
  ],
  "applicationBuildFile": {
    "buildProvisioningRegistrationId": "7495746709577092943",
    "filename": "gamebuild.1.1.zip",
    "path": "/",
    "domain": "builds.gamedev.org",
    "version": "1.1"
  }
}

In this case you must provide a bit more details than with an i3D.net hosted origin, because in this self-hosted case, we have no knowledge of which files are hosted on your origin. So you must provide the buildProvisioningRegistrationId, followed by fields you must manually enter for your build file:

  • domain: the domain of your origin
  • path: the path within which your build archive resides
  • filename: the file name of your build archive
  • headers: key/value array of HTTP headers for your security, to lock down access to the files on your origin. You can enter any kind of header keys (header name) and values (header value).

Upon submission we will validate these details, and see if we get a 200 OK response for a HEAD request, meaning the file could be reached by our platform. If this call succeeds, you will get the newly created ApplicationBuild in the response body of the request. You could optionally verify its existence using the ApplicationBuild's ID:

Verifying the new ApplicationBuild

GET /v3/applicationBuild/{applicationBuildId}

JSON response data ApplicationBuild: 

[
  {
    "id": "2873523614050361171",
    "name": "Bluewolf",
    "applicationId": "2801917034933755411",
    "executable": "bw",
    "startupParameters": "-p VAR_GAME_PORT",
    "installId": 9837,
    "osId": 151,
    "label": [
      {
        "key": "version",
        "value": "1.1"
      }
    ]
  }
]

We now have a complete ApplicationBuild element pointing to an ApplicationBuildFile (representing the build archive you uploaded earlier) and the following definitions:

  • a name (must be unique)
  • the Application element this element belongs to
  • the file path (including file name) to the executable that we need to start the instance
  • startupParameters to accompany the executable
  • operating system needed for the build to run on. This must match exactly the operating system on your servers (BM & VM), otherwise the platform will refuse to run your build