search

MarechJ / hll_rcon_tool

Hell Let Loose Community RCON, CRCON for short. An alternative rcon client for HLL. It is a web application with many features, historical data, statistics, discord integrations, etc
MIT License
107 stars 72 forks source link
discordapp game hll rcon rcon-client

readme

Hell Let Loose (HLL) Community RCON (CRCON)

An extended RCON tool for Hell Let Loose, meant to replace the official tool and go WAY beyond.

Website Discord GitHub release (latest by date) Docker Cloud Automated build Docker Cloud Build Status Docker Pulls Code style: black README zh

ko-fi

Join us on Discord for feedback, troubleshooting and information about updates and general Hell Let Loose hosting info : https://discord.gg/hZx6gn3

Included features

Manage your games and players in realtime

Admin Accounts / Audit Trail

API / API Keys

Manage your players database

Automatic server settings

Settings that can be applied based on different conditions (time of day, number of connected players, current map, number of connected admins, etc.) Change most (but not all) game server/CRCON settings, including but not limited to :

Automatic Moderation

Auto Mods

Miscellaneous automatic enforcement of rules

Chat Commands

Discord Integration

Public stats webpage

Power users features

Some images

Manage your games and players in realtime

Live view page

Manage your players database

Player history overview

Automatic server settings

Settings

Permanent logs

Historical logs

Features to come (maybe)

Installation

Minimum skills

"I don't know anything about VPS, Linux, console commands, coding and such..."

Relax :

Install it on a VPS, not on your home PC

CRCON is designed to run permanently (24/7) as a website,
being accessible on the Internet for your players (to access public stats) and game server admins (to manage the games).

So, we strongly suggest you rent a cheap VPS to host your CRCON !

Why is it designed this way :

If you still decide to install it on a home computer, keep in mind you'll have to :

Hardware requirements

[!TIP] Some VPS providers rent this type of services for ~$5-10/month.
Some VPS providers even offer free installation of linux distributions in which Docker is already activated. Search/ask for it !

[!NOTE] You can run CRCON on as little as 3.x GB of RAM, but as it's not easy to increase the amount of RAM your VPS has, it's better to pad it a little bit. The more game servers you manage within a CRCON install, the more RAM/CPU/storage you'll need.

Software requirements

In theory, you can install CRCON on any operating system/architecture that runs Docker engine and Docker Compose plugin.
Unless you have a really good reason not to do so, you should use Linux.
This will ensure better tech support when you'll search for help on Google, as Docker and CRCON userbases are very scarce on Windows.
If you're unfamiliar with Linux, you are advised to pick a VPS plan using a popular distribution, like Ubuntu server or Debian.

If you really need to run it on Windows and have no other option, try using Windows Subsystem for Linux.

[!NOTE] We provide pre-built Docker images for linux/amd64 and linux/arm64.
If you use a different operating system or architecture, you will need to build your own images.

1. git

(Optional but highly recommended)

If you don't use git, you'll have to manually download and install the CRCON releases in .zip format, and you won't be able to update your CRCON as easily as with git)

You can check if git is installed by entering this command in your terminal : 

git version

You should get a reply like git version 2.34.1

If not, you'll find installation procedures on https://git-scm.com/download/

2. Docker Engine

[!WARNING] You can also try to use Docker Desktop, but you may encounter issues with nested virtualization, depending on your computer/server/VPS.

You can check if Docker engine is installed by entering this command : 

docker version

You should get a (multiline) reply like Client: Docker Engine - Community - Version 26.1.0...

If not, you'll find installation procedures on https://docs.docker.com/engine/install/

3. Compose plugin for Docker

[!CAUTION] docker-compose has been deprecated in july 2023, errors will occur if you try to use it.

You can check if Docker Compose plugin is installed by entering this command : 

docker compose version

You should get a reply like Docker Compose version v2.26.1

If not, you'll find installation procedures on https://docs.docker.com/compose/install/

4. Any text editor that supports syntax highlighting

(Optional but highly recommended)

The instructions below use nano, which is a tiny shell based editor that can be difficult to work with.
You should try Visual Studio Code, which is a free and fully featured text editor that allows you to remotely edit files over SSH which is very handy when editing files on your VPS.

Install steps

Stay cool and follow the drill. It's a simple installation, many not-so-technical people managed to do it, so you probably can too :)

[!TIP] All the commands given below are meant to be entered in a Debian-based (like Ubuntu) Linux terminal.

1. Download CRCON

Open an SSH session on your VPS. That's a text-only based terminal we'll use to enter commands on the distant VPS.

Windows users can use the PowerShell tool that's already available in their StartMenu. To launch it, open the StartMenu, search for PowerShell and click on its icon. Then, to connect to the VPS, just enter this command, where 123.123.123.123 is the VPS IP.

[!NOTE] all commands must be validated with the [Enter] key.

ssh root@123.123.123.123

You'll get a password prompt. Type the 'root' user's password, as given by the VPS provider (it won't display for security reasons), then [Enter].

You also can use an SSH client (don't know which one to get ? Try PuTTY : https://www.chiark.greenend.org.uk/~sgtatham/putty/),
log in as root into your distant Linux, using the SSH credentials given by your VPS provider.

Once you're in, enter these commands in the terminal (press the [Enter] key to validate) :

Download the CRCON files :

git clone https://github.com/MarechJ/hll_rcon_tool.git

Get in the newly created CRCON dedicated folder :

cd hll_rcon_tool

2. Edit the environment config file

Now, you're going to create and edit an .env file, in which you'll tell CRCON how to connect to your HLL game server(s).
Here we'll use nano, a simple text editor that runs in text mode.
You can use any other tool you're used to, either local or getting the file from a SFTP connection.

[!CAUTION] Do not edit default.env.
The file you're about to create must be named .env or Docker will not detect it.

Make a copy of the environnement config file template :

cp default.env .env

Install the nano text editor (debian-based command) :

apt update && apt install nano

Launch nano to edit the .env file :

nano .env

[!TIP] In nano, you can move the cursor with the arrow keys.

You do not have to change all the values. Only these 5 are mandatory :

2-1. Choose a password to give CRCON access to its database

HLL_DB_PASSWORD=anythingwithoutanyspace

[!TIP] No need to remember/note it : you'll never have to enter it anywhere.
Check the comments in the .env for restricted characters, such as %.

[!CAUTION] Do not change the password after CRCON has been started at least one time : your database would not be accessible.

2-2. Invent a string that will be used to scramble users passwords

The longer the better.

RCONWEB_API_SECRET=anythingwithoutanyspaceordollarsign

[!TIP] You may want to back this up separately. If you lose it, all of your admin accounts will be invalidated and need their passwords reset.

[!CAUTION] Do not change the string after CRCON has been started at least one time : existing passwords would be invalidated.

If you want to manage more than one game server, repeat the steps below for the 2nd, 3rd, etc.

2-3. RCON IP

As provided by the game server provider. This may be not the same as the game server IP.

HLL_HOST=123.123.123.123

2-4. RCON port

As provided by the game server provider. This is not the same as the game server port.

HLL_PORT=12345

2-5. RCON password

As provided by the game server provider.

HLL_PASSWORD=yourrconpassword

[!IMPORTANT] Triple-check there is no space before/after the = signs, nor in the values you've set.

3. Create a Docker Compose File

docker compose commands need a special file to know what to do.
This file will be created from a template.
If you intend to manage more than one HLL game server, you'll have to modify it to fit your needs.

The docker-templates/ folder contains two example templates :

[!CAUTION] Do not edit these files.

For docker compose to detect the file, it needs to be in project's root and named compose.yaml.

3-1. Managing a single game server

Make a copy of the one-server.yaml compose template :

cp docker-templates/one-server.yaml compose.yaml

That's it ! Go to step 4 (Run CRCON for the first time).

3-2. Managing two or more game servers

Make a copy of the compose template, then edit the newly created compose.yaml to fit your needs.

You can either :

There are two places that need to be updated for the compose.yaml to work properly, according to your servers number :

3.2.1 Networks

The networks section (at the top) must contain a definition for each server.

Add a network for each server you are using (look at docker-templates/ten-servers.yaml for examples)

  networks:
    common:
    server1:
    server2:
    server3:

[!NOTE] If you are no longer managing all the defined game servers, you can delete their dedicated networks.
Failing to do so won't hurt anything : it will just create extra unused networks.

[!CAUTION] Do not remove the common: network.

3.2.2 Services

The services section defines what containers Docker will actually start when you run commands like docker compose up -d, so you need to add a service definition for each server you are willing to run (or delete the ones you don't use).

For example, if you used one-server.yaml as your starting template for compose.yaml and you wanted to add a 2nd server, you would copy the appropriate section from docker-templates/ten-servers.yaml and add it to your compose.yaml :

########### SERVER 2  #############
  backend_2:
    <<: *backend
    environment: &env_2
      <<: *backend-env
      SERVER_NUMBER: ${SERVER_NUMBER_2}
      HLL_HOST: ${HLL_HOST_2}
      HLL_PORT: ${HLL_PORT_2}
      HLL_PASSWORD: ${HLL_PASSWORD_2}
      HLL_REDIS_DB: ${HLL_REDIS_DB_2}
      HLL_REDIS_URL: redis://${HLL_REDIS_HOST}:${HLL_REDIS_HOST_PORT}/${HLL_REDIS_DB_2}
      RCONWEB_PORT: ${RCONWEB_PORT_2}
      PUBLIC_STATS_PORT: ${PUBLIC_STATS_PORT_2}
      PUBLIC_STATS_PORT_HTTPS: ${PUBLIC_STATS_PORT_HTTPS_2}
      GTX_SERVER_NAME_CHANGE_USERNAME: ${GTX_SERVER_NAME_CHANGE_USERNAME_2}
      GTX_SERVER_NAME_CHANGE_PASSWORD: ${GTX_SERVER_NAME_CHANGE_PASSWORD_2}
      SENTRY_DSN: ${SENTRY_DSN_2}
    hostname: api_2
    networks:
      common:
      server2:
        aliases:
          - backend
  supervisor_2:
    <<: *supervisor
    environment:
      <<: *env_2
    depends_on:
      backend_2:
        condition: service_healthy
    networks:
      common:
      server2:
        aliases:
          - supervisor
  frontend_2:
    <<: *frontend
    ports:
      - ${RCONWEB_PORT_2}:80
      - ${RCONWEB_PORT_HTTPS_2}:443
      - ${PUBLIC_STATS_PORT_2}:81
      - ${PUBLIC_STATS_PORT_HTTPS_2}:444
    depends_on:
      backend_2:
        condition: service_healthy
    networks:
      common:
      server2:

[!CAUTION] You have to use the appropriate server numbers.
If you use the same server number twice, only one of them will start and you will encounter issues.

[!CAUTION] You need to be very careful and match the indentation levels appropriately or Docker will not be able to read the file.

4. Run CRCON for the first time

CRCON is now ready to start and connect to your HLL game server(s).

[!WARNING] Do not think it's over yet, as we now have to configure CRCON's users and secure the default admin account.

[!NOTE] Launch process will display a lot of scrolling text.
Don't panic, as you do not have to read/do anything. Just watch the magic.

Enter this command :

docker compose up -d --remove-orphans

If everything went well, you will see output similar to (this is an example for a single game server and edited to fit):

❯ docker compose up -d
[+] Running 8/8
 ✔ Network hll_rcon_tool_common            Created  0.1s
 ✔ Network hll_rcon_tool_server1           Created  0.1s
 ✔ Container hll_rcon_tool-redis-1         Healthy  0.2s
 ✔ Container hll_rcon_tool-postgres-1      Healthy  0.2s
 ✔ Container hll_rcon_tool-maintenance-1   Healthy  0.1s
 ✔ Container hll_rcon_tool-backend_1-1     Healthy  0.1s
 ✔ Container hll_rcon_tool-supervisor_1-1  Started  0.1s
 ✔ Container hll_rcon_tool-frontend_1-1    Started  0.1s

If any of the containers report an Error status, and/or if you see messages about Unhealthy services, something is misconfigured.
First thing to check :

5. Get in the CRCON UI

Your CRCON user interface can be reached from all over the world, in any web browser.

Each game server is accessed separately, pay attention to the RCONWEB_PORT values in your .env for each game server.

For example : by default, you can reach game server 1 on http://yourVPSIP:8010/
(substitute the IP address of your VPS for yourVPSIP in the URL).

[!WARNING] Do not touch anything yet. You'll have plenty of time to play with the different tools later.

6. Prepare to configure users

Due to inner security checks, we need to declare the VPS IP/port as "secure" to be able to enter the users management tool.
Failing to do so will lead to CSRF errors when accessing the admin panel.

"server_url": "http://123.123.123.123:8010/",

7. Restart CRCON

Yes. Restart it. This may sound strange, but it is mandatory :
to be taken in account, the server_url value you've just set has to be read during the CRCON Docker containers start.

docker compose down
docker compose up -d --remove-orphans

8. Configure users

Now you can get into the CRCON users management tool, located at : http://yourVPSIP:8010/admin

[!NOTE] You should be already logged in. If not, the credentials are still admin/admin.

Add a new user

Click on the + Add link.

readme_admin_account_setup_1

Fill the Add User form
Don't forget to enter the user's Steam ID (see image below) : it will be used by CRCON to identify this user as an admin.

readme_admin_account_setup_2

Click on the SAVE link.

Once the user is created, you'll end up on that page :

readme_admin_account_setup_3

[!WARNING] Don't forget to give yourself the Superuser status and staff status if you intend to disable the admin account !

[!NOTE] Users won't be allowed to change their password by themselves unless you check staff status on their profile.

To change the password of a user, click on its name, then on this link (see image below) :

readme_admin_account_setup_4

You also can change your current password using the dedicated link (top-right red square below) :

readme_admin_password_1

Change admin's default password

You MUST change the admin's default credentials, as they are insanely insecure.

[!TIP] (you also can disable admin's account by unchecking the Active status.
just make sure there's another user having Superuser status and staff status activated).

9. Basic configuration is over

🎉 Yes ! You did it ! You now have a fully working and secured CRCON ! Congratulations !

Take your time to explore all the menus and commands.

You'll find a lot of things to customize in the SETTINGS menus.
(Most of the settings are described/explained on their own page.
There is a lot of questions/answers about them on Discord, too).

We know the user interface isn't always intuitive :/
Someone is actually working on a tremendous new version (thanks @Dorf !).

If you have any question (or just want to come and say hi), feel free to join us on Discord.

Have fun !

[!NOTE] Feel free to support CRCON's development (thanks !).
The money will be used to reward contributing developers and people who create video tutorials, demos, documentation, etc.
paypal

Update to the latest version

Please join the CRCON Discord and follow announcements.
Sometimes, update instructions vary from standard.
If you are updating from an older version, you should review the announcements in order and make any non-standard changes in order.

Normal (most) updates

You also can download the latest zip release and install it manually (NOT recommended)

[!NOTE] If you get git error messages when you pull, you have to resolve these before you can upgrade.
(Unless you have been changing files, this should never happen).
It's important you get the sources every time, or at least the Docker compose files, as new dependancies might have been introduced.

Downgrade (in case of issue) to a previous version

Check the available versions numbers on Docker hub (or Github releases) :
https://hub.docker.com/r/cericmathey/hll_rcon_tool/tags
https://github.com/MarechJ/hll_rcon_tool/releases

Edit your .env file and change TAGGED_VERSION from latest to a specific tagged release
(it must match the release tag on Docker hub):

TAGGED_VERSION=9.4.1

Then restart

docker compose pull
docker compose up -d --remove-orphans

How to use

(Demo video coming soon)

There's a public endpoint available to anybody without password on http://yourVPSIP:7010/api/scoreboard

See the Wiki for instructions on how to use certain features of the app.

For power users

Multiple Game Servers

You can use one CRCON for multiple game servers, or have separate CRCONs for one (or more) game server(s), but they need to be set up differently (see below). If you run multiple game servers (for instance US west, US east and/or an event server), it makes more sense to do one CRCON install, rather than separate CRCONs for each game server.

One CRCON to manage multiple game servers

When using a single CRCON installation for multiple game servers, all of your admin accounts will have equal access to all of them, and all of your data will be stored in a single database.

This will make it difficult to separate your servers in the future (if you are trying to use one CRCON for multiple communities by sharing a VPS) without starting from scratch and losing data.

You will need to update your compose.yaml to have a definition for each extra server you want to run.
You can copy and paste each extra server from docker-templates/ten-servers.yaml (refer to the installation guide below for specifics)

Multiple CRCON installations

Please see the Wiki for instructions on managing multiple installs on the same host machine.

Building your own Docker images

Docker images are hosted on Docker Hub, but if you're running a fork, have made local modifications, are running CPU architecture we don't have pre-built images for, or the release you want isn't available for some reason, you can build your images locally.

Set environment variables

If you don't already have a .env file created use default.env to make a template, otherwise the build will fail due to unset environment variables:

cp default.env .env

If you don't have a .env, you must set the following environment variables to something, or the build will fail with an error that looks like invalid tag ":": invalid reference format (just use a copy of default.env):

BACKEND_DOCKER_REPOSITORY=
FRONTEND_DOCKER_REPOSITORY=
TAGGED_VERSION=

Create a Docker Compose file

Refer to the installation guide if you do not already have a compose.yaml file created.

Build the images

Building the images can take a significant amount of time and you must be connected to the internet for it to fetch resources.

docker compose build

Run it

Once the images are built (which can take a considerable amount of time depending on your hardware specs), and once it's configured properly (see the installation part of this README), then simply enter this command to create the containers :

docker compose up -d --remove-orphans

If you don't want to use docker compose (which you really should, it's just easier), then you would have to properly set/create/run the Docker containers yourself. Please consult Docker's documentation.

Development environment

Pull requests are always welcome ! It can be a bit tricky setting up a local environment and it is hard to contribute without having a HLL game server to connect to (and it's impossible to host one yourself, as T17 won't release the server files).

Overview / Project Structure

The project is split up into several main components :

It is intended to be run using Docker and docker compose.
Each CRCON install can manage multiple game servers, and each game server (server 1, server 2, etc.) has its own set of images (backend_1, frontend_1, supervisor_1, etc.).

rcon package

The rcon package relies on several core classes.

rcon.connection.HLLConnection handles connecting to the game server (IP, port and RCON password), xor encoding/decoding content and sending/receiving raw bytes over TCP sockets.

rcon.commands.ServerCtl is the parent class of Rcon and handles managing a pool of HllConnection instances, validating/converting low level stuff (like stripping tabs from user generated content for HLL tab delimited lists), automatically retrying commands that fail, and sending the raw commands (such as get profanity) to the game server.

rcon.commands.ServerCtl can be used without any database or redis connection, but is of limited use and not published separately.

rcon.rcon.Rcon inherits from ServerCtl and handles parsing/structuring the raw text received from the game server into meaningful data, interacting with the database, caching command results, etc.

CRCON is not an async (ASGI) web app (async) or multi core (multiprocessing), but it does support running multiple slow (to the game server) requests simultaneously through thread pools.

The rcon package also contains the implementation of most of CRCNs features, if you're not sure how something works, identify which API endpoint is doing the action, look in the URL routing in rconweb and you can see what parts of rcon are imported.

rconweb

The rconweb package is a Django web app that actually exposes all of the URL endpoints and imports from rcon as needed when interacting with the game server versus the local CRCON backend (redis, postgres, etc.).

Some endpoints are explicitly exposed, but some (Rcon methods) are implicitly exposed (rconweb.api.views.expose_api_endpoint).

supervisord

Due to the fact that Python is notoriously single threaded, some core parts of CRCON have been broken out into services that run in their own Python interpreter, so they can take advantage of multiple cores/threads on the system.
This also enables faster network access since each individual network request (to the game server, steam API, Discord, etc.) blocks until completion.

Other portions are optional services and have been split so users have more control over what runs.

The services are managed by supervisord and run inside of their own (supervisor) container.

redis

Redis is used for two reasons in CRCON, caching and interprocess communication.

Every round trip to the game server can be significantly slow (in computing terms) and induces some amount of overhead on both CRCON and the game server.

Some commands are cached, even if they have a very low cache time (such as retrieving logs from the game server) to avoid constantly reprocessing info on very short time frames and others are on a longer cache time because they rarely (if ever) change (such as the list of available maps from the game server).

This also condenses requests that occur almost simultaneously to be reduced to a single request that makes it to the game server, the remaining requests will be resolved from the cache (unless they happened before the first request has completed and cached its results).

Many portions of CRCON run in their own separate Python interpreter instances with their own section of memory, but by caching results with redis, we can communicate back and forth between interpreter instances. This is used both explicitly with rq to run tasks (such as recording game stats to the database, or bulk VIP uploads) and implicitly when something caches function results in redis and is accessed elsewhere.

postgres

CRCON uses postgres 12 with a default configuration.

Running a local/development instance

To run a local instance of CRCON without using the Docker images requires you to do some manual set up.

If you have never successfully run the complete CRCON environment from this install, you should do so first so that the database is created/initialized properly. (If you only ever plan on running the tests, you can do this without seeding the database). If you've done this, you can skip the database migrations/user creation below. It's just easier to do it this way, so I recommend it but it is optional.

Because of some configuration differences and how Docker determines environment variable precedence, I recommend using separate shells to run local instances and to run the full blown production Docker setup.

To avoid polluting your system Python, you should create/activate a virtual environment, I use pyenv but set up is outside the scope of this README.

Once the virtual environment is activated in your shell install all of the Python dependencies :

pip install -r requirements.txt
pip install -r requirements-dev.txt

Set environment variables

You can use dev.env as a template for what variables need to be set, and after filling in the missing portions, from your shell:

Or you can manually set them as specified in the sections below.

source dev.env

SERVER_NUMBER is an integral part of how CRCON works and is how data is segregated between servers in the database and is normally set in the compose files.

export SERVER_NUMBER=1

The HLL_DB_PASSWORD password must match what you set when the database was first created, or you can connect to the postgres docker container and reset the password for your database user if needed.

The default username and database name is rcon if you've seeded the database, unless you've configured it differently.

export HLL_DB_PASSWORD=rcon_dev
export HLL_DB_NAME=rcon
export HLL_DB_USER=rcon
export HLL_DB_HOST=localhost
export HLL_DB_HOST_PORT=5432
export HLL_DB_URL=postgresql://${HLL_DB_USER}:${HLL_DB_PASSWORD}@${HLL_DB_HOST}:${HLL_DB_HOST_PORT}/${HLL_DB_NAME}

Running the development backend

Make sure you set all of the environment variables from the previous section(s).

You can sort of run a local instance without a game server to connect to, but so much depends on one that it's pretty pointless to try to do this without one.

export HLL_HOST=<your game server IP>
export HLL_PORT=<your game server RCON port>
export HLL_PASSWORD=<your game server RCON password>

If you didn't run the production environment first : create the database tables (you only need to do this once, unless you've created new migrations).

PYTHONPATH=. alembic upgrade head
PYTHONPATH=. ./manage.py init_db
PYTHONPATH=. ./rconweb/manage.py makemigrations --no-input
PYTHONPATH=. ./rconweb/manage.py migrate --noinput

Alembic runs the database migrations which creates the tables, and init_db installs a postgres extension and sets default values for auto settings.

makemigrations and migrate creates the required Django database tables.

If you didn't run the production environment first: Create a superuser account and follow the prompts:

PYTHONPATH=. ./rconweb/manage.py createsuperuser

Set the redis environment variables:

export HLL_REDIS_HOST=localhost
export HLL_REDIS_HOST_PORT=6379
export HLL_REDIS_DB=1
export HLL_REDIS_URL=redis://${HLL_REDIS_HOST}:${HLL_REDIS_HOST_PORT}/1

Both the redis and postgres containers should be running (or you should have a redis and postgres installed/configured if you don't want to use the Docker images):

docker compose up -d redis postgres

Start the Django (backend) development web server:

DJANGO_DEBUG=true DEBUG=true PYTHONPATH=. ./rconweb/manage.py runserver --nothreading

If you've set all the environment variables correctly, initialized the database and started the Django web server, you'll see something similar to:

System check identified some issues:

    WARNINGS:
    api.DjangoAPIKey: (models.W042) Auto-created primary key used when not defining a primary key type, by default 'django.db.models.AutoField'.
            HINT: Configure the DEFAULT_AUTO_FIELD setting or the ApiConfig.default_auto_field attribute to point to a subclass of AutoField, e.g. 'django.db.models.BigAutoField'.
    api.SteamPlayer: (models.W042) Auto-created primary key used when not defining a primary key type, by default 'django.db.models.AutoField'.
            HINT: Configure the DEFAULT_AUTO_FIELD setting or the ApiConfig.default_auto_field attribute to point to a subclass of AutoField, e.g. 'django.db.models.BigAutoField'.

    System check identified 2 issues (0 silenced).
    December 28, 2023 - 22:35:19
    Django version 4.2.7, using settings 'rconweb.settings'
    Starting development server at http://127.0.0.1:8000/
    Quit the server with CONTROL-C.

You can now open your browser (or use any other tool like Postman) to make API calls (http://127.0.0.1:8000/api/ will list all the available endpoints), or use the admin site (http://127.0.0.1:8000/admin/).

Any changes to the files in rcon/ or rconweb/ will cause the backend webserver to reload with the changes.

Running the development frontend

Once you have the development backend running, from another shell you can run the development frontend web server:

cd rcongui  
npm install  
npm start

You should see something similar to:

VITE v4.3.9  ready in 320 ms

➜  Local:   http://localhost:3000/
➜  Network: use --host to expose
➜  press h to show help

You can now open your browser (http://localhost:3000/) to use the frontend, any modifications to the frontend (javascript files) in rcongui will cause it to recompile/update.

Running services

Running the Django development web server only starts the backend web server which accepts HTTP requests, it won't start any of the services that would be started in a production environment.

Some of these services are required if you want the frontend to work as expected, such as log_loop (runs all of the hooks) or log_recorder that saves log lines to the database.

Each service you want to run either needs to be run in the background or needs to be run in a separate shell (don't forget to set environment variables in each shell).

# Calculates player stats for the scoreboard
PYTHONPATH=. ./manage.py live_stats_loop
# Runs hooks (on connected events, on kills, etc.)
PYTHONPATH=. ./manage.py log_loop
# If you want logs to be saved in the DB
PYTHONPATH=. ./manage.py log_recorder

Those service are run by supervisor in the production setup, so if you want more info check config/supervisor.conf

Running Tests

Unfortunately at this moment in time the database needs to be running for the tests to run. The tables don't actually need to exist.

From the root hll_rcon_tool directory:

PYTHONPATH=. DEBUG=TRUE pytest tests/

If you don't set PYTHONPATH you'll see errors similar to ModuleNotFoundError: No module named 'rcon'.

If you don't set DEBUG to a truthy value, you'll see errors about not being able to connect to redis.

To test if your changes will work with the production setup, start the whole stack

This should be done from a separate shell without the environment variables set, or they'll override what is set in your .env file because of how Docker determines precedence and you won't be able to connect to redis or postgres properly.

Building the frontend if you've made any changes to the javascript files or if the build cache isn't available can take a considerable amount of time.

docker compose build
docker compose up -d

Now test on http://localhost:8010

General notes

If you have problems with dependancies or versions of python or nodejs, please refer to the respective Dockerfile that can act as a guide on how to setup a development environment.