Install

TL;DR

To run support-frontend in DEV:

1. Clone this repo
2. Get membership Janus credentials for authentication to S3
3. Run setup.sh from support-frontend/support-frontend to install dependencies - note this requires nvm
4. Run fetch-config.sh from support-frontend/support-frontend to fetch config
5. Run devrun.sh from support-frontend/support-frontend to run the Play and webpack proxy servers
6. Open https://support.thegulocal.com in your browser to view the site

Setup

We recommend installing nvm to easily switch between versions of node.

support-frontend has a number of dependencies, such as java8, sbt, node, nginx. These can all be installed by running setup.sh from the sub-project.

Is support-frontend the first Guardian app you are running locally?

You can try the following steps if you run into trouble.

• We have a convention of keeping config for Guardian apps in the /etc/gu directory. Make sure you have that directory and that you can write config to it.
• If support.thegulocal.com doesn't load anything you might need to add the following line inside /usr/local/etc/nginx/nginx.conf:

  http {
      include sites-enabled/*;
      ...
  }
  

• Restart nginx (sudo may be necessary): nginx -s stop and nginx
• If setup.sh stops abruptly telling you about a node version, try running nvm install to install the version of node support-frontend uses, then run setup.sh again.
• Try creating the /usr/local/etc/nginx/sites-enabled directory manually if it doesn't exist. The error for the directory not existing may say "you don't have permission" too.
• If you're on a mac, we recommend OpenJDK and the setup script currently just points you to https://adoptopenjdk.net, so try going there and installing the JDK before running setup.sh because for example, the script code to setup sbt relies on the JDK being installed.
• setup.sh is meant to install homebrew and then use it to install some dependencies. If you have run setup.sh and then entering brew -v at the command prompt just gives you brew: command not found, you might try doing the homebrew install step manually (see the homebrew link above for homebrew installation info)

Config

This project uses shared config from the support-config library, as well as pulling in private config from S3.

Download config from S3 by running fetch-config.sh from the project root.

Overrides

In /conf/DEV.public.conf, if while developing locally you are not relying on Identity API in CODE you can set identity.useStub=true to get stubbed responses.

Running

In local development, the base app server has two layers of proxy sitting on top it:

1. Play/Scala app server - the main app server, accessed at http://localhost:9210/ (this will appear as a blank page)
2. webpack-dev-server - a proxy providing compilation of client-side code and auto-refreshing, accessed at http://localhost:9211/
3. Nginx - a proxy adding HTTPS and a unified .thegulocal.com domain with other Guardian projects, accessed at https://support.thegulocal.com/uk

You need all 3 of these running to have a working development environment, which you access in your browser at https://support.thegulocal.com/uk.

This can be done by running devrun.sh from support-frontend\support-frontend to run the Play and webpack proxy servers

Alternatively you can run them separately as follows

1. sudo nginx
2. nvm use
3. yarn devrun

And in a separate window

1. sbt
2. support-frontend / devrun

Troubleshooting

NGINX error messages

nginx has some unhelpful error messages. Here are some translations:

When stopping/reloading nginx

nginx: [error] open() "/usr/local/var/run/nginx.pid" failed (2: No such file or directory)

This means nginx is not running. And nginx -s reload will not automatically start nginx if it's not running.

When starting nginx

nginx: [emerg] bind() to 0.0.0.0:8080 failed (48: Address already in use)

This means nginx is already running.

nginx: [emerg] host not found in upstream "support.thegulocal.com" in [some/path]/support.conf:16

This means nginx doesn't know what to do with the websocket proxy setting in the support site conf file. You can resolve this by running dev-nginx add-to-hosts-file support.thegulocal.com.

Node/NPM/Yarn errors

When installing

Node Sass could not find a binding for your current environment: [OS version] with Node [Node version]

This can usually be solved by running npm rebuild node-sass (although we generally use yarn, there is no yarn equivalent for rebuilding C/C++ bindings for Node). If necessary nuking your node_modules folder with rm -rf node_modules and re-running yarn install can help.

When running the dev server

Sometimes the Webpack process can run out of memory and crash when rebuilding, usually after a major change like switching to a different branch. If you're experiencing this issue, try setting a higher limit for Node's memory heap size by adding the following to your shell config file (.zshrc/.bash_profile/etc):

export NODE_OPTIONS=--max_old_space_size=8192