Builders are used to clone your custom Runtime Code written in TypeScript, Go, and Lua. A builder represents the “CI” portion of a traditional CI/CD pipeline, deployment is a separate process.
Builders conditionally compile your code against a selected Nakama image and package it into a Docker image. Your 20 most recent builder images are stored at all times.
These images are then available for deployment in your project’s Configuration tab, enabling you to quickly deploy a new image or return to a previous one whenever needed.
Each tile on the dashboard provides the details of the corresponding builder:
- Status: Icon indicates the status of the most recent build process.
- Builder name: The name of this builder, used to build the resultant image. This cannot be edited once set.
- Organization: The organization this builder belongs to.
- Description: The user provided builder description.
- Repository: The Git repository this builder is linked to.
- Branch Nakama Version: The Nakama version associated with this builder. Any custom code must use the same Nakama version.
Best practices #
Before you start creating builders and deploying new projects, be sure to keep in mind the following:
- The repository should only contain source code relevant for the server module (i.e. do not place your Unity project there).
- Beside your custom runtime code files, all other files will be removed from the builder except for the following extensions:
main.goand mod files must be in the root directory, all others can be in subfolders. The shared object or Dockerfile do not need to be committed.
- In your Project configuration, set the
runtime.js_entrypointparameter to the location of your bundled JS file (e.g.
- After pushing any changes to your JS bundle, trigger a new build based on that latest commit.
You must include at least one file in the root directory, all other Lua modules can then be included in subfolders.
Builders are designed to ignore your Lua test files as follows:
.luafiles in a
- Any files named in the format
Creating builders #
You can create a new builder from your Organization or Builders dashboards.
- From the dashboard page, select the New Builder tile. The Create your Builder page is displayed.
- Provide the following details for your new builder:
- Organization: The Organization this builder will be associated with. Use the drop-down to select from your available Organizations.
- Builder Name: Enter a unique identifier for your builder. This name will be used for the Docker images created by this builder. Only alphanumeric characters may be used and cannot exceed 20 characters in length.
- Description: Enter a short description of this builder for easy identification.
- Nakama Image: Use the drop-down to select the Nakama version this builder will use.
- Click Create to finalize your new builder, then proceed to the builder details page to connect it to your desired repository and complete setup.
Connecting to source control #
To link your new builder to a desired repository, navigate to the Edit tab in your builder settings:
Use the drop-down of your source control provider (Git) to enter your connection details, then click Connect.
Managing builders #
Select any builder tile from your Organization or Builders dashboards to view its details page and manage the configuration.
There are eight tabs available in the project details page:
The Info tab provides all relevant details for this builder, such as the associated repository and Nakama image, and the recent status for this builder.
The Trigger tab enables you to view all recent commits for the linked repository and selected branch, then trigger a new image build using your desired commit SHA.
After selecting Trigger you can view the progress on the Info tab and, when finished, use this new image to update any projects in your organization.
The History tab displays all previously triggered builds. Select any listed build to view additional details.
The Logs tab enables you to view all logs generated by this builder, and filter according to logging level and any desired time period.
The Edit tab enables you to change available builder settings, such as the linked repository, description, and Nakama image used.
The Team tab enables you to view existing team members, manage their permission level for this builder, and add or remove team members from the builder entirely.
Users must have previously registered with Heroic Cloud before they can be added here.
The Audit tab enables you to view a list of all user actions performed on this builder. You can filter this list according to the Category and Action performed.
The Deletion tab enables you to delete the builder entirely. This is a non-reversible operation that deletes all resources.