Quick Start

Quick Start

Prerequisites

• Install Git

• Install Node.js v12 or v14

• Install Docker:

  • Linux: first install the engine, then install docker-compose
  • Windows: install Docker Desktop on Windows and Make for Windows
  • Mac - install Docker Desktop on Mac

• Verify that the installations have succeeded. You should be able to run these commands and get similar output:

  $ git --version
  git version 2.17.1
  
  $ node --version
  v14.5.0
  
  $ npm --version
  6.14.5
  
  $ make --version
  GNU Make 4.1
  ...
  
  $ docker --version
  Docker version 19.03.12, build 48a66213fe
  
  $ docker-compose --version
  docker-compose version 1.25.5, build 8a1c60f6
  

• Clone the repo, and install the Node.js dependencies of this project:

  $ git clone git@github.com:unicsmcr/unics_social_api.git
  # or you can clone with HTTPS
  
  $ cd unics_social_api
  
  $ npm install

---

Configuration

• You now need to create an .env file - this is a configuration file for the project. You can just copy the included .env.example to create yours. I would not recommend changing most values (exceptions being the SendGrid variables, detailed below) unless they cause problems.

Email Service

The email service is responsible for sending emails to users, e.g. email address confirmations - this requires a SendGrid API key. You have two options:

1) Use the mock email service (recommended)

Instead of actually sending out emails, you can set up the mock email service. This will create a directory called emails, and create files containing emails that were meant to be sent. This is the easiest method, and requires setting MOCK_EMAIL_SERVICE=true in your .env file and that's it!

Once you no longer need an email, you can either delete the file itself or the emails folder - it won't break anything.

2) Create a SendGrid API key

If you'd like to actually receive the emails, you'll need to create a SendGrid API key and go through Single Sender Verification for an email you have access to. You then need to set this email address and the SendGrid API key in the .env file (SENDGRID_FROM_EMAIL and SENDGRID_TOKEN respectively.) You should also set MOCK_EMAIL_SERVICE=false to disable the mock email service.

This is due to security reasons on SendGrid's side which disallow you from using noreply@unicsmcr.com as you cannot prove you have access to that email, so the service is unable to send email as if it is from that address. This is why you have to use a personal email address that you have access to.

---

Running

• Launch the PostgreSQL database and its admin tool:

  $ docker-compose up -d
  # The -d flag means detached, so that the Docker process does not block your terminal.

• Launch UniCS Social Server!

  $ npm start
  # Whenever you make changes, you will need to re-run this command.

• After you've made changes, you can run tests to ensure that nothing broke and the coverage is still high!

  $ npm test
  

• You can shutdown the database and its admin tool once you're done:

  $ docker-compose down
  

---

Accessing the database admin tool for the first time

Once your database and admin tool are active (see previous step, docker-compose up -d), you can connect to the admin tool to interact with the database with a friendly GUI.

1. Visit http://localhost:5050 in your Internet browser of choice.

2. You should be greeted with a login screen. Assuming you haven't changed the related .env variables, the email should be admin@admin.com and password should be password (secure!)

3. Time to connect the server to the admin tool! Click on Add New Server under "Quick Links"

4. A pop-up window should open, fill it in with the following details and click Save (again, if you have changed the .env variables, make changes where appropriate):

5. That's it! The tool is now set up!

---

Finding data in the database

1. Open the admin tool as described above and login.

2. Navigate the tool as shown below. You can right click on a table and click View/Edit data to view the data in a table.

   

» Next page: Development Tools