Skip to content

Latest commit

 

History

History
233 lines (152 loc) · 8.23 KB

01-installation-steps.md

File metadata and controls

233 lines (152 loc) · 8.23 KB
Raw

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. To install local Janus credentials make sure you have awscli installed. For this run brew install awscli at your terminal.

Local dev server setup

Hello there! 👋 After completing this setup guide, we would greatly appreciate it if you could complete our Frontend Setup Questionnaire. It should only take 3 minutes and will help us improve this documentation and the setup process in the future. Thank you! 🙏

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. Make sure you have git installed. Run brew install git if required.

  2. Check out the repository:

    $ git clone git@github.com:guardian/frontend.git
$ cd frontend

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

  4. Make sure you have the latest version of Java

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

  6. 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 8.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 8 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 v8:

Ubuntu:

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

Mac:

$ brew install node@8

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.

Client-side development with VSCode

While IntelliJ is great for Scala, you may want another option if you are writing a lot of JS and CSS, so quite a few people choose to use VSCode.

You can download VSCode from https://code.visualstudio.com/

The built-in linting of VSCode may start finding TypeScript errors in JavaScript files... To resolve this open your user settings and add the following lines:

    "javascript.validate.enable": false,
    "typescript.validate.enable": false,

You can use the Command Palette (shift + cmd + P) to open user or workspace settings, just type in Preferences: Open User Settings

Recommended VSCode extensions are listed in .vscode/extensions.json and VSCode should prompt you to install these when you open the project. You can also find and install these by searching for @recommended in the extensions pane.

Optional steps

Before you go: We would greatly appreciate it if you could complete our Frontend Setup Questionnaire. It should only take 3 minutes and will help us improve this documentation and the setup process in the future. Thank you! 🙏

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