Prerequisites

1. Make sure you have Python installed on your computer. (Instructions for installing found here.)
2. Make sure you have mySQL (both Client and Server) installed and set up on your computer. (Instructions for installing found here.)

---

Instructions

Setting up initial files

1. Clone this repository onto your computer. If you need help cloning a repository, instructions for cloning a repository can be found here.
2. Two essential files must be sent individually to the user for security reasons. These files are:

   1. settings.py: This file, when received, should be placed in the directory named mysite.

   2. enchanted_circle_map.html: This file, when received, should be placed in the directory named templates. The file path for templates is: map_app/templates.

Setting up Python Virtual Environment

1. In the FireFlight folder (the main folder) using the terminal/PowerShell/command line, create a Python Virtual Environment (venv) folder named '.venv'. This requires proper installation of Python. Creation of the virtual environment may take up to one or two minutes.
   • For Windows: In the FireFlight folder, run this command in PowerShell (in the FireFlight folder!): python -m venv .venv
   • For Mac and Linux: In the FireFlight folder, run this command in your terminal (in the FireFlight folder!): python3 -m venv .venv
   • Complete instructions found here if needed.
2. Run the following command in the terminal from the FireFlight folder to activate the virtual environment (venv):
   • Windows: .venv\Scripts\Activate
   • Mac/Linux: source .venv/bin/activate
3. If the virtual environment is active, you will see (.venv) before your current PATH.

• Note: To deactivate the virtual environment (venv) at any point, run this command: deactivate.

Setting up the MySQL database

1. Open the MySQL command line client. This requires the proper installation and set up of a MySQL Server. (Detailed instructions found here for help opening the command line client.) Ensure that the server is currently running.
2. Create a new database for the web application to use. Write down the name of this database now.
   • Run this command in the MySQL command line client, replacing database_name with a name of your choosing: CREATE DATABASE database_name;
3. Create a new user for the web application to access the database from. Write down the name and password for this user now.
   • Run this command in the MySQL command line client, replacing user_name with a username of your choosing, and password with a secure password: CREATE USER 'user_name'@'localhost' IDENTIFIED BY 'password';
4. Grant permissions to the user to have full access to the database you have created.
   • Run this command in the MySQL command line client, replacing user_name with the username you created above, and database_name with the name of the database created above: GRANT ALL PRIVILEGES ON database_name.* TO 'user_name'@'localhost';

Connecting Django to the database

1. Open the file settings.py, which is in the mysite directory.

2. From lines 103 to 111, you will see a variable named DATABASES, with default field values for NAME, USER, and PASSWORD. Using the database name, user name, and password created in the previous section, replace each of the corresponding variables (keeping the quotation marks).

   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.mysql',
           "NAME": "database_name", # change this
           "USER": "user_name", #change this
           "PASSWORD": "password", #change this
           "HOST": "", # only change this if you are hosting your database externally!
       }
   }
   

   • On line 106 ("NAME": "database_name",), replace database_name with the name of the database created in Step 2 of "Setting up the MySQL database".
   • On line 107 ("USER": "user_name",), replace user_name with the username of the user created in Step 3 of "Setting up the MySQL database".
   • On line 108 ("PASSWORD": "password",), replace password with the password for the user created in Step 3 of "Setting up the MySQL database".

3. Remember to save your changes to this file before closing it.

Installing local dependencies

1. In the FireFlight folder (the main folder) using the terminal/PowerShell/command line, activate your virtual environment (see "Setting up Python Virtual Environment" Step 3 for the command to activate it).
2. Once the virtual environment is active, run the following command: pip install -r requirements.txt. This will install all the local dependencies needed for FireFlight to run properly into your virtual environment folder. This process make take several minutes to complete.

• Note for Windows Users: If permission is denied to run remotely signed scripts, see our troubleshooting page.

Setting up Django with the database

More information on Django migrations can be found here.

1. In the FireFlight folder (the main folder) using the terminal/PowerShell/command line, activate your virtual environment if it is not already activated (see "Setting up Python Virtual Environment" Step 3 for the command to activate it).
2. Run the following command: python manage.py makemigrations map_app. This will create the migrations to be applied in the next step.
3. Run the following command: python manage.py migrate. This will apply the migrations previously created to the project and database.

Creating a Django superuser

More information on creating a Django superuser can be found here. Creating a superuser allows you to access the Django Admin panel for the website in your browser (while the website is running).

1. In the FireFlight folder (the main folder) using the terminal/PowerShell/command line, activate your virtual environment if it is not already activated (see "Setting up Python Virtual Environment" Step 3 for the command to activate it).
2. Run the following command: python manage.py createsuperuser. This will start the process of creating a superuser.
3. You will be prompted to enter a username for your new superuser. Enter your desired username, and write it down now.
4. You will be prompted to enter an email address. Enter a valid email address, and proceed to the next step.
5. You will then be prompted to enter a password for your new superuser. Enter a secure password that you will not forget, or write it down now and keep it somewhere safe. Note: While typing your password, characters will not appear on the screen for security reasons.
6. You will now be prompted to confirm your password. Confirm your password, and the superuser will be created in the database.

Next Steps

Proceed to Uploading Data & Manually Generating Maps to populate your newly created MySQL Database and generate the initial map files. This must be done before Running the Server Locally for the first time.