Skip to content

Setting Up for Development

Jump to bottom
Julian Edwards edited this page Jul 11, 2024 · 8 revisions

This project uses VS Code development containers.

Prerequisites

Linux users should install Docker Engine, Docker CLI & Docker Compose.

Windows and macOS users will need Docker Desktop. Windows users should also ensure WSL2 is enabled.

More info on ensuring your Docker installation is compatible with VS Code dev containers can be found here.

Configuring the development environment

  1. Ensure you've installed the above prerequisites and your form of Docker is running.

  2. Start VS Code.

  3. Clone the repository

    • Use CTRL+SHIFT+P and select the task Dev Containers: Clone Repository in Named Container Volume and follow the instructions to clone this repo.
    • This will error as the .env file is not available. Accept the option to reopen in a recovery container.

  4. Setup development .env variables

    • Copy the .devcontainer/.env.empty file to .env, then add your RAWG API token to the RAWG_API_TOKEN variable (not publicly available, request it or make your own).
    • Use CTRL+SHIFT+P and select Dev Containers: Rebuild Container to apply the change.

The repository will cloned into a Linux volume for the dev container to use which should be faster for Windows and macOS users.

Upon connecting to your dev container, it will start up a development MySQL database in Docker for you.

  1. Use CTRL+SHIFT+P and select Tasks: Run Task, First Time DB Setup to create and migrate the database.

  2. Use CTRL+SHIFT+P and select Tasks: Run Task, Dev to start the client and api. You're now ready to start developing.

  3. Connect to the app on your host machine at localhost:5173.

Pushing commits & continuous delivery

As this app and repo are set up for CD, you should be aware of the basic setup and processes that will occur when pushing to the repo.

If the cloud infrastructure for the app isn't set up, you'll need to follow the instructions in Setting Up the CD & Cloud Infrastructure to configure it first.

Even if the infrastructure is available, you should be aware of the state of the Elastic Beanstalk application and its configuration. Familiarize yourself with Continuous Delivery and Hosting.

Working with your development database

This project uses database migrations and these must be run to get the database into a usable state.

During development you will work with a completely local and fresh database. Any pre-existing data for users, games or entries will have to be provided by database seeding.

VS Code Tasks for working with the database

First Time DB Setup - Creates and migrates the database to the latest version.

Create Database - Creates the database if it doesn't already exist.

Migrate Database - Runs all migrations.

Seed Database - Populates the database with test data.

Clear Database - Clears all data from the database. Used for testing.

Creating new migrations

You can use the Sequelize CLI to generate migration scripts and models.

Models generated by the CLI must be manually converted to typescript. They must also be manually updated to reflect changes in the database caused by additional migrations.

Migration scripts must remain Javascript. CLI generated migrations will also often need manual tweaking, e.g. adding constraints to columns.

To see exactly what files are going to be used by the CLI on running migrations you can look at the .sequelizerc file.

Viewing or manually interacting with the database

The dev container contains the SQLTools extension for connecting to and running commands against the database.

Open the SQLTools tab on the left in VS Code and select the dev-db connection. It should be pre-configured and you can authenticate with "devpassword".

The .vscode/useful_queries directory contains saved SQL scripts you might want to use for exploring the database.

Automated testing

The app has basic testing for the frontend with Vitest and React Testing Library.

  1. Make sure the database is initialized with First Time DB Setup or other commands listed above.

  2. If the API server isn't running, start it by hitting CTRL+SHIFT+P and selecting Tasks: Run Task, then Start API or Dev (if you want to start Vite as well)

  3. Hit CTRL+SHIFT+P and select Tasks: Run Task, Test.

    • This will clear the database, seed it with test data and run automated testing.
Clone this wiki locally