startersclan/docker-hlstatsxce-daemon repository overview

⁠docker-hlstatsxce-daemon

Dockerized HLStatsX:CE⁠ perl daemon.

⁠Deprecation

This project is now deprecated.

As mentioned in the FAQ⁠, the daemon image starts with errors because the daemon code is outdated.

A fully working daemon image with updated code (with GeoIP2 support) has been developed in https://github.com/startersclan/hlstatsx-community-edition⁠. There is now no more need for this project, but it will be preserved only for the sake of existing support.

⁠Tags

Variants are based on ubuntu:16.04 or alpine:3.8. All variants include DBI and DBD::mysql perl modules.

Variants may contain one or more additional Perl modules. E.g. :geoip-geoip2-emailsender contains the geoip, geoip2, and emailsender Perl modules.

Variants may also contain additional tools. E.g. :geoip-geoip2-emailsender-curl contains the geoip, geoip2, and emailsender Perl modules, and curl, wget, and openssl tools:

⁠Usage

⁠Example

docker run -it \
    -p 27500:27500/udp \
    -e LOG_LEVEL=1 \
    -e MODE=Normal \
    -e DB_HOST=db \
    -e DB_NAME=hlstatsxce \
    -e DB_USER=hlstatsxce \
    -e DB_PASSWORD=hlstatsxce \
    startersclan/docker-hlstatsxce-daemon:v1.6.19-geoip-alpine-3.8

# Alternatively, if you prefer to use a config file instead of environment variables
docker run -it \
    -v /path/to/hlxce/scripts/hlstats.conf:/app/hlstats.conf \
    startersclan/docker-hlstatsxce-daemon:v1.6.19-geoip-alpine-3.8

⁠Example (Swarm Mode with Docker Secrets)

docker service create --name hlstatsxce-daemon \
    -p 27500:27500/udp \
    -e LOG_LEVEL=1 \
    -e MODE=Normal \
    -e DB_HOST=db:3306 \
    -e DB_NAME=DOCKER-SECRET:secret_db_name \
    -e DB_USER=DOCKER-SECRET:secret_db_user \
    -e DB_PASSWORD=DOCKER-SECRET:secret_db_password \
    --secret secret_db_name \
    --secret secret_db_user \
    --secret secret_db_password \
    startersclan/docker-hlstatsxce-daemon:v1.6.19-geoip-alpine-3.8

The entrypoint script takes care of expanding the environment variables DB_NAME, DB_USER, and DB_PASSWORD from the respective secret files /run/secrets/secret_db_name, /run/secrets/secret_db_user, and /run/secrets/secret_db_password. This is done by using the syntax ENVVARIABLE=DOCKER-SECRET:docker_secret_name (note the colon).

⁠Configuration

⁠Environment variables

In general, it is better to use environment variables than a config file, because it offers more configuration options. Use them only if:

1. not using a config file

2. using the config file ./hlstats.conf in same directory as hlstats.pl, but want to override the config file's settings.

⁠Configuration file, Command line parameters, and Database options

Configuration options are applied the following order. Later options override the earlier options.

1. Default config file ./hlstats.conf if it exists.

   • See code⁠

2. Command line parameters (Also applies to environment variables above which simply generate a command line).

   • See code⁠

3. (N.A. since bugged) Custom config file specified by command line parameter --configfile.

   • Doesn't work because of a bug explained here⁠

4. Database configuration from hlstats_options table.

   • See directives⁠

   • See code⁠

The following database configuration options override config file or command line parameter configuration. Looking in install.sql⁠:

• --dns-resolveip is enabled since parameter DNSResolveIP value is 1
• --dns-timeout is 3 since parameter DNSTimeout value is 3
• --mode is Normal since parameter Mode value is Normal
• --rcon is enabled since parameter Rcon value is 1
• --timestamp is disabled since parameter UseTimestamp value is 0

⁠Warning: If using CONFIG_FILE or --configfile

There is a bug in hlstats.pl that does not apply the command line parameter --configfile=<configfile> properly as configuration. To fix that, find the line in hlstats.pl⁠ on line 1821:

if ($configfile && -r $configfile) {

Add this code line before it:

setOptionsConf(%copts);

Save the file. That should fix hlstats.pl's --configfile argument issue.

⁠FAQ

⁠Q: Perl errors on startup?

A: This docker image runs perl5, but HLStatsX:CE 1.6.19⁠ might have been written for perl4 or early perl5 (not sure) and the project is no longer actively maintained. You will have to fix the compatibility errors, and rebuild a docker image based on this docker image.

From experience (of the author of this repo), there are quite a number of these kinds of bugs that can cause the daemon the crash. You might end up as a Perl Monk after having fixed them. :)

⁠Q: Error Unable to execute query: Illegal mix of collations (or similar)?

A: This error can happen when certain player names contain special characters (e.g. emoji or unicode). The fix is to convert all default collations in the DB tables to utf8mb4_unicode_ci, using the ALTER⁠ statement to convert all TABLE and their TEXT columns to DEFAULT CHARSET=utf8mb4 and DEFAULT COLLATE=utf8mb4_unicode_ci (See install.sql⁠). See here⁠ for a detailed explanation. To fix:

• If on HLStatsX:CE 1.6.19, copy this 79.php⁠ into the ./web/updater folder, login to the Admin Panel > Update DB and upgrade the DB version to 79 and HLStatsX:CE version to 1.6.20. The DB is now fixed.
• Alternatively, copy this tools_resetdbcollations.php⁠ and overwrite the existing ./web/pages/admintasks/tools_resetdbcollations.php, login to the Admin Panel > Reset All DB Collations to utf8mb4, and run the fixes. The DB is now fixed.

Additionally, to ensure the daemon's character set matches the DB tables' collation, use default_character_set=utf8mb4 in the mysqld config file (e.g. /etc/mysql/mysql.conf.d/mysqld.cnf):

[client]
default_character_set=utf8mb4
...

[mysql]
default_character_set=utf8mb4
...

[mysqldump]
default_character_set=utf8mb4
...

⁠Q: How to use GeoIP2 with the perl daemon?

A: As of HLStatsX:CE 1.6.19⁠, the perl daemon scripts uses GeoIP⁠, and not GeoIP2⁠. You will have to change a bit of the code yourself to use the GeoIP2 API⁠.

⁠Q: How long will this Docker Image be supported?

A: As long as the repository is not marked deprecated, which should not happen.

⁠Development

Requires Windows powershell or pwsh⁠.

# Install Generate-DockerImageVariants module: https://github.com/theohbrothers/Generate-DockerImageVariants
Install-Module -Name Generate-DockerImageVariants -Repository PSGallery -Scope CurrentUser -Force -Verbose

# Edit ./generate templates

# Generate the variants
Generate-DockerImageVariants .