{"id":14037024,"url":"https://github.com/oduwsdl/raintale","last_synced_at":"2025-04-15T04:31:44.771Z","repository":{"id":46095467,"uuid":"172991385","full_name":"oduwsdl/raintale","owner":"oduwsdl","description":"A Python utility for publishing a social media story built from archived web pages to multiple services.","archived":false,"fork":false,"pushed_at":"2021-12-15T17:26:58.000Z","size":42509,"stargazers_count":11,"open_issues_count":14,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T06:28:24.260Z","etag":null,"topics":["mementos","social-media","storytelling","surrogates","web-archives","webarchives"],"latest_commit_sha":null,"homepage":"https://oduwsdl.github.io/raintale","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oduwsdl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-02-27T21:14:54.000Z","updated_at":"2023-12-27T03:57:18.000Z","dependencies_parsed_at":"2022-08-30T19:22:39.968Z","dependency_job_id":null,"html_url":"https://github.com/oduwsdl/raintale","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oduwsdl%2Fraintale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oduwsdl%2Fraintale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oduwsdl%2Fraintale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oduwsdl%2Fraintale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oduwsdl","download_url":"https://codeload.github.com/oduwsdl/raintale/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249006461,"owners_count":21197280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mementos","social-media","storytelling","surrogates","web-archives","webarchives"],"created_at":"2024-08-12T03:02:25.111Z","updated_at":"2025-04-15T04:31:42.626Z","avatar_url":"https://github.com/oduwsdl.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n\u003cimg src=\"images/raintale-logo.png\" width=\"100px\"\u003e\n\n# Raintale\n\nRaintale is a utility for publishing social media stories from groups of archived web pages (mementos). Raintale uses [MementoEmbed](https://github.com/oduwsdl/MementoEmbed)\n to extract memento information and then publishes a story to the given **storyteller**, a static file or an online social media service.\n\nRaintale accepts the following inputs:\n* a file containing a list of memento URLs (URI-Ms) (required)\n* a title for your story (required)\n* the URL of the underlying collection (optional)\n* the author, organization, or algorithm that generated the story (optional)\n* the storyteller to use when generating the story (e.g., HTML, Twitter, Markdown)\n* an output file for saving the story (if applicable)\n* a credential file for the a social media service (if applicable)\n* a template file allowing the user to format their story differently than the defaults (optional, and not supported by all storytellers)\n\nRaintale supports the following storytellers:\n* facebook - (EXPERIMENTAL) publishes a story as a Facebook thread, with titles, snippets, URLs, and memento-datetimes supplied by MementoEmbed\n* html - the HTML that makes up a story, suitable for pasting into a web page or a blogging application such as Blogger\n* twitter - publishes a story as a Twitter thread, with titles, URLs, memento-datetimes, and images supplied by MementoEmbed\n* template - given input data and a template file, this storyteller generates a story formatted based on the template and saves it to the given output file, allowing the end user to format their own stories\n* jekyll-html - writes output to [Jekyll](https://jekyllrb.com/) HTML file format, suitable for use with Jekyll and GitHub pages\n* jekyll-markdown - writes output to [Jekyll](https://jekyllrb.com/) Markdown file format, suitable for use with Jekyll and GitHub pages\n* markdown - writes output to the [GitHub Flavored Markdown](https://github.github.com/gfm/) file format, suitable for pasting into GitHub\n* mediawiki - writes output to this [MediaWiki](https://www.mediawiki.org/wiki/Help:Formatting) file format, suitable for pasting into MediaWiki pages\n\nRailtale also supports a number of presets for formatting a story for output to a specific file format:\n* default - provides a default set of fields like those seen in the social cards from social networking; may also provide an approximation, depending on file format (html, markdown, mediawiki, and jekyll storytellers)\n* thumbnails3col - provides a 3 column layout containing thumbnails of the submitted mementos (HTML storyteller only)\n* thumbnails4col - provides a 4 column layout containing thumbnails of the submitted mementos (HTML storyteller only)\n\nNote that not all file formats support all presets.\n\n\u003c!-- # Running Raintale\n\nRaintale uses docker-compose to load and execute all dependencies. To run Raintale, do the following:\n1. Create a directory on your system\n2. Copy docker-compose.yml from this repository into that directory\n3. Open a terminal\n4. Type: ```docker-compose run raintale tellstory --help``` to find the list of options\n\nFor example to create a raw HTML story suitable for pasting, type the following within that prompt:\n\n``\ndocker-compose run raintale tellstory -i story-mementos.txt --storyteller html -o mystory.html --title \"This is My Story Title\"\t--generated-by \"Me\"\n``\n\nThe output will be stored in ``mystory.html``.\n\nTo create a twitter story, 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.\n\n```\nconsumer_key: XXXXXX\nconsumer_secret: XXXXXX\naccess_token_key: XXXXXX\naccess_token_secret: XXXXXX\n```\n\nReplace the ``XXXXXX`` values with the corresponding values as displayed on your Twitter app page.\n\nOnce that is done, type the following within the Docker prompt:\n\n``\ndocker-compose run raintale tellstory -i story_mementos.txt --storyteller twitter --title \"This is My Story Title\"\t--generated-by \"Me” -c twitter-credentials.yml\n`` --\u003e\n\n# Installing Raintale\n\nBefore installing Raintale, make sure that the [MementoEmbed](https://github.com/oduwsdl/MementoEmbed) service is installed and running somewhere.\n\n## Installing Raintale on Linux or Unix\n\nBefore installing Raintale, you must have an instance of MementoEmbed running on a machine, either locally or elsewhere. If you do not have MementoEmbed, please install [the latest release of MementoEmbed](https://github.com/oduwsdl/MementoEmbed).\n\nTo install Raintale on Linux or Unix, choose your target platform below.\n\n### CentOS 8\n\nIf you would like to use the RPM installer for RHEL 8 and CentOS 8 systems:\n\n1. Download the RPM and save it to the Linux server (e.g., `raintale-0.20211106041644-1.el8.x86_64.rpm`)\n2. Type `dnf install raintale-0.20211106041644-1.el8.x86_64.rpm`\n3. Type `systemctl start raintale-django.service`\n\nTo stop Raintale, type `systemctl stop raintale-django.service`.\n\nTo remove Raintale, type `dnf remove raintale`. Removing Raintale stops the associated raintale service and its celery companion. Be patient, sometimes celery takes a long time to stop.\n\nDuring removal, the directory `/opt/raintale/raintale_with_wooey/raintale_with_wooey/user_uploads` is saved to `/opt/raintale/user_uploads-backup-[DATE].tar.gz` where [DATE] was the date and time of removal. This is where all story outputs are stored. The administrator may wish to delete or backup this file for future use.\n\n### Ubuntu 21.04\n\nIf you would like to use the DEB installer for RHEL 8 and CentOS 8 systems:\n\n1. Download the RPM and save it to the Linux server (e.g., `raintale-0.20211113202900.deb`)\n2. Type `apt-get install raintale-0.20211113202900.deb`\n3. Type `systemctl enable raintale-celery.service`\n4. Type `systemctl enable raintale-django.service`\n4. Type `systemctl start raintale-django.service`\n\nTo stop Raintale, type `systemctl stop raintale-django.service`.\n\nTo remove Raintale, type `apt-get remove raintale`.\n\n### Generic Unix\n\nWe also support a generic Unix installer which downloads many dependencies from the web. Unfortunately, these dependencies are not always version-locked and results on your system may vary.\n\n1. Download the generic Unix installer (e.g., `install-raintale.sh`)\n2. Type `install-raintale.sh`\n3. To start the Raintale WUI, type `/opt/raintale/start-raintale-wui.sh`\n\nTo stop raintale, type `/opt/raintale/stop-raintale-wui.sh`.\n\n## Installing Raintale in a Python Environment\n\nRaintale uses ```pip``` for build and installation. Clone this repository and type the following from the root of the source code:\n\n1. Clone this repository.\n2. Change into the directory where it was cloned.\n3. [Create a virtualenv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) to separate Raintale's install from other Python installations.\n4. Type ```pip install .``` \n\n## Installing the Raintale Web User Interface (WUI) in a Python Environment\n\nTo install the Raintale WUI, do the following:\n1. Follow the above instructions for installing Raintale in a Python Environment.\n2. Type `raintale-gui/install-gui.sh`\n4.\n\nThis installation script will install [Wooey](https://github.com/wooey/Wooey) and other dependencies required to run the Raintale WUI.\n\nTo stop Raintale WUI, type `raintale-gui/stop-gui.sh`.\n\n# Improving the performance of the Raintale WUI\n\nOnce installed, Raintale's WUI performance can be improved in a few ways.\n\n## Configuring Raintale WUI for Postgres\n\nBy default, the Raintale WUI uses SQLite, which does not perform well for multiple users logging into the same Raintale WUI system. For optimial user experience, the Raintale WUI can be connected to a Postgres database.\n\n1. Install Postgres on a system accessible to the server that on which the Raintale WUI is running. Record that system's host and the port Postgres is running on -- the default port is 5432.\n2. Log into Postgres and create a database with postgres for Raintale.\n3. Create a user and password.\n4. Grant all privileges on the database from step 2 in step 3.\n5. Run `/opt/raintale/raintale-gui/set-raintale-database.sh --dbuser [DBUSER] --dbname [DBNAME] --dbhost [DBHOST] --dbport [DBPORT]` -- with DBUSER created from step 3, DBNAME replaced by the database you created in step 2, DBHOST and DBPORT recorded from step 1. The script will prompt you for the password.\n6. Restart Raintale as appropriate for your system.\n\n#### Configuring the Raintale WUI for RabbitMQ\n\nFor optimal process control, the Raintale WUI can use a queueing service like RabbitMQ.\n\n1. Install RabbitMQ on a system accessible to the server that the Raintale WUI is running on. Record that system's hostname and the port that RabbitMQ is running on -- the default port is 5672.\n2. Run `/opt/raintale/raintale-gui/set-raintale-queueing-service.sh --amqp-url amqp://[HOST]:[PORT]/` where HOST is the host of the RabbitMQ server and PORT is its port\n\n# Enabling Raintale's Experimental Video Stories for the Raintale WUI on CentOS 8\n\nBy default, Raintale's video stories are not enabled in the Raintale WUI in CentOS 8 installs. Generating these stories requires ffmpeg. Installing ffmpeg on Ubuntu is easy. Installing ffmpeg on CentOS 8 requires using YUM/DNF repositories outside of those provided by CentOS, as detailed in [https://linuxize.com/post/how-to-install-ffmpeg-on-centos-8/](these instructions). Rather than force all Centos 8 Raintale administrators to go through this process, we have disabled video stories through the Raintale WUI.\n\nTo enable them:\n1. install ffmpeg\n2. Open `/opt/raintale/raintale-gui/add-raintale-scripts.sh` in an editor and remove the # and space from the line containing `Create Video Story.py` so it looks like this (spaces are significant):\n```\npython ${WOOEY_DIR}/manage.py addscript \"${SCRIPT_DIR}/scripts/Create Video Story.py\"\n```\n3. Run `/opt/raintale/raintale-gui/add-raintale-scripts.sh`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foduwsdl%2Fraintale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foduwsdl%2Fraintale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foduwsdl%2Fraintale/lists"}