37. Server management part 4: Deployment

You can configure services on game servers created using iFun Engine and bundle these into packages to install on/upgrade individual servers. This documentation explains that process. Ubuntu 14.04/16.04 and CentOS 6.5/7 are currently supported.

37.1. Setting up the service

Use upstart for CentOS 6.5 and Ubuntu 14.04 and systemd for CentOS 7 and Ubuntu 16.04.

37.1.1. Upstart: Centos 6.5 & Ubuntu 14.04

Change the following in the project source directory ({{project-name}}-source) to change service configuration.

etc/upstart/init/{{project-name}}.conf

This file has the service script settings. Please see Upstart Intro, Cookbook and Best Practises for additional changes.

Note

If using flavors as discussed in Flavors: Identifying servers according to their role, the file name is etc/upstart/init/{{project-name}}.{{flavor}}.conf.

Note

If the project was created in a version prior to 1.0.0-1051, configuration files are in the etc/init and etc/default directories.

etc/upstart/default/{{project-name}}

This file defines the values used in service configuration.

# Sets this to 1 to enable, to 0 to disable
enabled=1
uid=root
gid=root

  • enabled: Whether the service is enabled. If this is 1, the service starts automatically after server restart.

  • uid: Account to run the service. The default is root, but we recommend assigning another account for security reasons.

  • gid: Group to run the service. We recommend assigning a group other than the default for security reasons.

Note

If using flavors as discussed in Flavors: Identifying servers according to their role, the file name is etc/upstart/default/{{project-name}}.{{flavor}}.

37.1.2. Systemd: Centos 7 & Ubuntu 16.04

etc/systemd/{{project-name}}.service in the project source directory is the configuration file. More details can be found at Systemd.

Note

If using flavors as discussed in Flavors: Identifying servers according to their role, the file name is etc/systemd/{{project-name}}.{{flavor}}.service.

Example: Changing the user running the service

For security reasons, we recommend creating a user instead of root and using that user’s account to run the service. The following example shows a service run by a user and group called centos.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[Service]
LimitNOFILE=999999

# It is strongly recommended that one should use uid:gid other than the root
# NOTE: Please update User=, Group=, and ExecStartPre=
User=centos
Group=centos

# Makes the daemon automatically restart
Type=simple
Restart=on-failure
RestartSec=5s

# create directories, and change permissions (with root privileges)
PermissionsStartOnly=true
ExecStartPre=/usr/bin/mkdir -p /var/log/funapi/example/glog \
  /var/log/funapi/example/activity \
  /var/crash/funapi/example
# NOTE: change root:root to service's uid:gid
ExecStartPre=/usr/bin/chown -R centos:centos /var/log/funapi/example/glog \
  /var/log/funapi/example/activity \
  /var/crash/funapi/example

ExecStart=/usr/bin/example-launcher

37.2. Generating packages

See Server management part 3: Server packaging for more on creating packages.

37.3. Installing/upgrading packages

37.3.1. Ubuntu 14.04, 16.04

Create a deb file as explained in Server management part 3: Server packaging. Copy this file to the server and then install with the dpkg command.

The following example shows a game called “example”.

$ sudo dpkg -i example_0.0.1_install.deb
[sudo] password for ubuntu:
Selecting previously unselected package example.
(Reading database ... 424079 files and directories currently installed.)
Preparing to unpack example_0.0.1_install.deb ...
Unpacking example (0.0.1) ...
Setting up example (0.0.1) ...
Processing triggers for ureadahead (0.100.0-16) ...
ureadahead will be reprofiled on next reboot

Important

If funapi1-runtime is not installed, a package installation error message is displayed. In this case, run the following command to automatically install the required package and server package.

37.3.2. Centos 6.5, 7

Create an RPM file as explained in Server management part 3: Server packaging. Copy this file to the server and then install with the rpm command.

The following example shows a game called “example”.

$ sudo rpm -i example_0.0.1_install.rpm

Important

If funapi1-runtime is not installed, a package installation error message is displayed. In this case, run the following command to first install funapi1-runtime.

$ sudo yum install funapi1-runtime

37.4. Starting/stopping the service

37.4.1. Upstart: Centos 6.5 & Ubuntu 14.04

You can start and stop the service with the commands start and stop.

If installing a server named “example”, run as follows:

37.4.1.1. Starting the service

$ sudo start example
example start/running, process 27687

37.4.1.2. Stopping the service

$ sudo stop example
example stop/waiting

37.4.2. Systemd: Centos 7 & Ubuntu 16.04

Use the systemctl command to enable the service and start or stop it.

If installing a server named “example”, run as follows:

37.4.2.1. Enabling the service

To automatically start the game service when the server is restarted, enable it with the following command:

$ sudo systemctl enable example

37.4.2.2. Starting the service

$ sudo systemctl start example

37.4.2.3. Stopping the service

$ sudo systemctl stop example

37.5. Viewing service logs

Separate logs are generated when starting and stopping a server with upstart or systemd. This allows you to see whether the service is running smoothly.

Note

See Programming part 1: Debugging logs for game server logs.

Note

See Debugging & Profiling for game server coredump.

37.5.1. Upstart: Centos 6.5 & Ubuntu 14.04

If running with upstart, service logs are in the /var/log/upstart/{{project-name}}.log file.

You can see the following logs for a server named “example”.

$ sudo less /var/log/upstart/example.log

37.5.2. Systemd: Centos 7 & Ubuntu 16.04

If running with systemd, you can see service logs with the journalctl -x -u {{project-name}} command.

You can see the following logs for a server named “example”.

$ sudo journalctl -x -u example

37.6. Locking package versions

You may need to lock the version of an external library you are using for development, an agent, or funapi1-runtime you are using in a live environment. You can do these functions using the methods below.

37.6.1. Locking versions in Ubuntu

Locking version:

If you are locking the version of funapi1-runtime, enter the following commands.

$ sudo apt-mark hold funapi1-runtime

After these commands, update from apt-get upgrade, excluding the package in question.

Checking packages with locked versions:

$ sudo apt-mark showhold
funapi1-runtime

You can check whether the version of a package you input above has been locked.

Unlocking version:

Unlock a package version with the following command:

$ sudo apt-mark unhold funapi1-runtime

You can upgrade the package after doing so.

37.6.2. Locking versions in CentOS

You need an additional package to lock a version in CentOS. Install with the following command.

$ sudo yum install yum-versionlock

After installing the yum-versionlock package, run with the following commands:

Locking version:

If you are locking the version of funapi1-runtime, enter the following commands.

$ sudo yum versionlock funapi1-runtime

After these commands, update from yum update, excluding the package in question.

Checking packages with locked versions:

$ sudo yum -q versionlock list
0:funapi1-runtime-1.0.0-1680centos7.*

You can check whether the version of a package you input above has been locked.

Unlocking version:

Unlock a package version with the following command:

$ sudo yum versionlock delete funapi1-runtime

You can upgrade the package after doing so.

Important

You need to input as with sudo yum versionlock delete '*:funapi1-runtime*' in CentOS 6.

37.7. Installing game servers in non-standard locations

37.7.1. Installing game server packages in non-standard locations

The creation and distribution of DEB and RPM files are explained above. These package files install the game server in a preset location and need root access.

However, they may not be allowed this access in certain cases, and may need to install all game server content in a certain directory. For example, if a game server is sent to a publisher, the publisher may wish to install the game package in a specific Linux account they use. In these cases, forcing the install location with DEB or RPM causes issues. It is better to create a tar.gz package to send to the publisher so they can extract it wherever they want. (tar.gz creation is explained in Available packaging types.)

For convenience, assume that our sample game is called hello and it is the lobby flavor. As such, the generated package will be hello_0.0.1_install-lobby.tar.gz. Now assume the publisher’s Linux server account is called Zeus. The publisher will extract the files under /home/zeus.

$ cd /home/zeus
$ tar zxf hello_0.0.1_install-lobby.tar.gz

When this happens, the package is installed with DEB and RPM under /home/zeus, and you can check that content installed under / in the directory has been copied.

37.7.2. Installing game server packages in non-standard locations and launching the service

Note that with this method, files are copied, but cannot automatically be run with game server services like upstart or systemd (that is, with daemons). Therefore, this task needs to be done manually.

You also need to specify the path to find the game server in /home/zeus rather than / even if the service has been registered. You only need to do these tasks once when setting up the game server OS.

Service registration for upstart and systemd is explained below. In both methods, environment variables are set and scripts are registered.

37.7.2.1. Environment variables that can be set in the service configuration file

  • GAME_ROOT_DIR: Sets the game server installation path. If this is not specified, / is used by default.

  • GAME_MANIFEST_OVERRIDE: Sets the MANIFEST.json override file location specified in Temporarily overriding MANIFEST.json. If this is not specified, /etc/{{project}}/MANIFEST.override.json is used by default.

  • GAME_LOG_ROOT_DIR: Sets the directory where log files are created. If not specified, /var/log/funapi/gamename is used by default.

  • GAME_CRASHDUMP_ROOT_DIR: Sets the core dump directory. If not specified, /var/crash/funapi/gamename is used by default.

  • GAME_GLOG_OPTIONS: Sets additional Google logging options. If not specified, –max_log_size=10 –stop_logging_if_full_disk is used by default.

  • GAME_CONTACT_EMAIL_ADDRESS: Specifies the email address to contact if the game server goes down. If not specified, email is not sent.

Tip

By specifying a GAME_CONTACT_EMAIL_ADDRESS, you can conveniently receive notifications when the game server goes down.

37.7.2.2. Registering services manually in Upstart (Ubuntu 14.04)

If you look under /home/zeus, you will see a directory called etc. This contains two subdirectories: default, which includes variable settings, and init, which includes actual service scripts.

$ cd /home/zeus
$ ls etc
default init

As our game name is hello and our flavor is lobby, the following files are found in each subdirectory:

$ ls etc/default
hello.lobby

$ ls etc/init
hello.lobby.conf

So that the service can find programs in /home/zeus, where we installed the game, the following environment variables are defined with export added in the variable configuration file etc/default/hello.lobby. Other variables can be used, as discussed in Environment variables that can be set in the service configuration file.

export GAME_ROOT_DIR=/home/zeus

Important

export must be used.

Now, when GAME_ROOT_DIR is set, files are copied as follows.

$ sudo cp /home/zeus/etc/default/hello.lobby /etc/default/
$ sudo cp /home/zeus/etc/init/hello.lobby.conf /etc/init/

Run as follows to run the game server:

$ sudo service hello start

37.7.2.3. Registering services manually in Systemd (CentOS 7/Ubuntu 16.04)

There is a directory called lib/systemd/system/ inside /home/zeus and a systemd service configuration file called hello.lobby.service under that.

$ ls lib/systemd/system
hello.lobby.service

Copy these files as follows.

$ sudo cp lib/systemd/system/hello.lobby.service /lib/systemd/system/

An environment variable configuration file called /etc/default/hello.lobby is also made and used as follows so systemd can find programs in /home/zeus where we installed the game. Other variables can be used, as discussed in Environment variables that can be set in the service configuration file.

GAME_ROOT_DIR=/home/zeus

Important

Unlike with Ubuntu, you do not need to use export.

Now you can run the game server as follows.

$ sudo systemctl start hello.lobby