Skip to main content

Extend app development requirements and recommendations

Last updated on June 20, 2024

Extend is in Open Beta for AGS Premium Clients! This means that the Extend add-on is available for you to try in your development environment. You can submit your feedback via our Extend Open Beta feedback form.


AccelByte Gaming Services (AGS) provides you sample Extend apps, which you can use as templates to start your projects. The source code for our sample Extend apps are fully customizable and hosted on GitHub.

We recommend you use our sample Extend apps as your project template as they are pre-configured with basic authentication and authorization settings. The sample apps also come with specific instrumentations that you will need for observability to enable metrics, traces, and logs to be available when you deploy your app.

Each type of Extend app has varied setups and configuration steps, which are separately documented throughout the following guides:


The repository link for each sample Extend app is provided in their respective guides.

Before diving into the above guides, we highly advise giving this article a thorough read. This article aims to list prerequisites for various development environments, provide a general overview of the Extend app development workflow, and offer recommendations for beginners to get started smoothly.


An Extend app can be developed in Linux, WSL2, and Windows, each with the following general prerequisites:

  • Linux Ubuntu 22.04 with the following tools installed:

    • Bash

      bash --version

      GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
    • Make

      • To install from the Ubuntu repository, run sudo apt update && sudo apt install make.

        make --version

        GNU Make 4.3
    • Docker (Docker Engine v23.0+)

      1. To install from the Ubuntu repository, run sudo apt update && sudo apt install

      2. Add your user to the docker group: sudo usermod -aG docker $USER.

      3. Log out and log back to allow the changes to take effect.

        docker version

        Server: Docker Desktop
        Version: 24.0.5

Extend app development workflow

This section covers the general workflow for developing an Extend app in the following scenarios:

Create a new Extend app project

  1. Clone the sample Extend app project to your local development environment using Git.

  2. Open the project using your preferred IDE.

  3. Open the file of the Extend app and follow the instructions in each section. The file in each Extend app contains the following sections:

    • Prerequisites: make sure that you have prepared and completed the prerequisites for the Extend app.
    • Setup: follow the steps in this section to ensure that your environment has the proper setup to build and develop the Extend app.
    • Build: build the sample app in your IDE.
    • Test: run the Extend app locally to test and debug issues, if any.
    • Deploy: create and deploy the Extend app from the AGS Admin Portal.

    If you're developing an Extend app for the first time, we recommend running and exploring the sample app as it is (before any customization) to get a feel of how the app works.

  4. Start customizing the Extend app to suit your preferences.

    • gRPC *.proto file if required
    • Implement gRPC methods
  5. After you customize the app, do the following:

    • Run the app locally to test and debug issues, if any.
    • Update the details of the Extend app in the AGS Admin Portal to reflect your customizations.
    • Push the Extend app container image to AGS.
    • Deploy the Extend app from the AGS Admin Portal.

Apply existing project to a newer Extend app version

  1. Clone the new version of the sample Extend app you are using.

  2. Transfer the following from your project into the new version Extend app.

    • gRPC *.proto file
    • gRPC methods implementation
    • Any other changes that you may have beyond the above (if any)
  3. Run the Extend app locally to test and debug any issues.


Test a sample Extend app as is. We recommend you run a sample Extend app as it is, before customizing it. This helps you familiarize yourself with how the apps function, allows you to explore features and functionalities, and therefore, assess how much app customization you will have to do for your project.


This section contains troubleshooting information for possible issues you may encounter when developing an Extend app.

Docker login fails

When pushing an Extend app container image to AGS, extend-helper-cli dockerlogin ... command returns the following error:

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

This issue may be due to the token size being larger than most credential managers can handle. Depending on your operating system, a possible workaround is to delete either "credsStore": "desktop" or "credsStore": "desktop.exe" from your Docker config.json.

- Linux or WSL2: `$HOME/.docker\config.json`
- Windows: `%USERPROFILE%\.docker\config.json`

For more information, refer to Docker's documentation on configuring the credstore.


You may have to periodically apply this workaround. As of this article's update date, Docker has a known issue of restoring "credsStore": "desktop" in the config.json file when it is restarted.

Next step

Start creating and customizing your Extend app projects. Refer to the following guides: