masto-rss/README.md

Masto-RSS Advanced Bot

A flexible and robust Python script to automatically post the latest entry from an RSS feed to Mastodon, designed to run continuously in a Docker container.

This project is based on the original concept of masto-rss but has been significantly rewritten and extended with modern features for stability and customization.

Features

• Posts Only the Latest Item: Checks an RSS feed periodically and posts only the single most recent entry, preventing feed spam.
• Prevents Duplicates: Keeps a history of posted items to ensure the same link is never posted twice.
• History Limit: The history file is automatically pruned to a configurable size (MAX_HISTORY_SIZE) to prevent it from growing indefinitely.
• Custom Toot Format: Fully customize the look of your posts using a template string with placeholders ({title}, {link}, {hashtags}).
• Hashtag Support: Automatically append a configurable list of hashtags to every post.
• Dockerized: Runs as a pre-built container image for easy, reliable, and isolated deployment. You don't need to manage Python or dependencies.
• Robust Error Handling: Designed to run forever, it handles connection errors to the RSS feed or Mastodon gracefully without crashing.

Getting Started

The recommended and simplest way to run this bot is by using the pre-built Docker image from Docker Hub with Docker Compose.

1. Prerequisites

• Docker and Docker Compose installed on your system.
• A Mastodon account and an application set up via Preferences > Development. You will need the Client Key, Client Secret, and Access Token.

2. Configuration

You only need to create one file: docker-compose.yml.

First, create a directory for your project and navigate into it:

mkdir my-masto-bot
cd my-masto-bot

Next, create a file named docker-compose.yml and paste the following content into it. You must edit the environment section with your own credentials and settings.

version: '3.8'

services:
  masto-rss:
    # Use the pre-built image from Docker Hub
    image: doorknob2947/masto-rss-advanced:latest
    container_name: masto-rss-bot
    restart: unless-stopped
    volumes:
      # This volume persists the history of posted links
      - ./state:/state
    environment:
      # --- Mastodon API Credentials (Required) ---
      - MASTODON_CLIENT_ID=YOUR_CLIENT_KEY_HERE
      - MASTODON_CLIENT_SECRET=YOUR_CLIENT_SECRET_HERE
      - MASTODON_ACCESS_TOKEN=YOUR_ACCESS_TOKEN_HERE
      - MASTODON_INSTANCE_URL=[https://mastodon.social](https://mastodon.social)

      # --- RSS Feed Configuration (Required) ---
      - RSS_FEED_URL=[https://www.theverge.com/rss/index.xml](https://www.theverge.com/rss/index.xml)

      # --- Bot Behavior (Optional) ---
      - CHECK_INTERVAL=3600 # Time in seconds between checks (e.g., 1 hour)
      - MAX_HISTORY_SIZE=500 # Max number of posted links to remember
      - TOOT_VISIBILITY=public # public, unlisted, private, or direct

      # --- Toot Content (Optional) ---
      - MASTO_RSS_HASHTAGS="news tech python" # Space-separated list of hashtags
      - TOOT_TEMPLATE='{title}\n\n{link}\n\n{hashtags}'

      # --- System (Do not change) ---
      - PYTHONUNBUFFERED=1

3. Environment Variables

All configuration is handled through the environment section in your docker-compose.yml file.

Variable	Description	Example
MASTODON_CLIENT_ID	Your Mastodon application's Client Key.	abc...
MASTODON_CLIENT_SECRET	Your Mastodon application's Client Secret.	def...
MASTODON_ACCESS_TOKEN	Your Mastodon application's Access Token.	ghi...
MASTODON_INSTANCE_URL	The base URL of your Mastodon instance.	https://mastodon.social
RSS_FEED_URL	The full URL of the RSS feed you want to monitor.	https://www.theverge.com/rss/index.xml
CHECK_INTERVAL	(Optional) The time in seconds between checks.	3600 (for 1 hour)
MASTO_RSS_HASHTAGS	(Optional) A space-separated list of hashtags to add to each post.	news tech python
MAX_HISTORY_SIZE	(Optional) The maximum number of post URLs to remember.	500
TOOT_VISIBILITY	(Optional) The visibility of the toot (public, unlisted, private, direct).	public
TOOT_TEMPLATE	(Optional) A string to format the toot. See "Customizing the Toot Format" below.	'{title}\n\n{link}\n\n{hashtags}'
PYTHONUNBUFFERED	Should be kept at 1 to ensure logs appear in real-time in Docker.	1

4. Customizing the Toot Format

You can change the layout of your posts using the TOOT_TEMPLATE variable. Use the following placeholders:

• {title}: The title of the RSS entry.
• {link}: The URL of the RSS entry.
• {hashtags}: The configured hashtags.

Examples in docker-compose.yml:

• Compact Format:

  - TOOT_TEMPLATE='{title} - {link} {hashtags}'
  

• Personalized Format:

  - TOOT_TEMPLATE='New on the blog: {title}\nRead it here: {link}\n\n{hashtags}'
  

Running the Bot

1. Create the state directory. This is required for the bot to remember which links it has already posted.

   mkdir ./state
   

2. Start the container in detached (background) mode:

   docker-compose up -d
   

The bot is now running!

Managing the Bot

• View logs in real-time:

  docker-compose logs -f
  

• Stop the container:

  docker-compose down
  

• Restart the container:

  docker-compose restart
  

Updating the Bot

To update to the latest version of the image from Docker Hub:

1. Pull the latest image:

   docker-compose pull
   

2. Restart the container to apply the update:

   docker-compose up -d
   

Acknowledgements

• This project is heavily inspired by and based on the original masto-rss. This version aims to add more robustness, flexibility, and ease of deployment using modern practices.
• The Python script, Docker configuration, and this README were written and modified with the assistance of AI.