Install - guardian/support-frontend GitHub Wiki

TL;DR

To run support-frontend locally:

  1. Clone this repo
  2. Get membership Janus credentials for authentication to S3
  3. Install prerequisites: Java, Node and homebrew (see below for recommendations on how to do this)
  4. Run setup.sh from support-frontend/support-frontend
  5. Run fetch-config.sh from support-frontend/support-frontend to fetch config
  6. Run devrun.sh from support-frontend/support-frontend to run the Play and webpack proxy servers
  7. Open https://support.thegulocal.com in your browser to view the site

Setup

The required Node version is specified in the .nvmrc file in the root of the project. We recommend fnm for managing Node versions. With fnm your shell can be configured to automatically switch Node versions when in a directory with a .nvmrc file.

The required Java version is specified in the .tool-versions file in the root of the project. We recommend Mise for managing Java versions. With Mise your shell can be configured to automatically switch Java versions when in a directory with a .tool-versions file.

Remaining steps are handled by running setup.sh from the support-frontend 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 expects homebrew to be available and uses 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 within the support-frontend sub-directory 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.

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