Extend app development requirements and recommendations

Last updated on May 7, 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.

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:

• Extend Override
• Extend Service Extension
• Extend Event Handler

注記

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, WSL2, and Windows, each with the following prerequisites:

Linux

As part of the development prerequisites, Docker is required to be installed and configured to ensure that the Docker command does not need root.

• If you have not installed Docker, follow Docker's documentation on installing the Docker Engine on Ubuntu.
• Manage Docker as a non-root user. For more information, follow Docker's documentation on managing Docker as a non-root user.

WSL2

• If you have not installed Docker, follow Docker's documentation on installing the Docker Engine on Ubuntu.
• Manage Docker as a non-root user. For more information, follow Docker's documentation on managing Docker as a non-root user.
• An integrated development environment (IDE) that can work with projects inside WSL2 file system, e.g., Visual Studio Code, JetBrains IDE, etc.

Windows

• As part of the development prerequisites, Docker is required to be installed and configured to ensure that the Docker command does not need root.
  • If you have not installed Docker, follow Docker's documentation on installing the Docker Engine on Ubuntu.
  • Manage Docker as a non-root user. For more information, follow Docker's documentation on managing Docker as a non-root user.
• The WSL2 terminal to execute the commands for developing the Extend app.

We recommend the following best practices to ensure a smooth experience in this setup:

• Install or use an IDE on Windows, not in WSL2.

• Clone the sample Extend app project in Windows and open the project from there.

• If you clone the sample Extend app project using Git on Windows, set git config --global core.autocrlf to false. Otherwise, you may encounter errors when executing commands in the WSL terminal due to line-ending problems, e.g., $'\r': command not found. If this happens, you can use tools such as dos2unix to fix those files, e.g., shell scripts (*.sh).

  :::note Due to known limitations on the WSL2 side, such as slow performance, developing and uploading an Extend app in this setup will likely be slower and more restrictive than with other setups. :::

Extend app development workflow

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

• Creating a new Extend app project.
• Applying an existing Extend app project to a newer version.

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.
   ヒント

   For fresh projects, we recommend running and exploring the sample Extend 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, 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:

• Extend Override
• Extend Service Extension
• Extend Event Handler