From 98f8452165e19aff8264b88f57efd592f0a79363 Mon Sep 17 00:00:00 2001 From: Gerben Date: Sat, 29 Sep 2018 12:31:10 +0300 Subject: [PATCH] Update&reorganise readme --- Readme.md | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/Readme.md b/Readme.md index b4a801b..0fc0ed3 100644 --- a/Readme.md +++ b/Readme.md @@ -1,38 +1,53 @@ # Memento — Nextcloud web archive server If you host snapshots of web pages on your Nextcloud, this app enables any client that speaks the -Memento protocol to access these snapshots. +Memento protocol to access these snapshots. It is part of an experiment aiming to create personal +web archives. The Memento protocol ([RFC7089][]) is widely used to ask archives (such as the Internet Archive's [Wayback Machine][]) for their copies of web pages. For example, a client (e.g. a browser extension) may ask an archive whether it has a copy of `https://nextcloud.com` from around July last year, and —if successful— will be redirected to the closest match. -Currently this app only supports snapshots that are stored as plain html files. It recognises a file -as being a snapshot if the file contains a <link> to the location of the original page; such -snapshots can be created using [Freeze-dry][]. +## Snapshot format -This app requires the app [Raw][] to also be installed, in order to host the snapshots. +Currently this app only supports snapshots that are stored as plain html files (supporting [WARC][] +files could be a future addition). It recognises a file as being a snapshot if the file contains a +`` to the location of the original page; such snapshots can be created using [Freeze-dry][]. -## Usage +For example, assume you have an html file `example.html`. If this file contains a `` in its ``, it will be recognised as a snapshot of +`https://example.org`. + +## Requirements + +Besides of course Nextcloud itself (tested on version 14), this app requires the app [Raw][] to also +be installed, in order to host the snapshots. -The app presents a Memento TimeGate at the `/timegate/{url}` route. +## Usage -For example, assume you have an html file `example.html` in the folder `Documents/snapshots`. If -this file contains a `` in its ``, it will be -recognised as a snapshot of `https://example.org`. Visiting -`/apps/memento/timegate/https://example.org` would then redirect you to +This app presents a Memento TimeGate at the `/timegate/{url}` route. Assuming that the +`example.html` of the above example resides in the folder `Documents/snapshots`, then visiting +`/apps/memento/timegate/https://example.org` would redirect you to `/apps/raw/files/Documents/snapshots/example.html` (hence you need the [Raw] app as well). +Note that a private file will only be found if the client supplies login credentials (i.e. the +session cookie). Otherwise, only files for which 'Share link' has been enabled will be found. + In a typical Memento client (e.g. the [Memento Time Travel][] browser extension), you would add your -personal archive as `https://my-nextcloud/apps/memento/timegate/` (of course first replace -`my-nextcloud` appropriately). +archive as `https://my-nextcloud/apps/memento/timegate/` (of course first replace `my-nextcloud` +appropriately). A TimeMap is also exposed, at the `/timemap/{url}` route, to list all available snapshots of a URL. For details, look at the documentation of the Memento protocol ([RFC7089][]). +The app normally looks for shared snapshots of all users on the Nextcloud instance. To limit results +to those of a single user, use `.../u/{userid}/timegate/...` instead of `.../timegate/...` (and +likewise for `timemap`). + [Memento Time Travel]: https://addons.mozilla.org/en-US/firefox/addon/memento-timetravel/ [RFC7089]: https://tools.ietf.org/html/rfc7089 [Wayback Machine]: https://web.archive.org/ +[WARC]: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/ [Freeze-dry]: https://github.com/WebMemex/freeze-dry [Raw]: https://code.treora.com/gerben/nextcloud-raw