Extend app development workflow and requirements

Last updated on December 17, 2024

Introduction​

AccelByte Gaming Services (AGS) provides you Extend app templates to start your projects. The source code for our Extend app templates are fully customizable and hosted on GitHub.

Use the Extend app templates when starting your projects as they are pre-configured with basic authentication and authorization settings. The app templates also come with specific instrumentations that you will need for observability to enable metrics and logs to be available when you deploy your app. Additionally, having basic knowledge about gRPC can help you understand Extend apps better.

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

note

For pricing details regarding the Extend service, refer to the Extend pricing page

Before diving into the above guides, AccelByte highly advises giving this article a thorough read. This article lists 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 Extend app template 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 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 are developing an Extend app for the first time, AccelByte recommends running and exploring the app template as it is (before any customization) to get a feel of how the app works. 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.

  4. Start customizing the Extend app to your needs.

    • gRPC *.proto file (if required)
    • Implement gRPC methods
    note
    • In general, there is no need to change other files unless you need to do further customizations.
    • Depending on the type of Extend app, gRPC *.proto files are handled differently:
      • Extend Override apps: Use the provided gRPC *.proto file as is (without modifications).
      • Extend Service Extension apps: Modify the gRPC *.proto file as needed.
      • Extend Event Handler apps: Include one or more gRPC *.proto files from API Events.

  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 Extend app template 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.

Troubleshooting​

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

Docker login fails​

Pushing an Extend app container image to AGS using Extend Helper CLI, the 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 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 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