Setup a development environment

If you attempted/completed these steps and you have any questions or feedback, please contact me at iamlogandavidson@gmail.com.

Operating system

This guide is mainly aimed at Windows users, but the frontend and backend apps both run on Linux systems in production, so getting it running on UNIX systems like Linux or macOS should be pretty straightforward.

Visual Studio Code

The project contains a Visual Studio Code workspace file called roronline.code-workspace. If you use VS Code as your editor, I recommend opening the project via the workspace rather than the folder.

How to setup a new local development environment

Prerequisites

• Git is installed. This can be downloaded here: https://git-scm.com/downloads.

• Node is installed. This can be downloaded here: https://nodejs.org/en/download.

• Docker is installed. This can be downloaded here: https://docs.docker.com/get-docker/.

• Python 3.11 is installed. This is the Python version that is used in production and it's recommended that you use the same version of the language in development. At the time of writing, the latest release of Python 3.11 is 3.11.4, which can be downloaded here: https://www.python.org/downloads/release/python-3114/.

• PostgreSQL 12 is installed. This can be downloaded here: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads.

  • When installing Postgres, you will be prompted to create a password for the postgres superuser. Remember this for later.

• You have a Google account and access to Google Cloud Platform.

Steps

1. Clone this repository.

   • If you're not sure how to do this, here is one way:

     1. Download GitHub Desktop from here: https://desktop.github.com/.
     2. Sign in to your account in GitHub Desktop.
     3. Follow this guide: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository.

Backend

2. Create a Python 3.11 virtual environment called env in the backend folder.

   • This can be done by opening a terminal or command prompt in the backend folder and executing this command. Remember to replace C:\Python\Python38\python with the correct path to your Python 3.11 executable.

     C:\Python\Python38\python -m venv env
     

3. Activate the virtual environment.

   • Now that you've created a Python virtual environment, you must understand how to activate and deactivate it. To execute any Python commands in this project you will need to do so within the virtual environment. This guide covers activation and deactivation of the virtual environment: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/.

   • Remember to always activate your virtual environment in the backend folder. This is where you will execute all your Python commands.

     From here on out, every time this guide instructs you to enter a command starting with python or pip, it is implied that you should enter the command in the activated virtual environment in the backend folder.

   • Ensure that your virtual environment is using the correct version of Python by entering this command. The command should return Python 3.11.4.

     python --version
     

4. Update pip using this command.

   python -m pip install --upgrade pip
   

5. Install packages from requirements.txt using this command.

   pip install -r requirements.txt
   

6. Create a Google Auth Platform client for Google authentication.

   • In the Google Cloud Platform online management console, create a new project then navigate to Google Auth Platform.

   • Configure Google Auth Platform by creating a new app named "Republic of Rome Online".

   • In the Data Access tab, add scopes for ./auth/userinfo.email, ./auth/userinfo.profile and openid.

   • In the Clients tab, create a new client with the following settings:

     Application type: Web application
     Name: Local development web client
     
     Authorized redirect URIs:
     URIs 1: http://localhost:8000/accounts/google/login/callback/
     URIs 2: http://127.0.0.1:8000/accounts/google/login/callback/
     

   • Take note of the Client ID and Client secret.

7. In the backend folder, create a new file called .env with this content.

   ALLOWED_HOSTS=127.0.0.1
   FRONTEND_ORIGINS=http://127.0.0.1:3000
   DEBUG=True
   PARENT_DOMAIN=127.0.0.1
   RDS_HOSTNAME=localhost
   RDS_NAME=postgres
   RDS_PASSWORD=rdspassword
   RDS_PORT=5432
   RDS_USERNAME=postgres
   REDIS_HOSTNAME=127.0.0.1
   SECRET_KEY=abc123
   SOCIALACCOUNT_GOOGLE_CLIENT_ID=googleclientid
   SOCIALACCOUNT_GOOGLE_SECRET=googlesecret
   

   • Replace rdspassword with the password you created for the postgres superuser during PostgreSQL installation.
   • Replace googleclientid with the client ID for your Google Auth Platform client.
   • Replace googlesecret with the secret for your Google Auth Platform client.

8. Ensure that the PostgreSQL server (a background service) is running.

   • If you have just installed PostgreSQL, the server may not be running.

   • On Windows, you can use Services.msc to check which services are running, manually start the server and configure automatic startup behaviour. Look for the service whose name begins with "postgresql". This guide covers basic usage: https://www.thewindowsclub.com/open-windows-services

9. Syncronize the database with Django's models and migrations using this command.

   python manage.py migrate
   

10. Create an application superuser with this command.

    python manage.py createsuperuser
    

    • You will need to provide a username and password. The email address is optional.

11. Start a Redis instance inside a docker container using this command.

    docker run -p 6379:6379 -d redis:5
    

12. Start the backend development server using this command.

    python manage.py runserver
    

    • Ensure that the backend server is running by visiting http://127.0.0.1:8000. If you are able to access the web browsable API and the Django admin portal, that means you have successfully setup up the backend.

Frontend

13. Now in the frontend folder, create a file called .env with this content.

    BACKEND_URL=http://127.0.0.1:8000/
    

14. Install packages and start the frontend server using npm.

    • In the frontend folder, open a terminal or command prompt and enter these commands. The first command installs required packages and the second command starts the frontend development server.

      npm install
      

      npm run dev
      

    • Ensure that the frontend server is running by visiting http://localhost:3000. Login in using the credentials you provided in step 9. If that works, congratulations! You have successfully set up the Republic of Rome frontend and backend development servers on your local machine!

How to update an existing local development environment

Prerequisites

• The steps in "How to setup a new local development environment" have been completed previously.

• The Python virtual environment has been upgraded to use the version of Python specified above.

• Environment variable names and values are up to date.

Steps

1. Update the backend by executing these commands in the backend folder, using the Python virtual environment.

   • Install packages from requirements.txt using this command.

     pip install -r requirements.txt
     

   • Syncronize the database with Django's models and migrations using this command.

     python manage.py migrate
     

2. Update the frontend by executing this command in the frontend folder.

   npm install