Extend app development requirements and recommendations

Last updated on July 25, 2024
info

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.

Introduction​

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:

note

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.

Prerequisites​

An Extend app can be developed in Linux, Windows (WSL2), and macOS, 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 docker.io docker-buildx docker-compose-v2.

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

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

      docker version

      ...
      Server: Docker Desktop
         Engine:
         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 README.md file of the Extend app and follow the instructions in each section. The README.md 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.
    tip

    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.

Recommendation​

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.

Troubleshooting​

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 using Extend Helper CLI, 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. For more information, see Docker's open ticket for this issue.

The workaround for this issue depends on your operating system.

  1. In Windows file system:

    • Remove "credsStore": "desktop.exe" from %USERPROFILE%\.docker\config.json.
    • Rename the following files in C:\Program Files\Docker\Docker\resources\bin.
      • docker-credential-desktop.exe to docker-credential-desktop.exe.old
      • docker-credential-wincred.exe to docker-credential-wincred.exe.old

  2. In WSL2 file system:

    • Remove "credsStore": "desktop.exe" from $HOME/.docker/config.json.

  3. Try extend-helper-cli dockerlogin ... command again.

note

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. For more information, see Docker's open ticket for this issue.

Next step​

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

Last updated on

On this page