Upgrade from v3 to v4

Upgrading from GameAP 3 while keeping the existing database is possible only to versions 4.0 and 4.1. They recognize a third-version database, extend its schema with their own tables, and keep working with the same users, servers, and games.

Starting with version 4.2, an in-place upgrade is not supported. Later versions expect the fourth-version schema and will not work with a GameAP 3 database.

If you need the latest version of the panel, install it on a clean database and migrate the data yourself — see If you need the latest version.

The latest version in the supported line is 4.1.2.

Before upgrading

Back up the database manually. gameapctl copies the v3 installation directory and the web server configuration, but does not save the database, and the upgrade changes its schema irreversibly.

# MySQL or MariaDB
mysqldump -u root -p gameap > gameap-v3-backup.sql

# PostgreSQL
pg_dump -U gameap gameap > gameap-v3-backup.sql

# SQLite — copying the file is enough
cp /var/www/gameap/database.sqlite gameap-v3-backup.sqlite

Check that the backup is not empty, and only then continue.

Which databases can be upgraded in place

DBMS in GameAP 3 In-place upgrade
MySQL, MariaDB yes
SQLite yes
PostgreSQL no

For MySQL and SQLite, the panel recognizes an existing GameAP 3 database and does not try to create the tables anew. For PostgreSQL there is no such recognition: the very first migration will try to create tables that already exist and fail.

If GameAP 3 runs on PostgreSQL, install GameAP 4 on a clean database and migrate the data yourself.

Upgrading to 4.1

gameapctl is installed together with the panel and can perform the transition.

gameapctl self-update
gameapctl panel upgrade

The utility will detect that the third version is installed and perform the upgrade.

Check which version gameapctl installs. When moving from the third version, it ignores the --version flag and installs the latest stable version from the 4.x line. If that turns out to be 4.2 or newer, the production database must not be upgraded.

First test the transition on a copy of the database — the procedure is described in Testing on a database copy. Make sure 4.0 or 4.1 got installed, and only then upgrade the production installation.

What happens during the upgrade:

  1. The .env file of the GameAP 3 installation is read, and the database connection parameters are taken from it.
  2. The v3 installation directory and the web server configuration are copied to a temporary directory. The path to the copy is printed to the console — write it down.
  3. The GameAP 4 configuration config.env is created, with the same database plugged in and new AUTH_SECRET and ENCRYPTION_KEY keys generated.
  4. GameAP 4 is installed and started.

On first start the panel applies migrations: it detects that the database belongs to the third version, skips table creation, and adds only what the fourth version is missing.

gameapctl is not installed

Download it from the releases page or with a command that substitutes the right version:

VERSION=$(curl -sL https://api.github.com/repos/gameap/gameapctl/releases/latest \
  | grep -m1 '"tag_name"' | cut -d'"' -f4)
curl -OL "https://github.com/gameap/gameapctl/releases/download/${VERSION}/gameapctl-${VERSION}-linux-amd64.tar.gz"
tar xvfz "gameapctl-${VERSION}-linux-amd64.tar.gz" -C /usr/local/bin

What changes with the transition

A web server and PHP are no longer needed. GameAP 4 is a single executable with a built-in web interface. After the upgrade, nginx or Apache can be kept as a reverse proxy or removed entirely.

The default port is 8025, not 80.

User passwords keep working. Versions 4.0 and 4.1 verify passwords the same way the third version did. There is no need to ask users to change their passwords.

Daemons keep working over the old protocol. In versions 4.0 and 4.1 the panel exchanges data with GameAP Daemon the same way the third version did, and connects to the daemon itself. Dedicated server settings need no changes, and the daemon port (31717 by default) must stay open.

Do not run gameapctl daemon upgrade --switch-to-grpc after upgrading to 4.1. gRPC data exchange only appeared in version 4.2, and a 4.1 panel will not be able to connect to such a daemon.

Rollback

If something does not work after the upgrade:

  1. Stop GameAP 4: gameapctl panel stop.
  2. Restore the database from the backup made before the upgrade.
  3. Bring back the v3 installation directory from the temporary copy whose path gameapctl printed.
  4. Restore the web server configuration and start it.

A rollback without a database backup is impossible: the schema has been changed, and GameAP 3 will no longer work with it.

Testing on a database copy

Before upgrading the production installation, it is worth running the transition on a copy of the database. It also shows which exact version gameapctl will install.

Do not point the trial installation at the production database: on first start the panel will apply migrations to it, and GameAP 3 will stop working.

Create a copy of the database:

mysqldump -u root -p gameap > /tmp/gameap.sql
mysql -u root -p -e "CREATE DATABASE gameap_v4_test"
mysql -u root -p gameap_v4_test < /tmp/gameap.sql

Download a version from the 4.1 line from the releases page and unpack it:

curl -OL https://github.com/gameap/gameap/releases/download/v4.1.2/gameap-v4.1.2-linux-amd64.tar.gz
tar xvfz gameap-v4.1.2-linux-amd64.tar.gz -C /usr/bin

Create the configuration file /etc/gameap/config.env:

DATABASE_DRIVER=mysql
DATABASE_URL=gameap:password@tcp(127.0.0.1:3306)/gameap_v4_test?parseTime=true

AUTH_SECRET=replace_with_32_random_bytes
ENCRYPTION_KEY=replace_with_32_random_bytes

HTTP_PORT=8025

The keys are easy to generate with openssl rand -hex 16.

Run:

gameap --env /etc/gameap/config.env

The panel will be available on port 8025. The full list of configuration parameters is in the config.env Reference.

Make sure the data is intact: users can log in, game servers and games are displayed. After that you can upgrade the production installation.

Setting up a systemd service

For convenient management of the trial installation, create a separate service.

Create a user and a directory:

useradd -r -s /usr/sbin/nologin -d /var/lib/gameap gameap
mkdir -p /var/lib/gameap
chown gameap:gameap /var/lib/gameap

Then the file /etc/systemd/system/gameap.service:

[Unit]
Description=GameAP - Game Server Control Panel
Documentation=https://docs.gameap.com
After=network.target
Wants=network-online.target
Requires=network.target

[Service]
Type=simple
User=gameap
Group=gameap

WorkingDirectory=/var/lib/gameap

ExecStart=/usr/bin/gameap

# Allow binding to privileged ports
AmbientCapabilities=CAP_NET_BIND_SERVICE

# Graceful stop
ExecStop=/bin/kill -TERM $MAINPID
KillMode=mixed
KillSignal=SIGTERM
TimeoutStopSec=30

# Restart policy
Restart=always
RestartSec=5
StartLimitInterval=60
StartLimitBurst=3

EnvironmentFile=/etc/gameap/config.env

RuntimeDirectory=gameap
PIDFile=/run/gameap/gameap.pid

# Filesystem permissions
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

ReadWritePaths=/var/lib/gameap

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=gameap

[Install]
WantedBy=multi-user.target

Enable and start the service:

systemctl daemon-reload
systemctl enable gameap
systemctl start gameap

If you need the latest version

You cannot upgrade from GameAP 3 straight to 4.2 or newer. The procedure is:

  1. Install the current version of GameAP 4 on a clean database, leaving the production installation untouched — see Install on Linux.
  2. Migrate the data from GameAP 3: recreate the users, dedicated servers, games, and game servers — manually or via the API.
  3. Make sure everything works, and only then decommission the old installation.

Game server files do not need to be moved anywhere: they stay on the dedicated server; it is enough to describe the servers in the new panel with the same directories and ports.