Skip to content

Guide for Developers

Jump to bottom
Humberto Navarro edited this page May 8, 2023 · 22 revisions

Setup Developer Environment

1. Basic setup

  1. Install Node.js Recommend using version 14
  2. Install git
  3. Clone OCC Club Website Project
    • Method 1:
      • Open the command line, navigate the directory you want to clone the project
        • For windows, cd dir_1/dir_2/...
        • For macOS and Linux, cd ~/dir_1/dir_2/...
      • Type git clone https://github.com/Computer-Science-Club-OCC/Computer-Science-Club-OCC.github.io.git
    • Method 2:
  4. Install your favorite IDE or code editor. We recommend Visual Studio Code. (if you already have an IDE you can skip this step)

2. Front-end setup

  1. Open the project folder with your IDE, and type cd client on the terminal.
  2. To install front-end packages, run npm install
  3. To build, run npm run build
  4. To start the front-end, run npm start. The browser opens automatically with url http://localhost:3000
  5. In case lint errors appears, run npm run format:fix to format files, then start the front-end server

3. Backend setup

  1. Install MongoDB Community version 5 from https://www.mongodb.com/try/download/community.
    Please follow the instructions of the OS you are using from https://www.mongodb.com/docs/manual/installation/

    • After installation,

      • For Windows:
        • Open Edit System Environment Variables > Environment Variables.
        • At User variables for <your_username> select Path > Edit.
        • Add the path you installed MongoDB. For example: C:\Program Files\MongoDB\Server\5.0\bin
      • For Linux:
        • In the terminal, check sudo systemctl status mongod. If not active, do sudo systemctl enable mongod
        • Note that the test runner will fail on systems with versions of libssl > 1.1 due to an incompatibility of mongodb memory server.

    • Check MongoDB if it was installed by typing mongo --version in the terminal.

    • It is optional to install MongoDB Compass GUI for easily interacting with the database. Or, you can interact with it on the terminal by the mongo command.

  2. Open the project folder with your IDE, and type 'cd backend` on the terminal.

  3. Run npm install to install packages

  4. Run npm start to run the backend server. 127.0.0.1:8000 is the backend url.

  5. For testing API, recommend using Postman or Insomnia

(Optional if not using Docker) Using MongoDB for macOS

Assuming you installed mongo using homebrew, follow these instructions (originally from here)

  1. In your terminal, run brew services start mongodb-community@5.0.
  2. Using MongoDB Compass, connect to the URI: mongodb://127.0.0.1:27017
  3. The backend terminal should now display the text:
    MongoDB status: Connected
    cs_club Collection is available
  4. In MongoDB Compass, you can now add data to the empty collections within occ_csc.
  5. Once finished, run brew services stop mongodb-community@5.0

4. Docker & Docker Compose setup

We recommend installing Docker Desktop, which includes Docker Engine, CLI client, and Docker Compose. Docker Compose will create a containerized environment for the frontend, backend, and mongo, so you don't have to worry about creating a separate mongo database and the versions of all dependencies will be consistent with other developers.

Go to "Install Docker Desktop" for your respective OS and follow the instructions to install here.

For easy development within VS Code, you can also install the Docker extension through Microsoft here.

  • To quickly start the entire stack on any machine with docker:

      1. First make sure your Docker Desktop is running

      2. If developing in a different branch/PR, run docker-compose build --no-cache

      3. Run docker-compose up in the root folder's terminal. (You should not have to cd into the frontend or backend folder)

      Note: The first time this is run, building the container will take around 10 minutes.

  • To run just a mongo instance:

      docker-compose up -d mongo

  • Stopping the environment:

      docker-compose down

  • Rebuild All Containers:

      docker-compose build

  • Cleaning Docker Env Deleting the mongo container will delete all data in the database

  • Stop the container(s) using the following command:

      docker-compose down --volumes

  • Delete all images using the following command:

      docker image prune -a

Contribute to Project

1. Assign

2. Raise an Issue

  • If you engage bugs or have ideas for the project, go to Issue on the club website repo and create a new one
  • Add tags for issues in the Labels section on the right
  • An image to describe the issue is recommended for clarity
  • On the right panel, Projects section, add "CS website issues", then select ToDo

3. Create a branch & start the project

  • On your IDE, if you had GitHub plugins, create a new branch from main
  • Name your branch as following formats:
    • <your_name>-<issue_title> if you work on an issue
    • <your_name>-<feature_name> if you work on a feature that is not stated on github issue

       Please, do not add <>. These formats also apply to forked repos

  • Run the docker commands to automatically start the project (Docker & Docker Compose setup)
    • For manual steps:
      • Locate /client and /backend folders on the terminal and run npm install for both if packages are not installed
      • Start frontend server and backend server. Use http://localhost:3000 to view the output of the website
  • Start implementing your code on the branch

4. Push a commit

  • Before you commit:
    • For frontend: run npm run lint then fix any lint errors. Then run npm run format:fix.
    • For backend, run npm run lint then fix any lint errors. Run npm run test to test. Then npm run format:fix.
  • Add all formatted files to the commit
  • If you see any errors or warnings on the terminal after you run the format command. You must fix those errors, and format them again.
  • Push your commit

5. Raise a PR

  • Create a PR, on the left side of the arrow select Computer-Science-Club-OCC/Computer-Science-Club-OCC.github.io, choose main.
  • Add descriptions for your PR. Have a good summary of your overall commits, and include WHY you made them. Adding images to describe your PR is recommended. Make sure you mention the issue you assigned earlier by #issue_number in the description.
  • Assign yourself at Assignees, and add tags at Labels
  • Assign a Reviewer if you think your PR is ready to merge
  • Fix bugs based on the reviewer's feedback
  • Once the reviewer approves, you can merge your PR to main branch
Clone this wiki locally