setup-behind-a-proxy.md

Setting up behind a proxy

If your app is served up behind a reverse-proxy, such as Nginx, then there's a couple of things to be aware of.

URL rewriting

If your proxy manipulates the URL before reaching your app, then there's some config required ...

Given this request pathway:

Browser (/app/) -> Reverse Proxy (rewrites to /host/app/) -> Your app

In this case your app will need to ...

• Specify a mountUrl of /app/
• Mount your CASA app onto the /host/app path

And here's the minimal setup to do that:

import ExpressJS from "express";
import { configure } from "@dwp/govuk-casa";

// Set the specific prefix you want to appear in the browser address bar
const { mount } = configure({
  mountUrl: "/app/",
});

// Mount onto the full proxy path + mountUrl combo
const app = ExpressJS();
app.use("/host/app", mount(ExpressJS()));

app.listen();

Setting secure cookies

If you are using the secure option for sessions, then your app will by default only set cookies when serving requests over a TLS connection. However, it's common to have the proxy perform TLS termination and make any upstream calls over plan HTTP, eg

Browser --(https)--> Nginx proxy --(http)--> Your app

In this case, you will need to tell Express to trust that the proxy is serving TLS requests:

import ExpressJS from "express";
import { configure } from "@dwp/govuk-casa";

const { mount } = configure({
  session: {
    secure: true,
  },
});

const casaApp = ExpressJS();
casaApp.set("trust proxy", 1);
mount(casaApp);

const app = ExpressJS();
app.use("/", casaApp);

app.listen();