Skip to content

Setup Guide

Jump to bottom
Alistair Madden edited this page Mar 12, 2018 · 7 revisions

Software Installation

First of all, if you're not using some kind of unix-like operating system (linux, osx, freeBSD, ...) life is going to be more painful. For most people, Ubuntu is a great operating system for development work. If you have the space on your HDD (or dare I say SSD or NVMe drive) you can even dual boot!

With this warning out of the way, let's run down the list of things you'll need to have installed on your system.

  • Git - for cloning of, committing to and keeping up to date with the website repository.
  • NodeJS (Latest LTS (v8.10.0 at the time of writing)) - this is what the back end of the website runs on.
  • NPM (v5.6.0 or better. Included with NodeJS) - for package management. Think apt for JavaScript. Sort of. NPM handles all the packages needed to run the website so there should be no issues with "my package x is the wrong version" or "my operating system doesn't support package x". If you can run npm in your terminal you're pretty much good to go!

All of these things are available for Windows but YMMV. There is no reason why it shouldn't work. Versions have been given, but don't feel they need to be strictly adhered to. The latest Long Term Support (LTS) of any of this software should be sufficient. If you have any issues, don't hesitate to reach out on the CompSoc Slack!

With these programs installed, you should be able to follow the quick start guide:

Git

The first step is to clone this repository:

Navigate (using the terminal/command line) to the directory you'd like to place your project directory in

mkdir a_suitable_directory && cd a_suitable_directory

Then clone the repository!

git clone https://github.com/ducompsoc/website.git compsoc_website

If you do not have git installed, get it here.

This will place a folder compsoc_website inside the folder a_suitable_directory.

Navigate to your newly created project folder

cd compsoc_website

You can check the contents of directory by typing ls in bash (Mac and Linux) or dir (Windows).

The branch initially checked out is the master branch of the project. This branch will always contain the latest release of the website.

The develop branch is where all the new features are branched from and merged into using a strategy similar to the one found here.

To view all your local branches (that is, branches present on your machine) use

git branch

If you have been following these instructions you should only see the master branch.

To access the develop branch, we need to check it out

git checkout develop

This creates a local branch called develop which tracks (is linked to) the remote branch (the branch on the github repository).

Running ls or dir once more will highlight any changes in files.

But it's the same folder? Why have the files changed? That's git at work. For more information on git, see the excellent documentation.

Node and NPM

The website's back end runs on the nodejs runtime. Head over to https://nodejs.org/en/download/ and download the LTS (long term support) version for your platform.

Once installed, run

node

in your terminal/command line to check that node has been installed. A little carat should appear. To get back to the command line, type .exit or hit ctrl+C twice.

Also check npm is installed correctly

npm

If the terminal gives you a bunch of information (the NPM help page) then you are in good shape.

NPM is Node's Package Manager and is used to install third party libraries and frameworks. The package.json file in the root (top most) directory of the project (compsoc_website if you've been following along) stores all the modules that project relies upon.

Running

npm start

in your terminal/command line downloads the project's modules and their dependencies (via npm install) and runs the file app.js with node (via node app.js). If all is well, you should be greeted with the message

Example app listening on port 9000!

Navigate to localhost:9000 in a web browser (just type it in as you would a URL) and you should recognise the CompSoc website!

Where to go next: This tutorial was too simple - I just want to know how to edit pages! I'm following along, this seems to make sense. What else do I need to know?

Clone this wiki locally