CDPT-2295 Update documentation

[EarthlingDavey]

Hey @EmilyHazlehurst would it be possible for your review to include getting this up and running locally? ... To ensure that I've not missed any steps from the docs.

[EmilyHazlehurst]

@EarthlingDavey I've added a couple of observations I made whilst setting this up locally.

I've been able to get it to the point of logging the snapshots and successfully authenticating between the local intranet and archiver instances, but I can't see the snapshots as I get a 404 when redirected to the /env-agency/index.html page. I think it has something to do with the proxy as it doesn't seem to get hit, but I've not had chance to investigate it any more than that.

It works well on dev though, so might be something to do with my local setup.

[EmilyHazlehurst]

Following the installation instructions with a fresh install I get:

  "fetchStatuses": [
    {
      "env": "local",
      "status": 404
    }
  ],
  "s3Status": true
}

If I teardown the environment and add the JWTs to the .env file that was automatically created then re-run make run it works as described (sort of, I get a 200 response from Prod, and 302 on the others).

Might it be worth removing the automatic creation of the .env file, and instead having a line here before running make run telling the user to duplicate the .env and which values to update?

Otherwise, this isn't explained until line 208.

[EmilyHazlehurst]

After more testing, I get an error Cannot read properties of undefined (reading 'trim') after clicking the button on the Intranet dashboard.

This is because the Cloudfront public/private keys aren't set, but I can't see that they're required until line 311 of this README and they aren't in the env.example file.

The Cloudfront object also appears to be required, but is only mentioned in the make command table at the very bottom.
The instructions that appear in the terminal say it's optional, but cloudfront.js requires it in the getKeyPairId() function.

It might be better to rewrite this section as more of a quickstart guide to getting the local site working, with links to the more detailed bits e.g.

1. Add the following keys to the .env file
   a) AWS_CLOUDFRONT_PUBLIC_KEY (see <#LINK> for more info)
   ....

[EmilyHazlehurst]

There's some odd behaviour when I follow these instructions using the Dory proxy.

If I'm running the Intranet at the same time, the Archiver uses the Intranet's Minio instance instead of it's own and if I go to the web interface it redirects to the Intranet's Minio instance. If I stop it running, then it uses it's own instance.

[EmilyHazlehurst]

With further testing, localhost:2000 can never fully work here.

controllers/cloudfront.js has the getCdnUrl() function which starts with:

  // Check appHost starts with `app.`
  if (!appUrl.host.startsWith("app.")) {
    throw new Error("Invalid host");
  }

[EmilyHazlehurst]

I couldn't see a link in the Intranet until I added INTRANET_ARCHIVE_URL to the .env on the Intranet.

I'd mention that here as I don't think it is mentioned anywhere else and could catch people out.

It also only appears for agencies with the has_archive property in agency.php, so I'd mention that here too as it's not immediately clear why it's not appearing if you're using HQ (the default).

[EmilyHazlehurst]

On line 146 if using the localhost:2000 option, this should be cdnUrl.hostname, otherwise it includes the port number and doesn't work. (TypeError: option domain is invalid)

[EarthlingDavey]

Thanks @EmilyHazlehurst for such detailed feedback 🙌

It's exactly what I need as I probably got quite blind to the requirements and running order.

I'll address and ask for a re-review later :)