Developer Guides ‐ Development environment - MarechJ/hll_rcon_tool GitHub Wiki

🧭 You are here : Wiki home / Developer Guides / Development environment

Prerequisites

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

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.