Skip to content

Latest commit

 

History

History
135 lines (99 loc) · 6.17 KB

DeveloperSetupGuide.md

File metadata and controls

135 lines (99 loc) · 6.17 KB
Raw

Developer Setup Guide

Follow these steps to start contributing to the UCT Locator Project.

Getting the Software

You will want to download and install all of these things to begin:

Getting the Code - Cloning from GitHub

The code for the project is stored on GitHub.

Getting the Repository URL

The first thing to do is get the URL for the repository where the code lives.

  1. Open up the UCT Locator project in GitHub
  2. Click the green "Code" button
  3. In the pop-up, make sure the "HTTPS" tab is selected
  4. Click the button to copy the repository URL

Now you have the URL that points to the project code!

Cloning the Repository Locally

Next, it's time to pull down the code by cloning it with git.

  1. Open Visual Studio Code
  2. Click the gear icon in the lower left to open the "Manage" menu
  3. Click "Command Pallette..." at the top to open the command pallette
  4. There, type in "Git: Clone" and press Enter
  5. Next, paste in the copied repository URL, and press Enter
  6. In the file explorer, select a folder (like the Desktop) for the repository location
  7. On the pop-up that appears, click "Open" to open the repository folder

That's it! Now you have access to all the code in the repository.

Configuring the Application

The code from the repository is all there, but you still need to do a couple of things before the application is ready to run.

Creating the Back-End Environment File

For the back-end of the application to work properly, it needs a database. The code is setup to search for the database URI in an environment file - .env.

  1. In Visual Studio Code, open the File Explorer on the left
  2. Click on the back-end folder to expand it
  3. With the back-end folder selected, click the "New File..." icon
  4. Enter ".env" for the filename, and press Enter

Open the new back-end/.env file for editing, and add these two lines:

SECRET_KEY="thisissecret"

Local Database

To run the application locally you will need to have a running Postgres database. Easiest option to run this is by using docker. This command will allow you to spin up a Postgres database with the PostGIS extension already installed.

docker-compose up -d

We also spin up an instance of pgAdmin4 to make querying the database easy. It runs on http://localhost:5050.

Login credentials can be found in the docker-compose.yaml file.

Create a .env to connect to your database

The following properties should allow the database to connect. If you modified the sql script above then they may differ slightly.

NODE_ENV=local
POSTGRES_USERNAME="developmentuser"
POSTGRES_PASSWORD="real-dev-password-here"
POSTGRES_DB="developmentdb"
POSTGRES_HOST="127.0.0.1"
POSTGRES_PORT=5432

Creating the Front-End Environment File

In addition to a back-end file, there is also a front-end .env. This file allows access to the Google Maps API - basically, the thing that creates and runs the interactive map in the UCT Locator app.

Follow the same basic steps as above, this time creating a new .env file within the front-end folder.

Open the front-end/.env file for editing, and add this line:

REACT_APP_GOOGLE_MAPS_API_KEY=<google-key-here>

The actual API key for Google Maps is not published here. Replace <google-key-here> in the .env file with the API key that should be provided. Optionally, create your own Google Maps API key by following this guide.

Installing Application Packages

There is one thing left to do before the application is ready to run. There are a ton of packages that the application needs to use - these are big libraries of code that other people or organizations have created.

  1. In Visual Studio Code, open the Terminal menu from the top
  2. Select "New Terminal" to open a new terminal
  3. In the terminal that appears, enter npm install and press Enter

Once the command is done running, all the necessary packages should be installed!

Running the Application

Now the application should be all ready to run! You will need to run both the front-end and the back-end to have a fully functional local application.

  1. In Visual Studio Code, open the File Explorer on the left
  2. At the bottom of the pane, click the "> NPM SCRIPTS" box to expand it
  3. Expand the back-end\package.json section
  4. Find the server script and click the "Run" button to the right
  5. Expand the front-end\package.json section
  6. Find the start script and click the "Run" button to the right

Both commands should open up their own terminal windows and execute. After a minute, both the front-end and back-end should be up and running!

The front-end start command should automatically open up a web browser window with the application loaded. By default, the front-end should run on localhost:3000, and the back-end should run on localhost:5000.

The homepage should look something like this:

Conclusion

Hopefully by following this guide, you were able to get the UCT Locator application up and running! The next step will be to start digging into the code and trying to make sense of how everything currently works. This could also be a great time to learn more about some of the technologies the application uses.