ClueTracker

A service that records Clue Games, including the players and cards involved, and all known facts about which players hold, or do not hold, or may have shown, which cards.

Develop

The frontend is based on ReactJS. The backend/API is based on Python's Django Rest Framework.

The frontend lives in the frontend/ directory, the backend lives in the cluetracker/ directory.

Dependencies

For the frontend, first install Node version 16 or higher. Then, within the frontend/ directory, run:

npm install

For the backend, first install Python version 3.8 or higher.

Then, within the cluetracker/ subdirectory (where the manage.py file lives), setup and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Finally, install the dependencies with pip-tools:

pip install pip-tools
pip-sync requirements.txt dev-requirements.txt

In the first command, replace python3 with the name or full path of your Python 3 executable, if different.

Whenever you work with the backend, first ensure that the virtual environment is activated.

If you're looking for a clean way to install and maintain the correct Node and Python versions on your system, recommend using nvm and pyenv, respectively.

Configuration

To configure both frontend and backend apps locally, adjust the variables defined in the .env files within each respective folder, according to your needs.

For the backend, you will also have to make sure the environment variable DJANGO_READ_DOT_ENV_FILE is set to the value of True, otherwise Django will simply ignore your .env file.

For now, since self-registration and login via the UI is not implemented yet, you need to create an admin user in the backend, in order to allow the frontend to talk to the backend/API. Make sure the variables in frontend/.env file match whatever credentials you setup here:

python manage.py createsuperuser

Running the development servers

Open two terminal windows.

In the first, from the cluetracker/ directory, run:

python manage.py migrate  # run the database migrations (if not already)
python manage.py runserver

Access the API server on http://localhost:8000/api/games.

In the second, from the frontend/ directory, run:

npm start

Access the web server on http://localhost:3000.

Running tests

For the backend, tests are run with:

python manage.py test games.tests.test_api
python manage.py test games.tests.test_models

For the frontend, tests are run with:

npm test

Developing frontend with Storybook

You can use Storybook to develop the frontend React components in isolation. This way, you can see, test, and evaluate each component separately, viewing all of its possible states, without needing to integrate it into your entire webpage.

To start the Storybook interface, run:

npm run storybook

A browser window for Storybook should pop up, where you can browse your various components that you've defined Stories for. See Storybook docs on their website for more info.

Docker

You can run the frontend and backend apps together in a closer-to-production setup -- using a Postgres database instead of the development server's default SQLite -- using Docker.

1. Install Docker and docker-compose.
2. Clone the repository.
3. cd into the repository root.
4. Adjust the environment variables in the .env-docker files and .env-docker-postgres if necessary.
5. Run docker-compose build.
6. Run docker-compose up.
7. Access the API server on http://localhost:8000/api/games.
8. Access the web server on http://localhost:3000.

If the api service fails at first because postgres is not available yet, stop all the docker containers (without destroying them) and try again. (TODO: Implement a check-and-wait till postgres is up, using e.g. django-probes.)

Create an admin user, and make sure the variables in frontend/.env-docker file match whatever credentials you setup here:

docker-compose exec api python manage.py createsuperuser

To run tests:

docker-compose exec api python manage.py test [my.tests.module]
docker-compose exec web npm test