/docker-hlstatsxce-daemon

Dockerized HLStatsX:CE perl daemon 🐳

Primary LanguageDockerfileGNU General Public License v3.0GPL-3.0

docker-hlstatsxce-daemon

github-actions github-release docker-image-size

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

Tag Dockerfile Build Context
:v1.6.19-emailsender-ubuntu-16.04 View
:v1.6.19-geoip-ubuntu-16.04 View
:v1.6.19-geoip-geoip2-ubuntu-16.04 View
:v1.6.19-geoip-geoip2-emailsender-ubuntu-16.04 View
:v1.6.19-geoip-geoip2-emailsender-curl-ubuntu-16.04 View
:v1.6.19-emailsender-alpine-3.8 View
:v1.6.19-geoip-alpine-3.8, :latest View
:v1.6.19-geoip-geoip2-alpine-3.8 View
:v1.6.19-geoip-geoip2-emailsender-alpine-3.8 View
:v1.6.19-geoip-geoip2-emailsender-curl-alpine-3.8 View

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.

Tag component Perl Modules
geoip Geo::IP::PurePerl
geoip2 MaxMind::DB::Reader
MaxMind::DB::Reader::XS
emailsender Email::Sender::Simple

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:

Tag component Tools Description
curl curl, wget, openssl Useful for cron job containers for notifications or webhooks

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.

Name Default value (as in hlstats.pl) Description Corresponds to hlstats.pl argument
CONFIG_FILE "./hlstats.conf" Path to config file. May be absolute or relative -c,--configfile
LOG_LEVEL "1" Log level for debugging 0 - -n, --nodebug
1 - -d, --debug
2 - -dd, --debug --debug
MODE "Normal" Player tracking mode (Normal, LAN or NameTrack) -m, --mode
DB_HOST "localhost" Database IP or hostname, in format <ip>:<port> or <hostname>:<port>. Port may be omitted, in which case it is 3306 by default. To use a custom port, use format <ip>:<port> or <hostname>:<port> specifed. --db-host
DB_NAME "hlstats" Database name --db-name
DB_USER "" Database user --db-user
DB_PASSWORD "" Database password --db-password
DNS_RESOLVE_IP "true" Resolve player IP addresses to hostnames (requires working DNS) --dns-resolveip
DNS_RESOLVE_IP_TIMEOUT "5" timeout DNS queries after SEC seconds --dns-timeout
LISTEN_IP "" IP to listen on for UDP log data --ip
LISTEN_PORT "27500" Port to listen on for UDP log data --port
RCON "true" Enable rcon to gameservers --rcon
STDIN "false" Read log data from standard input, instead of from UDP socket. Must specify STDIN_SERVER_IP and STDIN_SERVER_PORT to indicate the generatorof the inputted log data (implies --norcon) -s, --stdin
STDIN_SERVER_IP "" Data source IP address. Only required for STDIN --server-ip
STDIN_SERVER_PORT "27015" Data source port. Only required for STDIN --server-port
USE_LOG_TIMESTAMP "false" for UDP; "true" for STDIN Use the timestamp in the log data, instead of the current time on the daemon, when recording events -t, --timestamp

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.

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

  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.

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 .