Extend app development workflow and requirements

Last updated on November 20, 2025

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 app 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, provides a general overview of the Extend app development workflow, and offers 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:

For a full Dev Container walkthrough, see Developing with Extend Dev Containers.

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.

Develop using Dev Containers (Alternative Workflow)​

Dev Containers provide an alternative development approach that uses containerized development environments. This workflow eliminates the need to manually install and configure prerequisites on your local machine, as all required tools and dependencies are pre-configured within a Docker container. This approach ensures a consistent development environment across different operating systems and team members.

tip

The Dev Containers workflow is particularly beneficial for:

  • Teams wanting consistent development environments across all developers
  • Developers new to Extend app development who want to avoid complex local setup
  • Cross-platform development teams working on Linux, Windows, and macOS
  • Developers who prefer isolated development environments that don't affect their host system

Prerequisites for Dev Containers​

To use Dev Containers for Extend app development, you need the following:

  • Visual Studio Code with the Dev Containers extension installed

    • The Dev Containers extension enables VS Code to open and work with projects inside a Docker container.
    • To install the extension, open VS Code, go to Extensions (Ctrl+Shift+X or Cmd+Shift+X), search for Dev Containers, and install the extension published by Microsoft.

  • Docker Desktop v4.30+

    • Docker Desktop must be installed and running on your system.
    • For installation instructions, refer to the Prerequisites section above, which includes platform-specific Docker Desktop installation steps.

  • Git

    • Git is required to clone the Extend app template projects.
    • Git is typically pre-installed on macOS and Linux, and available for Windows.
note

While this guide focuses on Visual Studio Code with the Dev Containers extension, other IDEs such as JetBrains IDEs (IntelliJ IDEA, GoLand, etc.) also support Dev Containers through their respective plugins. The general workflow remains similar, but specific steps may vary depending on your IDE.

Dev Containers Workflow Steps​

  1. Clone the Extend app template project

    Clone the Extend app template project to your local development environment using Git. The Extend app templates include Dev Container configuration files (typically .devcontainer/devcontainer.json and related Docker configuration) that define the development environment.

    For template-specific Dev Container support, refer to the Dev Container support matrix.

    git clone <extend-app-template-repository-url>
    cd <extend-app-directory>

  2. Open the project in VS Code

    Open the cloned Extend app project folder in Visual Studio Code. VS Code will detect the Dev Container configuration files in the project.

  3. Reopen the project in a container

    When you open a project with Dev Container configuration, VS Code will prompt you to reopen the folder in a container. You can also manually trigger this by:

    • Clicking the notification that appears when VS Code detects a Dev Container configuration
    • Using the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and selecting Dev Containers: Reopen in Container
    • Clicking the green button in the bottom-left corner of VS Code and selecting Reopen in Container

    VS Code will then build and start the Dev Container. This process may take a few minutes the first time as it downloads the base image and installs dependencies.

    note

    The Dev Container includes all necessary development tools pre-configured:

    • Bash shell
    • Make build tool
    • Docker (Docker-in-Docker) for building container images
    • Language-specific development tools and dependencies
    • Extend Helper CLI

  4. Verify the development environment

    Once the container is running, open a terminal in VS Code (Terminal → New Terminal). The terminal will run inside the Dev Container. Verify that the required tools are available:

    bash --version
    make --version
    docker version
    extend-helper-cli --help

    All commands should execute successfully within the container environment.

VS Code Configuration Files​

Extend app templates that support Dev Containers include pre-configured VS Code files in the .vscode directory to enhance your development experience:

  • tasks.json: Pre-defined build and development tasks that you can run directly from VS Code's Command Palette (Ctrl+Shift+P or Cmd+Shift+P). These tasks typically include building the app, running tests, and other common development operations. You can access these tasks by opening the Command Palette and selecting Tasks: Run Task.

  • launch.json: Debugging configurations that allow you to debug your Extend app directly within VS Code. This includes breakpoints, variable inspection, and step-through debugging. You can start debugging by pressing F5 or using the Run and Debug view in VS Code.

    tip

    For examples of these configuration files, see the extend-service-extension-go repository:

  • mcp.json: Pre-configured Model Context Protocol (MCP) servers that provide AI-powered development assistance. These MCP servers can help with code generation, documentation, and other development tasks.

    note

    To use the MCP servers, you may need to configure them in VS Code. For detailed setup instructions, refer to the VS Code MCP documentation and the MCP servers guide. The MCP configuration file is available at mcp.json in the Extend app templates.

  1. Follow the Extend app README instructions

    Open the README.md file of the Extend app and follow the instructions in each section. The workflow within the Dev Container is the same as the traditional workflow:

    • Prerequisites: The Dev Container already includes all prerequisites, so you can skip manual installation steps.
    • Setup: Follow any setup steps specific to the Extend app type. The container environment is already configured with the necessary tools.
    • Build: Build the app using the provided Make commands or build scripts.
    • Test: Run the Extend app locally within the container to test and debug issues.
    • 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.

  2. Customize the Extend app

    Start customizing the Extend app to your needs. The customization process is identical to the traditional workflow:

    • Modify 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.

  3. Test and deploy

    After customizing the app:

    • Run the app locally within the container to test and debug issues, if any.
    • Update the details of the Extend app in the AGS Admin Portal to reflect your customizations.
    • Build and push the Extend app container image to AGS (Docker-in-Docker in the Dev Container allows you to build images).
    • Deploy the Extend app from the AGS Admin Portal.

Benefits of Using Dev Containers​

  • Consistent Environment: All developers work in the same pre-configured environment, reducing "works on my machine" issues.
  • Simplified Setup: No need to manually install Bash, Make, Docker, or other prerequisites on your host system.
  • Cross-Platform Compatibility: Works seamlessly on Linux, Windows (including WSL2), and macOS with the same configuration.
  • Isolated Environment: The development environment is isolated from your host system, preventing conflicts with other projects or system configurations.
  • Easy Reset: If something goes wrong, you can easily rebuild or reset the container without affecting your host system.
  • Team Onboarding: New team members can start developing immediately without complex environment setup.

Customizing the Dev Container​

If you need to customize the Dev Container configuration (for example, to add additional tools or environment variables), you can modify the .devcontainer/devcontainer.json file in your Extend app project. Common customizations include:

  • Adding additional VS Code extensions
  • Setting environment variables
  • Installing additional system packages
  • Configuring port forwarding

After modifying the Dev Container configuration, rebuild the container by using the Command Palette and selecting Dev Containers: Rebuild Container.

note

Changes to the Dev Container configuration require rebuilding the container. Your project files and customizations are preserved during container rebuilds as they are stored on your host system and mounted into the container.

Troubleshooting​

If you encounter issues with Dev Containers:

  • Container fails to start: Ensure Docker Desktop is running and has sufficient resources allocated (memory, CPU).
  • Slow performance: Increase the resources allocated to Docker Desktop in its settings.
  • Port conflicts: Check if ports used by the Extend app are already in use on your host system.
  • Permission issues: On Linux, ensure your user is in the docker group. On Windows and macOS, Docker Desktop handles permissions automatically.

For more information about Dev Containers, refer to the VS Code Dev Containers documentation.

Next step​

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

Last updated on
On this page