gyrinx

This repository contains the Gyrinx Django application - a gang management tool for Necromunda. The code for this application is in the gyrinx directory.

📚 Full Documentation - Technical overview, architecture, and development guides.

Prerequisites

Before getting started, you'll need:

• Python 3.12+ - Use pyenv to manage versions
• Docker with Compose - For the database
• Git - For version control

Quick Start

# Clone and enter the repository
git clone [email protected]:gyrinx-app/gyrinx.git && cd gyrinx

# Set up Python environment
python -m venv .venv && . .venv/bin/activate
pip install --editable .

# Configure the application
manage setupenv

# Set up frontend toolchain
nodeenv -p && npm install && npm run build

# Start the database and run migrations
docker compose up -d && manage migrate

# Run the application
manage runserver

Visit http://localhost:8000 to see the application.

Development

There's a devcontainer configured in this repo which should get you up and running too, perhaps via a Codespace.

The Django manage.py file (in scripts/) is added to your shell by setuptools, so you can just use manage from anywhere:

manage shell

Detailed Setup

The Quick Start above gets you running fast. For more detailed steps:

1. Clone the repository:

   git clone [email protected]:gyrinx-app/gyrinx.git
   cd gyrinx

2. Make sure you're using the right Python version:

   python --version # should be >= 3.12

   If you use pyenv, we have a .python-version file. If you have pyenv active in your environment, this file will automatically activate this version for you.

3. Create and activate a virtual environment:

   python -m venv .venv && . .venv/bin/activate

4. Install the project in editable mode so you can use the manage command:

   pip install --editable .

   setuptools will handle installing dependencies.

5. You should then be able to run Django manage commands. This one will set up your .env file:

   manage setupenv

   With that run, you'll have a .env file with a random and unique SECRET_KEY and DJANGO_SUPERUSER_PASSWORD:

   cat .env

6. Next, set up the frontend toolchain:

   Get nodeenv (installed by pip earlier) to install node and npm in the virtual env.

   nodeenv -p

   Check it has worked (you might need to deactivate then . .venv/bin/activate):

   which node # should be /path/to/repo/.venv/bin/node
   which npm # should be /path/to/repo/.venv/bin/npm

7. Install the frontend dependencies:

   npm install

8. Build the frontend:

   npm run build

9. Install the pre-commit hooks:

   Before making any changes, make sure you've got pre-commit hooks installed.

   pre-commit is installed by pip.

   pre-commit install

Running the Django application

1. Make sure your virtual environment is active & pip has up-to-date dependencies:

   . .venv/bin/activate
   pip install --editable .

2. Start the database (Postgres) and pgadmin:

   docker compose up -d

3. Run the migrations:

   manage migrate

4. Run the application:

   manage runserver

You can also run the application itself within Docker Compose by passing --profile app, but this will not auto-reload the static files.

Building the UI

The Python toolchain installs nodeenv which is then used to install node and npm so we have a frontend toolchain.

To continuously rebuild the frontend (necessary for CSS updates from SASS):

npm run watch

Running Tests

To run the test suite, we also use Docker (so there is a database to talk to):

./scripts/test.sh

For faster test execution using parallel workers:

./scripts/test.sh --parallel
# or
./scripts/test.sh -p

You can also run tests directly with pytest for more control:

# Run tests in parallel (requires pytest-xdist)
pytest -n auto

# Run tests with database reuse (faster for repeated runs)
pytest --reuse-db

# Combine both for maximum speed
pytest -n auto --reuse-db

You can also use the pytest-watcher:

ptw .

New data migration

To create a new empty migration file for doing data migration:

manage makemigrations --empty content

Debugging SQL

You can debug the SQL that Gyrinx is running using the Django Debug Toolbar that is installed.

You can also enable SQL logging by setting the SQL_DEBUG variable:

SQL_DEBUG=True

Content library for development

To test Gyrinx locally, you are really limited unless you have the content library data available. This is because the content library is what provides the data for the Gyrinx application to work with.

The content library is managed by the Gyrinx content team in production, and is what makes Gyrinx useful.

Gyrinx uses a custom-ish data export/import process to manage content library data from production, so you can test locally.

Note

This process is only available for trusted developers and admins.

1. Export: Run the gyrinx-dumpdata Cloud Run job in production to export content to the gyrinx-app-bootstrap-dump bucket
2. Import: Download latest.json from the bucket and use manage loaddata_overwrite latest.json to replace local content data

This process ensures we have access to the latest production content library. See docs/operations/content-data-management.md for details.