Getting started with the service extension
Extend is in Open Beta for AGS Private Cloud 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.
Overview
This article walks you through how to set up an Extend Service Extension app. For this purpose, the Extend Service Extension app template is used. The app template contains an example of a custom guild service that has two endpoints to create and get guild progress data.
Prerequisites
- Go
- C#
- Java
- Python
Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:
a. Bash
On Windows WSL2 or Linux Ubuntu:
bash --version
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...On macOS:
bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
b. Make
On Windows WSL2 or Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt update && sudo apt install make
.make --version
GNU Make 4.3
...On macOS:
make --version
GNU Make 3.81
...
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
On Linux Ubuntu:
- To install from the Ubuntu repository, run
sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2
. - Add your user to the
docker
group:sudo usermod -aG docker $USER
. - Log out and log back in to allow the changes to take effect.
- To install from the Ubuntu repository, run
On Windows or macOS:
Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.
docker version
...
Server: Docker Desktop
Engine:
Version: 24.0.5
...
d. Go v1.20
Follow Go's installation guide.
go version
go version go1.20.0 ...
- Use the available binary from extend-helper-cli.
Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:
a. Bash
On Windows WSL2 or Linux Ubuntu:
bash --version
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...On macOS:
bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
b. Make
On Windows WSL2 or Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt update && sudo apt install make
.make --version
GNU Make 4.3
...On macOS:
make --version
GNU Make 3.81
...
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
On Linux Ubuntu:
- To install from the Ubuntu repository, run
sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2
. - Add your user to the
docker
group:sudo usermod -aG docker $USER
. - Log out and log back in to allow the changes to take effect.
- To install from the Ubuntu repository, run
On Windows or macOS:
Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.
docker version
...
Server: Docker Desktop
Engine:
Version: 24.0.5
...
d. .NET 6 SDK
On Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt-get update && sudo apt-get install -y dotnet-sdk-6.0
.On Windows or macOS:
Follow Microsoft's documentation for installing .NET on Windows or on macOS.
dotnet --version
6.0.128
- Use the available binary from extend-helper-cli.
Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:
a. Bash
On Windows WSL2 or Linux Ubuntu:
bash --version
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...On macOS:
bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
b. Make
On Windows WSL2 or Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt update && sudo apt install make
.make --version
GNU Make 4.3
...On macOS:
make --version
GNU Make 3.81
...
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
On Linux Ubuntu:
- To install from the Ubuntu repository, run
sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2
. - Add your user to the
docker
group:sudo usermod -aG docker $USER
. - Log out and log back in to allow the changes to take effect.
- To install from the Ubuntu repository, run
On Windows or macOS:
Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.
docker version
...
Server: Docker Desktop
Engine:
Version: 24.0.5
...
d. JDK 17
On Linux Ubuntu:
To install from the Ubuntu repository, run:
sudo apt update && sudo apt install openjdk-17-jdk
.On Windows or macOS:
Follow Microsoft's documentation for installing the Microsoft Build for OpenJDK.
java --version
openjdk 17.0.10 2024-01-16
...
- Use the available binary from extend-helper-cli.
Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:
a. Bash
On Windows WSL2 or Linux Ubuntu:
bash --version
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...On macOS:
bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
b. Make
On Windows WSL2 or Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt update && sudo apt install make
.make --version
GNU Make 4.3
...On macOS:
make --version
GNU Make 3.81
...
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
On Linux Ubuntu:
- To install from the Ubuntu repository, run
sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2
. - Add your user to the
docker
group:sudo usermod -aG docker $USER
. - Log out and log back in to allow the changes to take effect.
- To install from the Ubuntu repository, run
On Windows or macOS:
Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.
docker version
...
Server: Docker Desktop
Engine:
Version: 24.0.5
...
d. Python 3.10
On Linux Ubuntu:
To install from the Ubuntu repository, run
sudo apt update && sudo apt install python3 python3-venv
.On Windows or macOS:
Use the available installer here.
python3 --version
Python 3.10.12
- Use the available binary from extend-helper-cli.
Access to the AGS Admin Portal environment.
Base URL:
<your environment's domain URL>
- Example for AGS Shared Cloud customer:
https://spaceshooter.prod.gamingservices.accelbyte.io
- Example for AGS Private Cloud customer:
https://dev.customer.accelbyte.io
- Example for AGS Shared Cloud customer:
Create a game namespace if you don't have one yet. Take note of the namespace ID.
Create an OAuth Client with
confidential
client type containing the following permissions:For AGS Private Cloud customers:
ADMIN:ROLE
[READ]ADMIN:NAMESPACE:{namespace}:NAMESPACE
[READ]ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD
[CREATE,READ,UPDATE,DELETE]
For AGS Shared Cloud customers:
- IAM > Roles (Read)
- Basic > Namespace (Read)
- Cloud Save > Game Records (Create, Read, Update, and Delete)
Keep the
Client ID
andClient Secret
.
Clone the app template
- Go
- C#
- Java
- Python
git clone https://github.com/AccelByte/extend-service-extension-go
git clone https://github.com/AccelByte/extend-service-extension-csharp
git clone https://github.com/AccelByte/extend-service-extension-java
git clone https://github.com/AccelByte/extend-service-extension-python
Set up, run, and test an Extend app
This section covers how to set up, build, run, and then test an Extend app.
Set up the Extend app
To be able to run this app, follow these setup steps:
Create a docker compose
.env
file by copying the content of the.env.template
file.注記The host OS environment variables have higher precedence compared to the
.env
file variables. If the variables in the.env
file do not seem to take effect properly, check if there are host OS environment variables with the same name. For more details, refer to Docker's documentation about the docker compose environment variables precedence.Fill in the required environment variables in the
.env
file as shown below:.AB_BASE_URL=https://test.accelbyte.io # Base URL of AGS environment
AB_CLIENT_ID='xxxxxxxxxx' # Client ID from the Prerequisites section
AB_CLIENT_SECRET='xxxxxxxxxx' # Client Secret from the Prerequisites section
AB_NAMESPACE='xxxxxxxxxx' # Namespace ID from the Prerequisites section
PLUGIN_GRPC_SERVER_AUTH_ENABLED=true # Enable or disable access token validation注記In this app,
PLUGIN_GRPC_SERVER_AUTH_ENABLED
istrue
by default. If it is set tofalse
, thegRPC server
can be invoked without theAccelByte Gaming Services
access token. This option is provided for development purposes only. It is recommended to enablegRPC server
access token validation in the production environment.
Build the Extend app
To build this app, run the following command:
make build
Run the Extend app
To (build and) run this app in a container, run the following command:
docker compose up --build
Additionally, it is also possible to run the project outside the container.
- Go
- C#
- Java
- Python
In the top-level directory of the project, use the following commands to build and run the combined gRPC server and gRPC gateway.
go build -o service
./service
In the top-level directory of the project, use the following commands to run the gRPC server.
cd src
dotnet run
Then, in a separate terminal, also in the top-level directory of the project, use the command below to run the gRPC gateway.
make run_gateway
If you are developing in Windows file system with Visual Studio, you can also run the gRPC server by opening the solution src/plugin-arch-service-extension-grpc-server.sln
and configure the environment variables by configuring the debug properties as shown below. Make sure you set AccelByte.PluginArch.ServiceExtension.Demo.Server
as a startup project.
The modal will show, and then, you can start configuring the environment variables as shown below. Close the modal to apply and save the changes.
In the top-level directory of the project, run the following commands to run the gRPC server:
bash gradlew run
Then, in a separate terminal, in the top-level directory of the project, use the following command to run the gRPC gateway:
make run_gateway
In the top-level directory of the project, run the following commands to run the gRPC server:
python -m app
Then, in a separate terminal, in the top-level directory of the project, use the following command to run the gRPC gateway:
make run_gateway
Test the Extend app
If PLUGIN_GRPC_SERVER_AUTH_ENABLED is true
, you will need a user access token to access the REST API endpoints. First, you need to have a user account in hand for this. You can can create a new user or use an existing user. Then, you can generate the user access token using the getusertoken.sh
shell script available in the top-level directory of the project. You will need to set the necessary environment variables before executing the shell script.
# Your AGS environment Base URL
$ export AB_BASE_URL='http://test.accelbyte.io'
# Client ID from the Setup section above
$ export AB_CLIENT_ID='xxxxxxxxxx'
# Client Secret from the Setup section above
$ export AB_CLIENT_SECRET='xxxxxxxxxx'
# The <username> and <password> are the user account credentials
$ bash getusertoken.sh <username> <password>
Option 1: Using Curl
Replace <accessToken> with user access token from getusertoken.sh
shell script.
Test the CreateOrUpdateGuildProgress
endpoint.
$ curl -X 'POST' \
'http://localhost:8000/guild/v1/admin/namespace/<your-namespace>/progress' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-H 'Content-Type: application/json' \
-d '{
"guildProgress": {
"guildId": "123456789",
"namespace": "<your-namespace>",
"objectives": {
"target1": 0
}
}
}'
Then, test the GetGuildProgress
endpoint.
$ curl -X 'GET' \
'http://localhost:8000/guild/v1/admin/namespace/<your-namespace>/progress/123456789' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <accessToken>'
You will see the updated guild progress in the response.
Option 2: Using Swagger UI
Open the automatically-generated Swagger UI at http://localhost:8000/service/apidocs.
If PLUGIN_GRPC_SERVER_AUTH_ENABLED is true
, set the user access token by clicking on the Authorize button.
On the pop-up that appears, type in Bearer <user's access token> in the Value field for Bearer (apiKey)
. Then, click Authorize button.
Finally, proceed to test the CreateOrUpdateGuildProgress
endpoint and the GetGuildProgress
endpoint.
When testing locally, make sure HTTP
(not HTTPS
) is selected for Schemes
option in the Swagger UI: Otherwise, you will get a network transport error when testing the endpoints.
Deploy in AGS
Deploying an Extend app in AGS involves the following steps in the Admin Portal:
Create the Extend app
- In the AGS Admin Portal, go to the namespace where you wish to create your Extend Override app.
- On the sidebar menu, under ADD-ONS, go to Extend > Service Extension.
- On the Service Extension page, click on the + Create New button.
- On the Create App form, provide a name and description (optional) for your Extend app.
- Click Create. Your new Extend app is added to the Service Extension app list.
Upload the Extend app
Set up an OAuth Client for extend-helper-cli.Create an OAuth Client with
confidential
client type and containing the following permission:- For AGS Private Cloud customers:
ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS
[READ]ADMIN:NAMESPACE:{namespace}:EXTEND:APP
[READ]
- For AGS Shared Cloud customers:
- Extend > Extend app image repository access (Read)
- Extend > App (Read)
Keep a copy of the
Client ID
andClient Secret
.- For AGS Private Cloud customers:
Copy the extend-helper-cli command to perform docker login on the Extend app details page under Repository Authentication Command.
Export the required environment variables and perform docker login using extend-helper-cli. Run this command:
- Linux
- Windows (WSL2)
- macOS
# Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
export AB_BASE_URL='https://xxxxxxxxxx'
# Client ID of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_ID='xxxxxxxxxx'
# Client Secret of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_SECRET='xxxxxxxxxx'
# The command to perform docker login (from step 2)
./extend-helper-cli-linux_amd64 dockerlogin --namespace <game namespace> --app <app name> --login# Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
export AB_BASE_URL='https://xxxxxxxxxx'
# Client ID of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_ID='xxxxxxxxxx'
# Client Secret of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_SECRET='xxxxxxxxxx'
# The command to perform docker login (from step 2)
./extend-helper-cli-linux_amd64 dockerlogin --namespace <game namespace> --app <app name> --login# Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
export AB_BASE_URL='https://xxxxxxxxxx'
# Client ID of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_ID='xxxxxxxxxx'
# Client Secret of OAuth Client for extend-helper-cli (from step 1)
export AB_CLIENT_SECRET='xxxxxxxxxx'
# The command to perform docker login (from step 2)
./extend-helper-cli-darwin_amd64 dockerlogin --namespace <game namespace> --app <app name> --loginimportantWe recommend running the above commands in a separate terminal and in a different working directory than the Extend app project. This is to reduce the chances of the extend-helper-cli picking up the environment variables for the Extend app project instead.
The output of a successful login looks similar to the following:
INFO[0000] signing in to https://dev.accelbyte.io
INFO[0001] getting docker credentials...
WARNING! Your password will be stored unencrypted in /home/xyz-abc/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login SucceededimportantIf you get the following error, refer to Troubleshooting: Docker login fails for troubleshooting steps .
Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`
Upload the Extend app container image to AGS using
extend-helper-cli image-upload
command. You can specify your extend app project by using-w
parameter. For image tag, you can put v0.0.1. For example:- Linux
- Windows (WSL2)
- macOS
./extend-helper-cli-linux_amd64 image-upload -n <game namespace> -a <app name> -w <extend app source dir> -t <image tag>
./extend-helper-cli-linux_amd64 image-upload -n <game namespace> -a <app name> -w <extend app source dir> -t <image tag>
./extend-helper-cli-darwin_amd64 image-upload -n <game namespace> -a <app name> -w <extend app source dir> -t <image tag>
備考You can use the
--login
parameter to log in and upload the image simultaneously using a single command. Refer to the extend-helper-cli README text for more details.If your images are successfully uploaded, you will see an image with version v0.0.1 on the Image Version History page.
Configure the Extend app
Before deploying the Extend app that you uploaded, you must configure the environment variables required by the Extend app. In the app's details page, set the following environment variables with the same values that you used to run and test the Extend app locally.
AB_CLIENT_ID
AB_CLIENT_SECRET
If your Extend Service Extension app is based on the template before release v2024.02.13, make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED
environment variable to true
. Otherwise, the access token validation in the Extend app is disabled and your Extend app may be accessed without a valid access token.
Since release v2024.02.13**, PLUGIN_GRPC_SERVER_AUTH_ENABLED
in Extend Service Extension app template is set to true
by default. The access token validation can only be disabled when PLUGIN_GRPC_SERVER_AUTH_ENABLED
is explicitly set to false
. To align with this, all new Extend apps created through the Admin Portal will not have PLUGIN_GRPC_SERVER_AUTH_ENABLED
environment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false
is added on all new Extend apps created through the Admin Portal.
Deploy the Extend app
To deploy the Extend app, click Deploy Latest Image. Wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.
Test the deployed Extend app
Open the Swagger UI
at <Service URL>/apidocs
. Use the Service URL
or click the Open API Documentation button on the Extend app details page.
When testing deployed Extend app, make sure HTTPS
(not HTTP
) is selected for Schemes
option in the Swagger UI. Otherwise, you will get a network transport error when testing the endpoints.
Next step
Proceed to modify this template project and create your own Service Extension app. See Customize the Extend Service Extension app.