Backend: Setting up a local development environment

Why do I need a local development environment?

Note: VSTS stands for Visual Studio Team Services.

Since Fizzyo backend is a complex system, there are multiple non-trivial steps you have to follow to setup your own local backend instance. Some developers think that this initial effort is not worth it, and choose to use the online staging environment instead. This approach is not desirable, as it makes development less efficient in the long-term.

What you lose if you only use the staging environment:

• ❌ You have to wait for your code to be deployed every time you make a change. This means that even if you change a single letter in your code, you need to spent at least a minute to see your change in action. This is because you'll need to open the VSTS web portal to trigger a new deploy, and then wait 40 or more seconds for VSTS to build the source code, upload it to the server and wait for apps to be restarted.
• ❌ You never know if your data will be there tomorrow. Imagine you're testing a new feature and you added some dummy data to the staging database, just to play around with the implementation. Since safety of the staging database is not guaranteed, someone can delete all of your data or drop the whole database entirely.
• ❌ Your work can clash with the work done by someone else. If you're both trying to deploy a new feature to the staging environment at the same time and there's a bug in your code, trying to figure out whose code was the culprit becomes a nightmare.
• ❌ You develop bad Git commit habits. Since the only way to deploy code to the staging environment is by creating a new commit, many developers make one-line commits with rubbish titles like Tweak code or Trigger deploy. This is a bad practice since it makes it hard to figure out which commit changed what.

What you gain if you setup a local development environment:

• ✅ You can test your changes almost instantly. Since you're working locally, there is no need to push any code online. There's also no need to wait for VSTS to deploy your code to the Fizzyo server.
• ✅ Your local database is safe. Since your local database is hosted on your machine, you're the only one who can make changes to it, meaning you will never lose development data because someone else dropped the database.
• ✅ You are less likely interrupt someone else's work. Oftentimes the staging environment is used for demos and presentation to end users. You don't want to ruin someone's presentation by pushing broken code online because you couldn't test it locally.
• ✅ The Git commit log for Fizzyo-backend stays nice and clean. Since you can debug everything locally, you don't have to create any new commits until you're confident that the new feature works as expected. Once you're done, you can push the feature as a single commit (with a descriptive commit message).

Fizzyo backend deployment instructions

Instructions below should only be used to setup your own local development environment, do not use them for production/staging environments.

1. Installing Node.js

Install Node.js v8.11.x. Node installation includes a package manager called npm. Confirm you have the right versions by running the following commands:

$ node -v                                   
v8.11.4
$ npm -v
5.6.0

Make sure your Node version is v8.11.x. You might have to update npm using npm install -g npm, any 5.0+ version should work fine.

You could potentially use an older/newer version of Node to run the Fizzyo backend, but it's not recommended.

2. Fetching and building the source code

First of all, you need to get access to Fizzyo VSTS. If you can access the Fizzyo-backend repo page, you already have the required permissions. Otherwise, contact Yun Fu, Kunal Kapoor or Tim Kuzhagaliyev so they can add you to our VSTS portal.

Then, choose a folder on your machine where you want to store the Fizzyo backend source code. Since there are multiple Fizzyo repositories, I suggest you create a folder called fizzyo and put all repositories inside it.

Option 2A: Using SSH keys (recommended)

Follow these instructions to create an SSH key and add it to your account. Then clone the backend repository into the folder you chose:

$ cd fizzyo/
$ git clone [email protected]:v3/uclix/Fizzyo/Fizzyo-backend

Options 2B: Using HTTPS

This option is slightly more inconvenient since you'll have to type in your VSTS credentials every time you want to push something online. Either way, you can just clone the repository using HTTPS:

$ cd fizzyo/
$ git clone https://uclix.visualstudio.com/DefaultCollection/Fizzyo/_git/Fizzyo-backend

3. Setting up a local PostgreSQL database

See instructions on this page.

4. Preparing config.json

In step 3, you should have created a copy of config.example.json (that comes with the source code) and renamed it into config.json. You should have also edited the devDbUrl and testDbUrl fields in the config. If you haven't done so, please go to step 3 and complete these actions.

Once you're done, change the following fields in your config.json:

• Set apiUrl to http://localhost:1234.
• Set dbToUse to dev.
• Update windowsLiveClientId and windowsLiveClientSecret to contain Fizzyo's Windows Client ID and secret respectively. These values are confidential - contact Kunal Kapoor or Tim Kuzhagaliyev to get them.

5. Running the web API and a data validator instance

First we need to install all dependencies. Open terminal, go to the Fizzyo-backend folder and install npm packages:

$ cd Fizzyo-backend/
$ npm install

This step shouldn't produce any errors. If it does, don't panic - it's probably one of the common npm usage mistakes. Googling the error message should help you find the solution. Next, we need rebuild documentation:

$ npm run apidoc

Finally, we can start the web API:

$ npm start              # on Linux
$ npm run start-windows  # on Windows

If you're working extending the data validator, you might want to use commands below to start it too. Note that you will need to open a new terminal window if you want to have both the API and the validator running at the same time.

$ npm run start-validator          # on Linux
$ npm run start-validator-windows  # on Windows

6. Checking that everything works as expected

There are several things you can do to make sure everything works correctly. First, run unit tests:

$ npm run test

If some unit tests fail, there is probably something wrong with your npm dependencies. Try reinstalling them. Once you fixed all of your issues, we can try running database integration tests:

$ npm run test-db

If some tests fail now, there is probably something wrong with your DB setup. You should try to fix it. If all tests pass, then your setup is most likely functioning as expected.

You can also do some manual testing. Open http://localhost:1234/ in your browser and confirm that it loads successfully and shows you API endpoint documentation. Then, open http://localhost:1234/auth-example and try to register. To do that, you'll need a Microsoft account. On a fresh Fizzyo-backend install, you should be able to use the invitation code first-invitation.