Noob Guide

You want to set up Lego front-end and/or back-end locally on your computer? You ask for help, but they just tell you to check the readme on GitHub which only says “npm install”? Don’t worry, I’ve got you covered: here’s a complete guide on how to go from scratch to a (hopefully) fully functional set-up.

disclaimer: this noob guide was written by a noob. There are probably mistakes everywhere.

Last updated 04.02.2016

Linux

Short versions (Full guide below)

Front end

SSH key

1. $ cd
2. $ cd .ssh/ (mkdir .ssh/ if needed)
3. $ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
4. $ cat id_rsa.pub
5. Copy the key from your terminal to GitHub.com (Settings > SSH key)

Downloading the files

1. $ sudo apt-get install git
2. $ cd <workfolder>
3. $ git clone git@github.com:webkom/lego-webapp.git

Getting NPM

1. $ sudo curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
2. $ sudo apt-get update && sudo apt-get -y upgrade
3. $ sudo apt-get install nodejs

Setting up and running the server

1. $ cd lego-webapp
2. $ npm install yarn
3. $ yarn install
4. $ yarn

Back end

Downloading the files

1. $ sudo apt-get install git (if needed)
2. $ cd <workfolder>
3. $ git clone git@github.com:webkom/lego.git

Virtual environment

1. $ sudo apt-get install python3 python3-dev build-essential python-pip libpq-dev postgresql
2. $ sudo pip install virtualenv
3. $ cd lego
4. $ make venv
5. $ source venv/bin/activate

Installing requirements

1. $ sudo pip install -r requirements/dev.txt

Finishing up

1. $ docker-compose up -d (If you don't have Docker, get that)
2. echo "from .development import *" > lego/settings/local.py
3. $ python manage.py initialize_development
4. $ python manage.py runserver

Done!

Full guide (outdated)

Front End

The front-end consists mainly of the JavaScript files we use to generate the visual part of the website. We use the React library, and almost everything that doesn’t directly interact with databases resides on the front-end. Front-end is much easier to set up than the back end, as we don’t have to set up any local databases. However, most applications won’t be very interesting until we have set up back-end as well as most of the actual content resides on the back-end. Let’s start with front-end, though!

Our first goal is to copy the actual files down from GitHub onto your computer

SSH key

If you already have validated your computer with a SSH key, skip this step.

Because the files are only available to members of the GitHub project, we first have to validate your computer so GitHub knows it can trust you with the files. This is done by generating a so-called SSH key on your computer, and then copypasting that over to your validated user on GitHub.com.

1. Open your terminal, and navigate to your root folder by typing “cd”.

2. Navigate as such:

   $ cd .ssh/ ($ mkdir .ssh/ if needed)

3. Enter the following command to generate your SSH key. Note that you might have to re-type the “” signs inside the console.

   $ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

   Replace the dummy mail with the one you use on GitHub.

4. Enter the following command to print the SSH key you just made:

   $ cat id_rsa.pub

5. Copy the huge block of text you just printed. It should start with “ssh-rsa” and end with your e-mail.

6. Log in to GitHub.com, and navigate to Settings > SSH key for your user. Create a new key with some title (i.e. which computer you’re on) and paste the SSH key into the appropriate field.

Congratulations, the first step is done! Your computer is validated with GitHub, and you have access to all the files and folder there.

Downloading the files

The next step is to downlaod the files from GitHub to your computer.

1. Make a folder that you want your files to reside in. This could for example be called “webkom”, and you could place your back-end files here too if you intend to set that up later.

2. Close your old terminal window and open a new one. We use git for all of our projects, and if you don’t already have it installed, type the following:

   $ sudo apt-get install git

3. Navigate to the folder you created earlier using cd-commands, and type the following to download all the front-end files (easy, right?):

   $ git clone git@github.com:webkom/lego-webapp.git

And that’s it! You now have all the latest front-end files saved locally on your computer, located under a folder called lego-webapp.

NPM

Skip this part if you already have NPM installed. NPM is a tool that lets you manage packages, and you will need to to download and install many of the programs we need to set up the front-end. If you’re not sure whether you’ve got NPM install, type npm -v in your terminal. If you see some version numbers, you’re good to go.

1. We start by ensuring that we have all the necessary packages available, and also run an update to minimize the chance of errors:

   $ sudo curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -

   $ sudo apt-get update && sudo apt-get -y upgrade

   $ sudo apt-get install nodejs

   The easiest way to install npm is to install together with nodejs, which we just did. If you still dont have npm, type

   $ sudo apt-get install npm

   but this shouldn’t be necessary. You now also have nodejs available, which you might find handy in plenty of projects.

Setting up and running the server

Almost there! All that remains now is to install and run the server. As scary as that might sound to some, we’re lucky enough that npm does all the work for us!

1. Navigate to the lego-webapp folder, and type the following: $ npm install
2. Once the install is complete, you’re done! Start the server as such: $ npm start
3. Open your browser and type the following in the adress line: localhost:3000

And that’s it! Now you should hopefulyy see everything the front-end is able to dislpay without any content from the back-end. The terminal windows needs to be kept open for the server to keep running. If you would like to stop the server without closing the terminal, simply press Ctrl+C. Whenever you want to start the server, simply navigate to the lego-webapp folder and type npm start.

Back End

For the website to be any interesting, it needs content you can add and remove, users who can log in, and dynamic applications the users can interact with. All of these and more come from the back-end. While the front-end handles displaying content and processing most user interaction, the back-end handles all communication the the database. This includes posts, users, events, and any other aspect that we want to easily add, edit and store.

SSH key

If you didn’t set up the front end before coming here, you need to validate your computer with GitHub before anything else. You can do this by following the guide in the front-end section of this guide.

Downloading the files

We download the files in exactly the same way we did for the front end

1. Make a folder that you want your files to reside in. If you made a “webkom” folder for your front end files, you could choose that one.
2. We use git for all of our projects, and if you don’t already have it installed, type the following: $ sudo apt-get install git
3. Navigate to the folder you created earlier using cd-commands, and type the following to download all the back-end files: $ git clone git@github.com:webkom/lego.git

And that’s it! You now have all the latest back-end files saved locally on your computer. The folder will simply be called “lego” by default, and I will be referring to it as such in this guide.

Virtual environment

This is the first proper step is setting up the back-end. It’s where we get our feet wet, and I can’t guarantee this will all work exactly as intended. If at any point you get an error, do your best to google the issue and find a solution. If you get stuck, ask someone for help and try to learn from their solution.

A virtual environment, or venv for short, is roughly explained a simulation of a new user on your computer. You can “log in” to this user, and any changes you make or programs you install while logged into this user will only affect that user. This lets you install whatever and mess around with the issues that will undoubtedly arise without screwing up the rest of your computer. In addition, it is needed for several of the program we use to run the back-end, so we start by installing a venv.

1. Before anything else,  we download all of these packages. Some are needed for venv to work properly, some are needed for the local database we’ll be setting up, and others just seem to need to be there. Don’t think too hard about it.

   $ sudo apt-get install python3 python3-dev build-essential python-pip libpq-dev postgresql

   $ sudo pip install virtualenv

2. Navigate to the folder with your back-end files.

3. Create your very own virtual environment!

   $ make venv

4. “Change user” to your new venv:

   $ source venv/bin/activate

All the commands you enter from now on will onlt affect your venv. You need to change your source to this venv, as we call it, every time you want to run the server.

That’s a lot of progress done! Your venv is up and running, which is where all of your back-end work will be done. We still haven’t set up our local datebase though, which is the next step:

Database - postgresql

The whole point of our back-end is to handle communication with the database. Without an actual database to test with, there is a very limited amount of stuff to do with our files. This is the last step of the journey, and although it’s probably also the least intuitive one, we’ll guide you through every step. Stay strong!

We’ll now use a program called postgresql, which severely lessens the amount of database interaction we have to do. In this step we will be giving commands to postgresql directly instead of the usual terminal input, so keep that in mind.

1. Postgres:

   a. We start giving commands to postgres like this:

   $ sudo su postgres

   b. Until you press CTRL+D, you will now be issuing commands through postgres. Crease a database user for yourself with admin right as such:

   $ createuser --superuser <YourName>

   c. Make a database “shell” like this:

   $ createdb <YourName>

   d. CTRL+D to exit postgres.

2. Now we can make the actual database we’re going to use with psql, using postgres’ “shell” and your superuser that we just made:

   $ psql -c “CREATE DATABASE <YourName>”

3. Even though we’ve now made our database, there are a lot of things that still need to be install, configured and set up. Luckily for us, almost all of the commands we would have to run have been saved to a script, which we can run by typing the following:

   $ make development

   This will amongst other things install Django, which is the library we write our entire back-end code in.

4. Almost there! We’ve done almost everything we need to, but one command not including in make development is this one, which loads the initial settings of the project:

   $ python manage.py load_fixtures

5. And that’s it! Now all that’s left is to start the server, which is done as such:

   $ python manage.py runserver

And your server is up and running! It can be accessed on localhost:8000, but because of our specific configurations you will have to go to

localhost:8000/api/v1

to see any content. Well done!

Congratulations, you’re done! If you’ve set up both front-end and back-end correctly, you should now be able to see content from the back-end displayed on the frond-end. Happy programming!

OSX

On OSX, most of the guide is equal to the Linux guide. However, there are some slight differences. First, you need to use homebrew instead of apt-get. To install homebrew, type the following:

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once you have homebrew, follow the linux guide, replacing “apt-get install” with “brew install”. Note that some libraries have different names, such as python-pip when using apt-get changing name to pip when using homebrew.

In addition, setting up the database for the back-end is slightly different. Once you have installed the required packages, type

$ brew info postgres

And follow the guide there on how to get postgres running. It should be as simple as copypasting a few terminal commands. Once you’re done, type

$ createdb <YourName>

And then continue following the Linux guide starting with $ make development