Skip to content
This repository

Source for the Guardian's responsive site, coming soon to a desktop near you...

branch: master
Octocat-spinner-32 admin Fix prod links for ab tests again April 08, 2014
Octocat-spinner-32 applications fix whitespace in article body and remove right hand share buttons fr… April 16, 2014
Octocat-spinner-32 archive unstyled -> u-unstyled April 14, 2014
Octocat-spinner-32 article fix some bad indentation April 16, 2014
Octocat-spinner-32 commercial Add missing alt attribute April 14, 2014
Octocat-spinner-32 common Hotfix overlap between comment count and title April 17, 2014
Octocat-spinner-32 data new test files April 14, 2014
Octocat-spinner-32 dev-build Add new container route April 15, 2014
Octocat-spinner-32 dev Updated to latest Play and SBT April 03, 2014
Octocat-spinner-32 diagnostics Archive controller now renders a 404 page. April 01, 2014
Octocat-spinner-32 discussion Added a MemcachedAction March 30, 2014
Octocat-spinner-32 docs Update 2014-04-07.md April 10, 2014
Octocat-spinner-32 facia-tool Change displayName to title when writing to the content api April 17, 2014
Octocat-spinner-32 facia Fix whitespace issue April 15, 2014
Octocat-spinner-32 fronts-endtoend-tests Update README.md March 03, 2014
Octocat-spinner-32 git-hooks Validate JS on .js file changes only March 13, 2014
Octocat-spinner-32 identity Add switch code to avatar template April 17, 2014
Octocat-spinner-32 image Added a MemcachedAction March 30, 2014
Octocat-spinner-32 integration-tests force test into control test April 14, 2014
Octocat-spinner-32 nginx Update Homebrew install instructions March 25, 2014
Octocat-spinner-32 onward Add series component route back April 15, 2014
Octocat-spinner-32 project Add proper 3-letter team codes to football stats April 09, 2014
Octocat-spinner-32 resources update to single quotes March 21, 2014
Octocat-spinner-32 router Added a MemcachedAction March 30, 2014
Octocat-spinner-32 sport fix whitespace in article body and remove right hand share buttons fr… April 16, 2014
Octocat-spinner-32 tools Remove grid bookmarklet, which does not work anymore March 25, 2014
Octocat-spinner-32 .editorconfig Add .editorconfig July 01, 2013
Octocat-spinner-32 .gitignore removing compiled scss files and adding to .gitignore March 13, 2014
Octocat-spinner-32 CONTRIBUTING.md Added email verification to ID API January 13, 2014
Octocat-spinner-32 Gemfile Update Sass to 3.3.3 March 17, 2014
Octocat-spinner-32 Gemfile.lock updated Gemfile.lock March 18, 2014
Octocat-spinner-32 Gruntfile.js googletag path April 11, 2014
Octocat-spinner-32 IMAGES.md We do not know if there is a video at the top of the body. December 16, 2013
Octocat-spinner-32 LICENSE Happy new year January 08, 2014
Octocat-spinner-32 README.md Update README setup instructions April 03, 2014
Octocat-spinner-32 Vagrantfile Sync the .ivy2 directory November 19, 2013
Octocat-spinner-32 cla-corporate.txt Add Contributor License Agreements to the project April 19, 2013
Octocat-spinner-32 cla-individual.txt Add Contributor License Agreements to the project April 19, 2013
Octocat-spinner-32 dist-tc modifying teamcity grunt build command and reverting validate:css cha… March 13, 2014
Octocat-spinner-32 grunt-tc Remove accidental line addition January 02, 2014
Octocat-spinner-32 integration-tc Removed jasmine from TC scripts November 21, 2013
Octocat-spinner-32 package.json reverting imagemin version April 01, 2014
Octocat-spinner-32 provision.sh Got rid of 3rd party image service for now, tests are over. February 03, 2014
Octocat-spinner-32 sbt Give the local sbt environment a bit more New space April 14, 2014
Octocat-spinner-32 sbt-tc Updated to latest Play and SBT April 03, 2014
Octocat-spinner-32 test-tc remove integration testing February 18, 2014
README.md

Frontend

The Guardian website frontend.

Core Development Principles (lines in the sand)

This applies to all requests on www.theguardian.com and api.nextgen.guardianapps.co.uk (our Ajax URL)

On the server

  • Every request can be cached and has an appropriate Cache-Control header set.
  • Each request may only perform 1 I/O operation on the backend. (you cannot make 2 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 2 seconds will be terminated.

New developers quick-start

Frontend is a set of Play Framework 2 Scala applications.

Configuration

You need 2 files on your machine.

The first file is called /etc/gu/install_vars and has the following contents...

STAGE=DEV

The second file is called [YOUR_HOME_DIR]/.gu/frontend.properties and you can get its contents from a shared document. Ask your team mates to share it with you. If it has already been shared with you just search for "frontend.properties" in your documents.

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.

Vagrant

You can run the project with the supplied Vagrantfile - make sure you understand what vagrant is http://www.vagrantup.com/

  • You need Virtualbox and Vagrant - on Ubuntu sudo apt-get install virtualbox vagrant otherwise see http://docs.vagrantup.com/v2/installation/index.html
  • 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

Local Install Requirements

  • A Mac or Linux pc
  • Installed Open JDK sudo apt-get install openjdk-7-jdk
  • Installed Node.js (https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)
  • Installed npm (Node package manager - you quite possibly already have this)
  • Installed Grunt (build tool) sudo npm -g install grunt-cli
  • Installed Ruby >= v1.9.x (on Ubuntu: sudo apt-get install ruby ruby-dev) & bundler (You may already have this installed, but run ruby -v to check version number)
  • Installed Memcached sudo apt-get install memcached - this is optional (most of the time you do not want to use it as caching makes local development harder)

NPM ownership

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

File handles

On Linux machines 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

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 pam_limits.so

Restart the machine.

For more info see http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files/

Running

Assuming you have checked out this project, open a console and change directory into the root of the project.

Frontend is built in two parts, using Grunt for the client side asset build and SBT for the Play Framework backend. Neither of these tools are much use for building the other half of the project and coupling them together with an integration is one of those bad ideas that is even worse than it sounds.

Run

npm install

to download Node dependencies

Run

bundle

to install additional dependencies

Run

grunt compile

to compile assets

You must start SBT with the supplied script called sbt if you start SBT any other way the project will not run.

Start the Grunt build and watch for development changes:

grunt watch

In another console, start Simple Build Tool (sbt) by running ./sbt. It may take a while to start the first time. Once SBT is running, switch project by typing project dev-build. Then compile and run the project locally by typing run. This also can take a while first time.

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

  • http://localhost:9000/books
  • http://localhost:9000/media/2012/dec/05/newspaper-editors-sign-up-leveson
  • http://localhost:9000/news/gallery/2012/dec/04/24-hours-in-pictures-gallery

Play Framework will recompile code changes on refresh.

To create project files for use in IntelliJ, run the gen-idea task from the root SBT project. see https://github.com/mpeltonen/sbt-idea

Further information on using the Play console is available here.

Endpoints

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.

Deploying

Deployment uses the Magenta library.

Debugging

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

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

Something went wrong with that request. Please try again.