From 2dd82345bd25aad7c17f43e52ae53fb97226dd4a Mon Sep 17 00:00:00 2001 From: Ilya Kreymer Date: Fri, 11 Aug 2023 18:23:10 -0700 Subject: [PATCH] docs: add separate page for cors-settings to mention cors settings for both regular replayweb.page usage and embedding, link from embedding guide (#205) addresses #74, #168, #202 --- docs/contact.md | 4 +- docs/cors-settings.md | 124 ++++++++++++++++++++++++++++++++++++++++ docs/embedding.md | 35 +----------- docs/reference.md | 2 +- docs/troubleshooting.md | 2 +- 5 files changed, 131 insertions(+), 36 deletions(-) create mode 100644 docs/cors-settings.md diff --git a/docs/contact.md b/docs/contact.md index 65e785e..4aa10aa 100644 --- a/docs/contact.md +++ b/docs/contact.md @@ -1,7 +1,7 @@ --- layout: page title: Contact -nav_order: 6 +nav_order: 7 description: Contact Webrecorder permalink: /docs/contact @@ -31,4 +31,4 @@ We prefer to discuss issues or bugs on the forum or on github so that others run For other questions,, you can also reach us by e-mail. -Send us a message at and someone from the Webrecorder team will get back to you. \ No newline at end of file +Send us a message at and someone from the Webrecorder team will get back to you. diff --git a/docs/cors-settings.md b/docs/cors-settings.md new file mode 100644 index 0000000..2f2409c --- /dev/null +++ b/docs/cors-settings.md @@ -0,0 +1,124 @@ +--- +layout: default +title: Configuring Server CORS +nav_order: 4 +permalink: /docs/cors-settings +--- + +ReplayWeb.page doesn't require any specific server side settings, just the ability to server file and respond to `Range` requests, +loading parts of files. It can load files from any web server. However, a common obstacle is configuring CORS settings to give +ReplayWeb.page access to the data. + +# Configuring CORS + +Browsers restrict access to files hosted on a different domain than the websites that is trying to load them for security reasons. + +If you are loading web archives hosted on a different domain (for example, S3 or other cloud storage) and your site is hosted on a different domain, +the site hosting the file needs to 'allow' the website to load the file using special CORS (Cross-Origin Resource Sharing) headers. + +These settings apply whenever the archive is hosted on a different domain than the viewer, so if you are loading via our main ReplayWeb.page site, you need to grant access to *https://replayweb.page* to load these archives. + +The minimum requirement is to return an `Access-Control-Allow-Origin: https://replayweb.page` and most CORS settings include at least this option. + +## Differences between Chrome and Firefox and Safari + +Unfortunately, different browsers have diverged in how they handle in enforcing the CORS policy. + +At the moment, it seems Firefox and Safari sometimes send a [pre-flight OPTIONS request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) when handling ReplayWeb.page requests, because the ReplayWeb.page uses the `Range` header. + +Chrome currently considers it a 'safe' header, but the other browsers have not yet made this change. + +To be compatible with all browsers, we recommend including all headers as 'allowed headers' for use with ReplayWeb.page, eg. +by setting `Access-Control-Allow-Headers: '*'` as part of the CORS response in addition to `Access-Control-Allow-Origin`. + +The following provides different ways of configuring CORS for different hosting environments. + + +## S3 and Compatible Configurations + +If you are hosting from S3 or S3-compatible service, here are a few CORS bucket configurations that should work. + +Amazon S3 and other services now support a JSON based bucket policy, as well as an older XML-based policy. + +The below examples provide access to `https://replayweb.page` to load your archive. +If you are instead [embedding replayweb.page](./embedding), replace that with the server (origin) of the URL where the `` embed is hosted. + +Both JSON and XML options provide a way to specify multiple origins via the JSON list or multiple `` tags + +### JSON-Based Configuration + +The JSON-based configuration will look as follows: + +```json +[ + { + "AllowedOrigins": [ + "https://replayweb.page" + ], + "AllowedMethods": [ + "GET", + "HEAD" + ], + "AllowedHeaders": [ + "*" + ] + } +] +``` + +### XML-Based Configuration + + +```xml + + + GET + HEAD + https://replayweb.page + * + Content-Range + Content-Encoding + Content-Length + + +``` + +One way to set this policy is to use the popular [s3cmd](https://s3tools.org/usage) command-line tool: + +1) Paste the above snippet into a file, eg. `cors.xml` +2) Be sure to set the 'Allowed Origin' to the site hosting the embed. You can add as many of these as necessary. +3) Run `s3cmd setcors ./cors.xml s3://` + +See the s3cmd docs for how to configure it s3cmd to work with your setup. + +See [S3 Docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) for more info on how to set this policy. + +Other cloud providers may have a similar settings for configuring CORS. + +## Manual Setup / Nginx + +The recommended setup for nginx is to include the following CORS settings. +As above, you can replay `https://replayweb.page` with your domain: + +```nginx +location / { + if ($request_method = 'OPTIONS') { + add_header 'Access-Control-Allow-Origin' 'https://replayweb.page'; + add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS' always; + add_header 'Access-Control-Allow-Headers' '*' + return 204; + } + + if ($request_method = 'GET') { + add_header 'Access-Control-Allow-Origin' 'https://replayweb.page' always; + add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always; + add_header 'Access-Control-Allow-Headers' '*' always; + add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; + } +} +``` + +For more examples of CORS configurations for different servers, see: [https://enable-cors.org/](https://enable-cors.org/) + + diff --git a/docs/embedding.md b/docs/embedding.md index 7c6ee03..ea59dfa 100644 --- a/docs/embedding.md +++ b/docs/embedding.md @@ -176,40 +176,11 @@ html, body { ``` -### CORS restrictions +### Loading Errors -Browsers restrict access to files hosted on a different domain than the websites that is trying to load them. -If you are loading web archives hosted on a different domain (for example, S3 or other cloud storage) and your site is hosted on a different domain, -the site hosting the file needs to 'allow' the website to load the file using special CORS (Cross-Origin Resource Sharing) headers. +If you see errors such as `TypeError: failed to load` or similar errors, the issue may have to do with Cross-Origin Resource Sharing (CORS) errors. -If you are hosting from S3 or S3-compatible service, here is a potential CORS bucket configuration that should work. +See [CORS Settings](./cors-settings) for more info on how to configure CORS for ReplayWeb.page -Replace `https://myarchive.example.com` with the server (origin) of the URL where the `` embed is hosted. -```xml - - - GET - HEAD - https://myarchive.example.com - * - Content-Range - Content-Encoding - Content-Length - - -``` - -One way to set this policy is to use the popular [s3cmd](https://s3tools.org/usage) command-line tool: - -1) Paste the above snippet into a file, eg. `cors.xml` -2) Be sure to set the 'Allowed Origin' to the site hosting the embed. You can add as many of these as necessary. -3) Run `s3cmd setcors ./cors.xml s3://` - -See the s3cmd docs for how to configure it s3cmd to work with your setup. - -See [S3 Docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) for more info on how to set this policy. - -Other cloud providers may have a similar settings for configuring CORS. diff --git a/docs/reference.md b/docs/reference.md index 5435b53..4782415 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,7 +1,7 @@ --- layout: default title: Reference -nav_order: 4 +nav_order: 6 has_children: true permalink: /docs/reference --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ad05762..ddef3ed 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,7 +1,7 @@ --- layout: page title: Troubleshooting -nav_order: 4 +nav_order: 5 description: Troubleshooting ReplayWeb.page permalink: /docs/troubleshooting