Grid

Grid is the Guardian’s new image management system, which provides a universal and fast experience accessing media that is organised and using it in an affordable way to produce high-quality content.

See the Vision document for more details on the core principles behind this project.

Grid runs as a set of independent micro-services (Scala and Play Framework) exposed as hypermedia APIs (argo) and accessed using a rich Web user interface (AngularJS).

Grid relies on Elasticsearch for blazing-fast searching, and AWS services as additional storage and communication mechanisms.

Running the applications

Requirements

You will need to install:

sbt
JDK 8
Nginx
GraphicsMagick sudo apt-get install graphicsmagick or brew install graphicsmagick --with-little-cms2.
awscli
jq
exiftool

If you're using OSX, you'll also need md5 brew install md5.

Nginx

To run correctly in standalone mode we run behind nginx, this can be installed as follows:

Install nginx:

Linux: sudo apt-get install nginx
Mac OSX: brew install nginx

Make sure you have a sites-enabled folder under your nginx home. This should be

Linux: /etc/nginx/sites-enabled
Mac OSX: /usr/local/etc/nginx/

Make sure your nginx.conf (found in your nginx home) contains the following line in the http{} block: include sites-enabled/*;

you may also want to disable the default server on 8080

Get the dev-nginx repo checked out on your machine
Set up certs if you've not already done so
Configure the app routes in nginx

sudo <path_of_dev-nginx>/setup-app.rb <path_of_media_service_repo>/nginx-mapping.yml

Elasticsearch

You can run setup.sh to install and start Elasticsearch. You can use the script to start up Elasticsearch even if it's already installed.

Alternatively you can do these steps manually:

Run the Elasticsearch installer from the elasticsearch directory:

    $ cd elasticsearch/
    $ ./dev-install.sh

Start Elasticsearch from the elasticsearch directory:

    $ cd elasticsearch/
    $ ./dev-start.sh

Create CloudFormation Stack

First you need to create some dev credentials in AWS - ask your friendly system administrator.

Setup your awscli with a new profile aws configure --profile media-service.

Pro-tip: Set AWS_DEFAULT_PROFILE to avoid using the --profile flag with the awscli in the future.

echo 'export AWS_DEFAULT_PROFILE=media-service' >> $HOME/.profile

To create your stack run create-dev-stack.sh:

cd cloud-formation/scripts
./create-dev-stack.sh

Generate .properties files

Generate your .properties files for the various media-service services using the dot-properties generator

This will also create a panda.properties file that configures the pan-domain authentication

This file will be used by the different applications to share auth config, so that CORS is enabled across APIs.

Make sure you put the generated .properties files in /etc/gu/ instead of ~/.gu/ as many apps do.

Run the services

There are a few different ways to run the services, please see here.

Troubleshooting

Nginx returns "413 Request Entity Too Large"

Make sure you bump the maximum allowed body size in your nginx config (defaults to 1MB):

client_max_body_size 20m;

Crops fail with a 500 HTTP error and an SSL error in the cropper logs

Make sure you install any certificate authority file needed in the Java runtime for the cropper service to talk to the media-api.

You can do so with the keytool command:

$ sudo keytool -import \
               -trustcacerts \
               -alias internalrootca \
               -file rootcafile.cer \
               -keystore /path/to/global/jre/lib/security/cacerts

where internalrootca is the name you want to give the certificate in your keystore, rootcafile.cer is the certificate file you want to install (look for "dev-nginx/ssl/GNM-root-cert.pem"), and /path/to/global/jre/lib/security/cacerts the location of the cacerts file for the JRE you're using.

On Mac OS X, it may be something like /Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home/jre/lib/security/cacerts; on GNU Linux, it may be something like /usr/lib/jvm/java-1.8.0-openjdk-amd64/jre/lib/security/cacerts.

NGINX, Play & SNI

As the Play Framework does not yet support SNI NGINX can't always work out which certificate to send where there are multiple services on the same IP. This might result in NGINX sending the incorrect certificate. This will result in a HostnameVerifier Exception appearing in application logs.

Resolution

When the correct cert to send is ambiguous NGINX simply sends the first cert it sees in it's configuration (which is loaded from config files in alphabetical order) to resolve this problem, prefix your grid config filename with 0-!

neeharv / grid