Getting Started

Raintale allows you to quickly publish your story using a variety of different storytellers corresponding to different file formats and social media services. The input for Raintale consists of text content and memento URLs (URI-Ms). Raintale will then publish the text verbatim and summarize the URI-Ms as surrogates (cards, thumbnails, etc.).

Note

Raintale only works for memento URLs (URI-Ms) from Memento-compliant web archives. It will not work for live web resources or mementos from web archives that do not support the Memento protocol. To create mementos of live web pages, use tools like the Save Page Now tool at the Internet Archive, the ArchiveNow Python utility, or the Mink Chrome Extension.

Quickly Running Raintale using Docker-Compose

Raintale uses docker-compose to ensure that users have everything needed to run Raintale quickly. Raintale requires two Docker containers to function:

  • MementoEmbed - to process mementos, extract content, and produce surrogates
  • Raintale - to generate stories from data provided by MementoEmbed

Quickly Creating an HTML Story

Telling an HTML story with Raintale requires three pieces of information:

  • the title of your story - this example uses a title of This is My Story Title
  • a file containing a list of URI-Ms - this example uses a file named story-mementos.txt
  • the name of the file to write your story - this example uses mystory.html

Thus, to generate an HTML story with Raintale using docker-compose and the default options, perform the following:

  1. Open a terminal on your system
  2. Create a directory for your project and change into that directory
  3. Download docker-compose.yml from https://raw.githubusercontent.com/oduwsdl/raintale/master/docker-compose.yml to that directory
  4. Type the following and press ENTER:
docker-compose run raintale tellstory -i story-mementos.txt --storyteller html -o mystory.html --title "This is My Story Title"

Note how the --storyteller argument instructs Raintale how to tell your story. In this case, we supplied the html value to tell a story using HTML.

Quickly Creating a Twitter Story

To create a twitter story, you will need the following:

  • the title of your story
  • a file containing a list of URI-Ms
  • A file containing your Twitter credentials - this example uses twitter-credentials.yml

To acquire Twitter credentials, you will need to create a Twitter app. Log into Twitter from a web browser and visit https://developer.twitter.com/en/apps for more information. Once you have created an app, make a file named twitter-credentials.yml, save it in the same directory, and fill it with the following content.

Replace the XXXXXX values with the corresponding values as displayed on your Twitter app page.

To tell your Twitter story, type the following:

docker-compose run raintale tellstory -i story_mementos.txt --storyteller twitter --title "This is My Story Title" -c twitter-credentials.yml

Note how, in this case, the --storyteller argument was supplied the twitter value. This instructed Raintale to publish a story to Twitter rather than writing it out to a file.

Setting Up Raintale to Run Natively

Raintale is written in Python and communicates to MementoEmbed using the MementoEmbed Web API. To run natively, Raintale has the following requirements:

Note

Raintale is developed using MacOS and Linux. We have not yet tested it with Microsoft Windows. We recommend running it using Docker on Microsoft Windows.

To install Raintale natively, do the following:

  1. Open a terminal
  2. Clone the repository from GitHub by typing: git clone https://github.com/oduwsdl/raintale.git
  3. Change into the raintale directory
  4. Type pip install . to install raintale and all dependencies
  5. OPTIONAL for video support - install ffmpeg

Note

Due to its dependency on MementoEmbed, we have not yet released Raintale via Pypi, but we may do so in the future to improve the ease of installation.