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

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.

   • 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 .