Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Source for
HTML JavaScript Scala CSS Shell Java
Failed to load latest commit information.
admin Merge branch 'master' into jp-newspaper-pages-2
applications Merge branch 'oja-rm-offline-page-switch'
archive Renable test to work in test suite
article Rename the tag check function and remove unused test data files
commercial AB test completely removed
common Merge pull request #11185 from guardian/observer-logo
data Rename the tag check function and remove unused test data files
dev-build Merge pull request #11179 from guardian/RTRT_Email-Sign-up
dev Add test for ESLint rule
diagnostics All retina iPads see universal fronts all the time.
discussion Remove arrows from CSS and inline discussion arrow
docs fixing merge conflicts with master
facia-end-to-end Bye bye facia tool
facia-press merge master into switches branch
facia Add link to image
git-hooks move dev make stuff out of dev, add to top level make/package.json, a…
grunt-configs Do not uglify JS in dev, just copy
identity Link to existing T&C's for Teachers Network
image Relocate deployment files from conf
integrated-tests fronts.gutools is updated so reinstating the test
nginx Fix broken relative link
onward making `across the guardian` the default
preview Relocate deployment files from conf
project Merge branch 'master' into kc-creative-targeting
router Relocate deployment files from conf
rss Relocate deployment files from conf
sanity-tests/test Changed trait to sealed trait
sport Remove unused tests and fix up other tests
standalone Ensure routes work for /theobserver and /theguardian and pages have c…
static Revert "Prevent space-finder collisions due to race conditions"
tools move dev make stuff out of dev, add to top level make/package.json, a…
training-preview Relocate deployment files from conf
.editorconfig just trying this out
.eslintrc Upgrade ESLint to v1
.gitignore Remove jspm and SystemJS
.jscsrc Remove jspm and SystemJS
.scss-lint.yml Lint Sass Added email verification to ID API
Gemfile Merge branch 'master' of into styleguide
Gemfile.lock Outbrain isFront check
Gruntfile.js Add test for ESLint rule We do not know if there is a video at the top of the body.
LICENSE L'an de grâce deux mil quinze Fix broken link in
Vagrantfile Sync the .ivy2 directory
browserslist restore US to browserslist
cla-corporate.txt Add Contributor License Agreements to the project
cla-individual.txt Add Contributor License Agreements to the project
dist-assets-tc call it make compile, to minimise the dissonance
dist-npm-tc Remove jspm and SystemJS
dist-play-tc Replace old publish artifacts script with riffRaffArtifact
dist-publish-assets-tc Ensure the build.json can be parsed by riff raff
grunt-tc Relocate bower registry creation to npm setup stage
hologram_config.yml adding initial button styles and hologram setup use make
makefile don't expect gulp to be global
npm-shrinkwrap.json Add test for ESLint rule
package.json Add test for ESLint rule Got rid of 3rd party image service for now, tests are over.
sbt Remove ivy-sbt folder
sbt-tc Remove build params from sbt-tc missed these too

We're hiring!

Ever thought about joining us?


The Guardian website frontend.

Frontend is a set of Play Framework 2 Scala applications.

Frontend is built in two parts, using Grunt for the client side asset build and SBT for the Play Framework backend.

Core Development Principles (lines in the sand)

These principles apply to all requests on and (our Ajax URL)

On the server

  • Every request can be cached and has an appropriate Cache-Control header set.
  • Each request may only perform one I/O operation on the backend. (you cannot make two calls to the content API or any other 3rd party)
  • The average response time of any endpoint is less than 500ms.
  • Requests that take longer than two seconds will be terminated.

New developers quick-start


  1. Local Test Server setup
  2. IDE Setup
  3. Troubleshooting
  4. Optional steps
  5. Useful information and hints
  6. Additional Documentation

Local Test Server setup

You need a Mac or Linux PC (Ubuntu).

Before checking out the repository you may need to add an SSH key to your GitHub account.


  1. Check out the repository:

    git clone
    cd frontend
  2. Run ./ to install dependencies and compile assets

  3. All being well, you should be able to run the app (make sure you have the latest version of java)


Install each of the things listed below:

Configuration files

You need 3 files on your machine.

  1. /etc/gu/install_vars
  • ~/.gu/ contains the content.

    Ask your team mates to share it with you if you don't get any results.

  • ~/.aws/credentials

    Ask your team mate to create an account for you and securely send you the access key. For security, you must enable MFA - ask if you're not sure what this means.



This is needed on Mac only:

ruby -e "$(curl -fsSL"


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



curl -sL | sudo bash -
sudo apt-get install -y nodejs


brew install node

Grunt (build tool)


sudo npm -g install grunt-cli

Ruby >= v1.9.x (use ruby -v to check if you have it installed)


sudo apt-get install ruby ruby-dev



sudo gem install bundler

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

This is needed on Mac only:

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.



sudo apt-get install libpng-dev


brew install libpng

The frontend code

Note: Remember to see Troubleshooting below if you have any issues.

git clone

cd frontend

Install node dependencies:

npm install

Install additional dependencies:

make install

npm and bundle are also run by

After this, you can compile the assets:

make compile

 Run the app

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


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.


Switch project by typing

project dev-build

Then run the project locally by typing


This also can take a while the first time.

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

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

IDE setup

You need a copy of the source code from above. If not, run this command:

git clone

EditorConfig plugin

Install to your IDE from

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.



If you get errors like this on npm install

npm WARN locking Error: EACCES, open '/Users/jduffell/.npm/_locks/karma-requirejs-4becac899d6c8f35.lock'

Sometimes when you install npm, it ends up owned by root (but in your home directory).

Check that you own your own .npm directory ls -ld ~/.npm

If it is owned by root, then take ownership of it sudo chown -R username:username ~/.npm

Global install permissions errors

The script installs global npm packages without sudo. If you get npm permission errors, follow the guide to using npm without sudo here.

PhantomJS permissions errors (OSX)

If you get an error about not having permissions to execute PhantomJS during make compile, your machine is probably set up as managed and you'll need to ask IT to make it unmanaged.

File handles - "Too many files open"

You may run into a "too many files open" error during compilation or reloading. You can find out how many file handles you are allowed per process by running ulimit -n. This can be quite low, e.g. 1024 on linux or 256 on Mac


To increase the limit do the following (instructions from Ubuntu 12.10)...

In the file /etc/security/limits.conf add the following two lines

*  soft  nofile 20000
*  hard  nofile 65000

And in the file /etc/pam.d/common-session add the following line.

session required

Restart the machine.

For more info see


  • Edit your ~/.bash-profile file
  • add the following line: ulimit -n 1024
  • save and close the file
  • back at the command prompt enter: source .bash_profile and hit return.

Now you should be able to compile and run. Yay.

"No route to host" or "Unsupported major.minor version 52.0"

If you get no route to host, it means you are not using the 1.8 jre. Type java -version to check. You may need to close and reopen your terminal if you installed 1.8 recently.

You may also see java.lang.UnsupportedClassVersionError: play/runsupport/classloader/ApplicationClassLoaderProvider : Unsupported major.minor version 52.0 which is described in the Play 2.4 migration guide.

Follow the JDK install guide above.

Optional steps


Some packages (imagemin) are not working with newest Node.js. So if you want to run multiple Node.js versions on your system you may want to use nvm


Memcached sudo apt-get install memcached - (most of the time you do not want to use it as caching makes local development harder)


If you are working on Identity or Discussion, Nginx must be installed and configured to correctly serve the application, please refer to /nginx/ in this project.


You can run the project with the supplied Vagrantfile - make sure you understand what Vagrant is

  • Make sure you have Virtualbox and Vagrant installed (on Ubuntu sudo apt-get install virtualbox vagrant)
  • Change directory into the folder where this README is located
  • vagrant up - this will take a while, make some coffee
  • You can now get onto the box by vagrant ssh
  • The project is located in /vagrant so cd /vagrant
  • ./sbt

Client-side development mode

There is a make watch task available to build and watch for development changes.

make watch

Useful information and hints

Play console

Play Framework will recompile code changes on refresh.

Further information on using the Play console is available here.


The available endpoints are listed in conf/routes of each application and typically include:

  • /management: Operations support as per standard webapp guidelines. See guardian-management.
  • /<path>: Serve the Guardian URL at <path> if supported by this application.
  • /assets/<file>: A convenience for DEV machines. Assets are CDNed in PROD and would not be available on DEV.


Deployment uses the Magenta library.


You can debug your local Frontend application, by attaching a debugger.

  • Start Simple Build Tool in debug mode by typing ./sbt --debug.
  • Build and run your application. See "Running" for steps.
  • Use a debugger to attach to the remote Java process, on localhost:1044.

Any IDE debugger should be compatible. In IntelliJ, add a new Debug Configuration, based on the Remote default. Ensure the Transport is Socket, the Debugger mode is Attach, and the port is set to 1044. Start a new Debug session, and your breakpoints should be active.

Additional Documentation

If you're new, you'll want to see what libraries we use in frontend.

Further documentation notes and useful items can be found in docs.

Something went wrong with that request. Please try again.