Upload a dedicated server build using the AMS CLI

Introduction​

AccelByte Multiplayer Servers (AMS) helps you manage and deploy your dedicated server builds so you can serve game sessions to your players around the world. Before you can create a fleet of servers you need to upload the dedicated server build to an AMS account.

This article walks you through how to:

  • Use the AMS command line interface (CLI) to upload a dedicated server image
  • Create an upload command

Prerequisites​

Before you begin this guide, you must have:

AGS Shared Cloud

If you are an AGS Shared Cloud customer, you can create an IAM client with all the necessary permissions for dedicated server uploading by clicking Create DS Uploader IAM Client under the Create New button on the IAM Clients page. A client that is capable of uploading a dedicated server has the DS Uploader tag.

  • Stored the dedicated server executables and any supporting files within a folder.
Server image requirements

  • The dedicated server images must be built for either x86 or x64. ARM is currently not supported.

  • The dedicated server images must be built for Linux.

note

Ensure that your files have the correct permissions during upload. AMS CLI for Linux preserves file permissions and read-, write-, and execute- flags when uploading the image.

AMS CLI for Windows does not preserve these UNIX permissions, and only the executable specified in your command line will have the execute flag set. So, if you use the Windows version of the CLI and have additional files that require specific permissions, you might encounter permission denied errors during DS execution. To avoid this, create a startup script that sets the permissions before running the DS, and specify it in the executable flag. For example:

#!/bin/sh
chmod +x ./bytewars  # mark your DS as executable
chmod +x ./bin/node  # mark your dependency as executable
./bytewars           # run your DS
note

Ensure that your startup script is encoded with UTF-8. If it is not correctly encoded, the script may fail to execute and prevent your DS from starting.

Text editors typically allow you to specify an encoding when saving a file. See Visual Studio's File Encoding Instructions for more information.

You can verify a file's encoding using the file command. See below for an example of a correctly encoded file in UTF-8:

file startup.sh
startup.sh: POSIX shell script, ASCII text executable

Incorrectly encoded file in UTF-8 with BOM:

file startup.sh
test.sh: POSIX shell script, Unicode text, UTF-8 (with BOM) text executable

Another consideration for the startup script is the end of line sequence. Much like encoding, many text editors allow specification of a line ending sequence for a file. Often, files saved on Windows systems can default to Windows-style line endings, or CRLF. It is important to ensure files are saved with the Unix-supported LF ending sequence.

You can use the file command to check for the appropriate format. If invalid, you will see output similar to:

file startup.sh
startup.sh: POSIX shell script, ASCII text executable, with CRLF line terminators

A handy tool for dealing with both endcoding and line ending compatibility is dos2unix. If using a Debian-based distro, dos2unix can be installed via the following steps:

sudo apt-get update
sudo apt-get install dos2unix.

After successful installation, run the following command against your startup script:

dos2unix startup.sh
dos2unix: converting file startup.sh to Unix format...

The upload process​

The AMS CLI packages your dedicated server files and uploads the package to cloud storage. Once the upload completes successfully, you can deploy dedicated servers with this image using AMS fleets.

note

All dedicated server images are stored at the account level, meaning that all namespaces that link to the same AMS account will have access to all the dedicated server images that are uploaded to it.

Using the dedicated server uploader​

The general base command would be similar to this:

> ams upload -H <host> -c <iam_client_id> -s <iam_client_secret> -n <image_name> -p <path_to_server_folder> -e <exec_command>

You can view detailed help for the upload AMS CLI command by running ams upload -help.

upload command flags​

  • -c, --clientId

    The IAM client ID to be used for the uploader to authenticate.

  • -e, --executable

    Relative path to the executable that starts your dedicated server. The specified path must be relative to the directory specified in the --path argument.

  • -H, --hostURL

    Specify the host name of the environment that you want to upload to. The host name is the base URL of the environment, without the https://.

  • -n, --imageName

    Name of the image that is going to be built.

  • -p, --path

    The local path to the directory with your dedicated server files to be uploaded. This can either be an absolute path or a relative path but must be a directory containing all the files needed to run your dedicated server.

  • -s, --secret

    Specify the IAM client secret to be used for the uploader, to authenticate if the IAM client in use is a confidential client. Otherwise this option can be skipped.

  • -f, --symbolFiles (Optional)

    Use this option if you want your debug symbols to be uploaded alongside the server files. The default is false.

Manage server images​

You can manage server images on the Server Images page. On the sidebar, go to AMS > Server Images to view a list of server images in your AMS account.

Server Image List

The Server Images page shows the following information for each server image:

  • Image Name: name of the image that was built from CLI.
  • Image ID: unique ID of the image.
  • Size (MiB): storage image size, calculated using mebibytes (MiB).
  • Uploaded At: upload date and time of the image.
  • Tags: custom tags that have been added to the image.
  • Fleets: number of fleets referencing the image.
  • Status: status of the image, which can be Uploading, Complete, or Scheduled for deletion.

The same information is displayed on the details page of a server, along with a list of fleets that reference the image. From the list, click on the name of a server image to view its details page.

tip

To easily find and sort server images on the list:

  • Search for specific images using their name or ID in the search bar.
  • Sort the list in ascending or descending order based on Image Name, Size, Uploaded At, Fleets, or any other criteria available in the table header.
  • Sort Specific Tags and Status from the table list
  • Filter the list by Tags and Status. Click on the filter icon beside Tags or Status and select the criteria you want use. Then, click on OK to apply the filter.

Edit server image name and tags​

After a server image is created, only its name and tags can be edited. To do so, follow these steps:

  1. From the list of server images, click on the name of the server image you want to edit.
  2. On the details page of the server image, do the following:
    • In Image Name, click on the pencil (edit) icon to edit the name.
    • In Tags, click on Add more and type in the tags you want to add. You can add multiple tags by separating each tag with a comma. To remove a tag, click on its X (remove) button.

Protect server images​

Protecting a server image prevents it from being automatically deleted by AMS after 30 days of no fleets using or referencing it. On the server images list, the protected ones have a lock icon next to their names.

Server images can be protected in two ways:

  • From the list on the Server Images page, you can protect images one at a time or by batches.
    • One at a time: Find the image you want to protect and click on its Action menu. Select Protect Image and then click Protect on the confirmation message.
    • Batch: Check the boxes of the images you want to protect. At the top-right side of the list, click on Protect Image and then click on Protect on the confirmation message.
  • From the details page of the server image, click on Protect Image at the top-right side of the page. Then, click on Protect on the confirmation message.

Schedule server images for deletion​

In AMS, only unprotected server images that are not referenced by fleets can be scheduled for deletion. Once an image is scheduled, it will be deleted after one to two hours. During this period, you can cancel the deletion and keep the image in your AMS account. See Cancel server image deletion for more information.

Server images can be scheduled for deletion in two ways:

  • From Server Images page, you can schedule images for deletion one at a time or by batches.
    • One at a time: from the list, find the image you want to schedule for deletion. Select Delete and then click on Schedule Deletion on the confirmation message.
    • Batch: from the list, check the boxes of the images you want to schedule for deletion. At the top-right side of the list, click on Delete Image and then click on Schedule Deletion on the confirmation message.
  • From the details page of the server image, click on Delete Image at the top-right side of the page and then click on Schedule Deletion on the confirmation message.
notice

Starting October 8, 2024, server images that are older than 30 days and not associated with any fleets will automatically expire and be permanently deleted. Ensure that you protect any unused server images you wish to keep to prevent them from being deleted automatically.

Cancel server image deletion​

An image scheduled for deletion can be canceled within one hour after the request to delete it was made.

The deletion of a server image can be canceled in two ways:

  • From Server Images page, find the image and click on its Action menu. Then, click on Cancel Deletion and then click on Yes, cancel deletion on the confirmation message.
  • From the details page of the server image, click on Cancel Deletion at the top-right side of the page and then click on Yes, cancel deletion on the confirmation message.

What's next​

Now that you have uploaded your dedicated server build to AMS, you are ready to create a fleet to deploy dedicated servers using the uploaded image.

Last updated on

On this page