gyrinx

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

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

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 build 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/content.git
   cd content

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

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