brad/masto-rss
1
0
Fork 0
mirror of https://github.com/aserper/masto-rss.git synced 2025-12-17 05:15:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
unroll3677
2025-07-16 14:35:20 +02:00
committed by GitHub
parent c42d230053
commit 6ff72f7f97
1 changed files with 81 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
README.md
View File

@@ -11,44 +11,83 @@ This project is based on the original concept of [masto-rss](https://github.com/
* **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**: Comes with a `Dockerfile` and `docker-compose.yml` for easy, reliable, and isolated deployment.
* **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.
## Setup & Configuration
## Getting Started
The recommended way to run this bot is by using Docker and Docker Compose.
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 in `Preferences > Development`. You will need the `Client Key`, `Client Secret`, and `Access Token`.
* A Mastodon account and an application set up via **Preferences > Development**. You will need the **Client Key**, **Client Secret**, and **Access Token**.
### 2. Create the Project Files
### 2. Configuration
Create a directory for your project and place the following files inside:
You only need to create one file: `docker-compose.yml`.
1. `masto-rss.py` (The Python script)
2. `Dockerfile`
3. `requirements.txt`
4. `docker-compose.yml`
First, create a directory for your project and navigate into it:
### 3. Configure Environment Variables
```bash
mkdir my-masto-bot
cd my-masto-bot
```
All configuration is handled through the `docker-compose.yml` file. Open it and edit the `environment` section with your own details.
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.**
| 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` |
```yaml
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
@@ -64,7 +103,6 @@ You can change the layout of your posts using the `TOOT_TEMPLATE` variable. Use
```yaml
- TOOT_TEMPLATE='{title} - {link} {hashtags}'
```
* **Personalized Format:**
```yaml
- TOOT_TEMPLATE='New on the blog: {title}\nRead it here: {link}\n\n{hashtags}'
@@ -72,18 +110,19 @@ You can change the layout of your posts using the `TOOT_TEMPLATE` variable. Use
## Running the Bot
1. Make sure you have configured your `docker-compose.yml` file correctly.
2. Create the state directory from your terminal:
1. **Create the `state` directory.** This is required for the bot to remember which links it has already posted.
```bash
mkdir ./state
```
3. Start the container in detached mode:
2. **Start the container** in detached (background) mode:
```bash
docker-compose up -d
```
The bot is now running!
### Managing the Container
## Managing the Bot
* **View logs in real-time:**
```bash
@@ -100,13 +139,20 @@ The bot is now running!
docker-compose restart
```
* **Update the script and rebuild the image:**
## Updating the Bot
To update to the latest version of the image from Docker Hub:
1. **Pull the latest image:**
```bash
docker-compose up -d --build
docker-compose pull
```
2. **Restart the container** to apply the update:
```bash
docker-compose up -d
```
## Acknowledgements
This project is heavily inspired by and based on the original [masto-rss](https://github.com/aserper/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.
* This project is heavily inspired by and based on the original [masto-rss](https://github.com/piko-system/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.