Skip to content

Latest commit

 

History

History
220 lines (144 loc) · 6.99 KB

01-installation-steps.md

File metadata and controls

220 lines (144 loc) · 6.99 KB

Quick start guide

Security checks

All development laptops must be encrypted. If you are not 100% sure, please ask for help.

Check your Mac

  • Choose Apple menu > System Preferences
  • Security & Privacy.
  • Click the FileVault tab.
  • ensure that FileVault is enabled for your disk

Checking Linux (including desktop machines)

Follow this link and enter the relevant search string for your system.

Obtain AWS credentials

  1. Fork Janus and follow the readme (Note: you will need permission to access the Janus repo to do this, and 2FA set up on your Google account)
  2. Make your change and push to a new branch (you can review the closed PRs for help)
  3. Submit a PR
  4. You may need to pip install awscli and add /Library/Frameworks/Python.framework/Versions/Current/bin to your $PATH to run the commands Janus gives you.

Local dev server setup

Before checking out the repository you may need to add your guardian email address to your github account and add an SSH key to your GitHub account. Before pushing changes you may need to create an access token. Make sure your dev manager has added you to the necessary teams, in case you have need write access.

You need a Mac or Linux PC (Ubuntu).

Automatic

  1. Check out the repository:

    $ git clone [email protected]:guardian/frontend.git
$ cd frontend

  2. Get AWS Credentials using Janus for Frontend and CMS fronts (you will need access to Janus)

  3. Make sure you have the latest version of Java

  4. Run ./setup.sh to install dependencies and compile assets. EACCES error?

  5. All being well, you should be able to run the app

Manual

Configuration

You need one file on your machine:

~/.aws/config

[profile frontend]
region = eu-west-1

Homebrew

This is needed on Mac only:

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

JDK

Ubuntu: Java 8 is required, but only OpenJDK 7 is available in the official Ubuntu repo. Install Java 8 as below.

$ sudo apt-get purge openjdk*
$ sudo add-apt-repository -y ppa:webupd8team/java
$ sudo apt-get update
$ echo oracle-java8-installer shared/accepted-oracle-license-v1-1 select true | sudo /usr/bin/debconf-set-selections
$ sudo apt-get -y install oracle-java8-installer

Mac: Install from Oracle web site

Node.js

The frontend uses an .nvmrc which specifies Node 6.x as a requirement. If you use NVM to manage multiple versions of Node on your machine, you can just nvm use (or nvm install if you don't have 6 installed yet).

To install nvm:

$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.32.1/install.sh | bash

You may find it useful to add this script to your .bash_profile – or wherever else is appropriate for your setup – to automatically switch Node versions if an .nvmrc is present.

If you just want to use your system Node, you'll need to install v6:

Ubuntu:

$ curl -sL https://deb.nodesource.com/setup_6.x | sudo bash -
$ sudo apt-get install -y nodejs

Mac:

$ brew install node@6

Xcode (if on a Mac, one of the Node modules requires it)

This is needed on Mac only: https://itunes.apple.com/gb/app/xcode/id497799835

Xcode installs an old version of git 1.9.3. If you need a newer version, you can run

$ brew install git
$ echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile

Quit Terminal, relaunch it and check that git --version outputs 2.1.3 or newer.

Client side code

Install additional dependencies:

$ make install

The frontend application should now be ready to run.

Running the app

Compile the client side assets:

$ make watch

As a convenience, this command will also watch for changes to client side code and automatically inject changes into the browser without requiring a browser refresh.

In another console, run the supplied bash script [sbt]. The dot and slash are important in this command.

$ ./sbt

Wait for SBT to be up and running. This may take 15 mins or so to start the first time - you'll know it's done when you get a prompt. If it is your first time, compile the project.

compile

Switch project by typing

project dev-build

Then run the project locally by typing

run

This also can take a while the first time.

Now check that you are up and running by hitting the following URLs:

Please note, make watch proxies port 3000 with the ability to live reload assets, you could access all links using port 9000 as well.

If you have setup local Nginx then try hitting https://m.thegulocal.com

Congratulations, you have a local instance running! Now continue on to set up your IDE.

IDE setup

EditorConfig plugin

Install to your IDE from http://editorconfig.org/#download

IntelliJ metadata

To create project files for use in IntelliJ, you need to make sure you install the Scala plugin from Preferences->Plugins. It supports SBT and Play. Then load IntelliJ, then click Import project and import the directory as an SBT project. Default settings are fine, except you need to make sure you choose JDK 1.8 (under JVM - Custom) otherwise it won't import correctly - You can find the location by pasting /usr/libexec/java_home into your terminal.

Congratulations, you are now set up to edit frontend code! See the Optional steps below for other things to do.

Optional steps

Nginx

If you are working on Identity or Discussion, Nginx must be installed and configured to correctly serve the application, please refer to /nginx/README.md in this project. This will allow you to access frontend via https://m.thegulocal.com