QUICKSTART.md started

2022-03-09 22:44:57 +00:00 · 2022-03-09 22:44:57 +00:00 · 4cfaa1b87c
commit 4cfaa1b87c
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@ -0,0 +1,99 @@
+# Quickstart guide
+
+This is a quickstart guide for deploying LibResilient on a website. This guide makes a few assumptions:
+1. the website in question is a static site;
+2. the administrators of the website have shell access on the hosting server, and ability to install software there;
+3. LibResilient is going to be deployed for the whole site.
+
+These assumptions are made to simplify this quickstart guide and are *not necessary* for LibResilient to be able 
+
+## The website
+
+We are going to assume a simple website, consisting of:
+
+ - `index.html`
+ - `favicon.ico`
+ - an `/assets/` directory, containing:
+   - `style.css`
+   - `logo.png`
+   - `font.woff`
+ - a `/blog/` directory, containing two blog posts:
+   - `01-first.html`
+   - `02-second.html`
+
+In fact, this hypothetical website is very similar to (and only a bit simpler than) [Resilient.Is](https://resilient.is/), the homepage of this project.
+
+## First steps
+
+We shall start with a completely minimal (but not really useful) deployment of LibResilient, and then gradually add functionality.
+
+To start, we need:
+
+ - [`libresilient.js`](https://gitlab.com/rysiekpl/libresilient/-/blob/master/libresilient.js)\
+   This script is responsible for loading the service worker script. It can be included using a `<script>` tag or copy-pasted into the HTML. We'll go with the `<script>` tag.\
+   the `libresilient.js` script should be located in the same directory as the `service-worker.js` script.
+   
+ - [`service-worker.js`](https://gitlab.com/rysiekpl/libresilient/-/blob/master/service-worker.js)\
+   This is the heart of LibResilient. Once loaded, it will use the supplied configuration (in `config.json`) to load and configure plugins. Plugins in turn will perform actual requests and other tasks.
+   
+ - the [`fetch` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/fetch.js)\
+   This LibResilient plugin uses the basic [HTTP Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to retrieve content.\
+   LibResilient expects plugins in the `plugins/` subdirectory of the directory where the `service-worker.js` script is located, so this file should be saved as `/plugins/fetch.js` for our hypothetical website.
+   
+ - `config.json`\
+   That's the config file, and should also reside in the same directory as `service-worker.js`.\
+   We will write it from scratch, although an example is available [here](https://gitlab.com/rysiekpl/libresilient/-/blob/master/config.json.example).
+   
+Our `config.json` has to be a [valid JSON file](https://jsonlint.com/); for now it should only contain this:
+
+```json
+{
+    "plugins": [{
+        "name": "fetch"
+    }],
+    "loggedComponents": ["service-worker", "fetch"]
+}
+
+```
+
+Let's unpack this:
+
+ - The `plugins` key contains an array of objects.\
+   Each object defines configuration for a plugin. For simplest plugins, the minimal configuration is just the name of the plugin. Based on the name `service-worker.js` establishes which file to load for a given plugin — in this case, it will be `./plugins/fetch.js` (relative to where `service-worker.js` is).
+   
+ - The `loggedComponents` key is a narray of strings.\
+   It lists the components whose logs should be visible in the deveoper console in the browser. The `service-worker.js` script logs messages as the "service-worker" component, the `fetch` plugin as (you guessed it!) "fetch".\
+   We want the log messages visible for both of them, just so that we know what's going on. In a production environment we would perhaps want to limit the log messages to only some components.
+
+With all this, our website structure now looks like this:
+
+ - `index.html`
+ - `favicon.ico`
+ - `/assets/`
+   - `style.css`
+   - `logo.png`
+   - `font.woff`
+ - `/blog/`
+   - `01-first.html`
+   - `02-second.html`
+ - **`config.json`**
+ - **`libresilient.js`**
+ - **`service-worker.js`**
+ - **`/plugins/`**
+   - **`fetch.js`**
+
+We also need to add this to the `<head>` section of our `index.html`, and HTML files in the `/blog/` directory:
+
+```html
+<script defer src="/libresilient.js"></script>
+```
+
+Once we deploy these changes, our HTML files will load `libresilient.js` for each visitor, which in turn will register `service-worker.js`. That code in turn will load `config.json`, and based on it, will load the `/plugins/fetch.js`.
+
+Each user of our website, after visiting any of the HTML pages, will now have their browser load and register the Libresilient service worker, as configured. From that point on all initiated in the context of our website will always be handled by LibResilient, and in this particular configuration — the `fetch` plugin.
+
+This doesn't yet provide any interesting functionality, though. So how about we do that next.
+
+## Adding cache
+
+Bare minimum would be to add offline cache to our website. This would at least allow our visitors to continue to browse content they've already loaded once even if theya re offline or if our site is down for whatever reason.