gyrinx

This repository contains the Gyrinx Django application. The code for this application is in the gyrinx directory.

See the docs directory or the Google Doc for technical discussions. Access to the Google Doc is limited to contributors and admins.

Table of Contents

• Technical Overview
• Development
• Setup
• Running the Django application
• Building the UI
• Running Tests
• New data migration
• Debugging SQL
• Content library for development

Technical Overview

Gyrinx is a Django application running in Google Cloud Platform. It runs in Cloud Run, a serverless application platform, with Cloud SQL (specifically, Postgres) for data storage. Cloud Build is used to deploy the application. The frontend is built with Bootstrap 5.

The code is hosted here on GitHub. When new code is pushed on main to the gyrinx repo, it is automatically deployed by Cloud Build. This includes running database migrations. Code is tested automatically in GitHub Actions.

Analytics are through Google Analytics.

Project tasks, issues and to-dos are managed in the Gyrinx GitHub Project.

Development

To run Gyrinx, you will need Docker with Compose. You'll also need a recent Python version: pyenv is a good way to manage installed Python versions.

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

Setup

To set up the development environment, follow these 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.