Skip to content

01-installation-steps.md

Latest commit

 

History

History
214 lines (136 loc) · 6.68 KB

01-installation-steps.md

File metadata and controls

214 lines (136 loc) · 6.68 KB

Quick start guide

Basic Tools

You need to have a few command line tools installed on your computer (some are used to install other tools). You should already have them if your laptop has been properly set up as part of your onboarding, otherwise here are what you need:

Obtain AWS credentials

  1. Make a change to Janus and push to a new branch (you can review the closed PRs for help).
  2. Submit a PR
  3. To install local Janus credentials make sure you have awscli installed. For this run brew install awscli at your terminal.

Local development 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).

We present you with two setup types: automatic and manual. They are equivalent, the manual set up can be used if for some reasons you still have a problem after doing the automatic set up.

Automatic Setup

  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, CMS fronts and Content API (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. (If you get a EACCES error see here).

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

Manual Setup

Configuration

You need one file on your machine:

~/.aws/config

[profile frontend]
region = eu-west-1

JDK

Java 11 is required - on Mac OS this can be installed using sdkman:

$ sdk list java | grep -m 1 "11.*.1-amzn"
$ sdk install java 11.0.15.9.1-amzn # Choose latest of 11.*.1-amzn
$ sdk current java
Using java version 11.0.15.9.1-amzn
$ java -version
openjdk version "11.0.15" 2022-04-19 LTS
$ sdk use java 11.0.15.9.1-amzn
Using java version 11.0.15.9.1-amzn in this shell.

Node.js

We highly recommend installing a Node version manager such as fnm (preferred), nvm or asdf.

Install the Node version manager of your choice.

Run the command for your version manager to use the Node version as specified in .nvmrc.

For fnm this will be:

$ fnm use

For nvm this will be:

$ nvm use

Once installed, check the running Node version (ignoring any 'v' prefix) matches the version in .nvmrc

$ node --version

Client side code

Install additional dependencies:

$ make install compile

The frontend application should now be ready to run.

Running frontend

Note: frontend is used to generate JSON that is passed to dotcom-rendering for generating web content. We will show you how to run frontend, and how to run dotcom-rendering alongside it. This will help you to build a mental model of the relationship between the systems.

However, if you are working purely on web pages generated by dotcom-rendering, you might find it easier to work only with dotcom-rendering.

$ 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 sbt

$ sbt

Wait for sbt to be up and running (this may take few minutes if it's the first time). Then clean and compile at the sbt prompt

[root] $ clean

Then, when it's finished

[root] $ compile

article

The [article] app which serves most of news articles.

Switch to the [article] project:

[root] $ project article

You can't access an article directly from frontend because frontend relies on dotcom-rendering to generate HTML documents.

Follow the instructions to setup and run dotcom-rendering locally.

With the DCR server running, frontend should now be able to serve articles. Run the [article] app:

[article] $ run

In your web browser, access an article:

http://localhost:9000/uk-news/2020/feb/14/77-survivor-thelma-stober-to-lead-grenfell-memorial-commission

If everything went fine, frontend received the request, queried CAPI to retrieve article data, and then queried DCR to get the HTML document.

dev-build

[dev-build] is a more complete version of frontend which emulates the entire website.

project dev-build
[dev-build] $ run

This allows you to access more content, including fronts.

IDE setup

EditorConfig plugin

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

Editor setup

We recommend using Intellij or VS Code.

For Intellij:

  • install the Scala plugin
  • import the 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.

For VS Code:

  • add the Metals extension. Then simply open the project and follow the instructions in your editor.

Code formatting is provided by scalafmt. See their installation docs for integration with your preferred editor. You should configure this to format on save as unformatted code will fail a build in our CI.

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 and test signed in behaviour.