bsky.rss

A configurable RSS poster for Bluesky

Important

⚡ New User? → Quick Start Guide - Get posting in 10 minutes 🆘 Having Issues? → Troubleshooting Guide - Common problems & solutions

---

This app runs in two modes:

• Single-bot mode (this README) - one Bluesky account per container/process. Start here if you're running one bot.
• Fleet mode - many independent bots running out of a single process, instead of one container per bot. See the Fleet mode section below.

Deployment

Choose your preferred deployment method:

Cloud Platforms (Managed)

Deploy with one command and let the platform handle infrastructure:

• Fly.io - Best price/performance (~$5-10/month)
• Railway - Easiest setup with GitHub integration (~$5/month)
• Render - Free tier available, great for testing
• DigitalOcean App Platform - For existing DO users ($5/month)

📖 Full Deployment Guide · 🔄 Platform Comparison

Self-Hosted

Run on your own infrastructure:

Docker (Recommended for self-hosting)

Copy this docker-compose.yml file to your Docker host:

version: "3"
services:
  bsky-rss:
    restart: always
    image: ghcr.io/rmdes/bsky.rss
    environment:
      - APP_PASSWORD=
      - INSTANCE_URL=https://bsky.social
      - FETCH_URL=
      - IDENTIFIER=
    volumes:
      - /your/data/directory:/build/data

Mount /build/data to a directory on your host for persistent storage.

See Deployment Guide - Docker for details.

Manual / Development

For local development or custom setups:

git clone github.com/rmdes/bsky.rss
cd bsky.rss
yarn install
cp .env.example .env  # Edit with your credentials
yarn start

See Environment Variables below for configuration.

---

Not sure which to choose? See the Platform Comparison Guide for recommendations based on your needs.

Environment Variables & Configuration File

Environment Variables

Here's an outline of the environment variables:

• APP_PASSWORD: The password of the account that will be posting the RSS feed (you can use an account password, but it's recommended to use an app password)
• INSTANCE_URL: The URL of your Bluesky instance (if using the official one, use "https://bsky.social")
• FETCH_URL: The URL of the RSS feed you want to fetch & post from (e.g. "http://rss.cnn.com/rss/cnn_latest.rss")
• IDENTIFIER: The identifier for the account to post from (this can be the email address or the username of the account)

Configuration File

• If you set up the RSS poster using Docker, create the config.json file in your data directory that you mounted in the compose file.
• If you set up the RSS poster manually, rename the config.example.json file in the data directory to config.json.

Here's an example of the config.json file:

{
  "string": "$title - $link",
  "publishEmbed": true,
  "embedType": "card",
  "languages": ["en"],
  "ogUserAgent": "",
  "truncate": true,
  "runInterval": 60,
  "dateField": "",
  "publishDate": false,
  "imageField": "",
  "imageAlt": "$title",
  "forceDescriptionEmbed": false,
  "removeDuplicate": false,
  "descriptionClearHTML": false,
  "titleClearHTML": false,
  "adaptiveSpacing": false,
  "spacingWindow": 600,
  "minSpacing": 1,
  "maxSpacing": 60
}

• string: The string to post to Bluesky. You can use the following variables in the string:
  • $title: The title of the RSS post
  • $link: The link to the RSS post
  • $description: The description of the RSS post
  • $georss: An OpenStreetMap link built from the item's geographic coordinates, if the feed provides any - <georss:point> (GeoRSS Simple) or geo:lat/geo:long (W3C Basic Geo) as a fallback. Renders as an empty string when the item has neither.
  • [text](url): Markdown-style link syntax - text and url can both contain $placeholders (e.g. [$title]($link)). See CONFIGURATION.md for fallback behavior and more examples.
• publishEmbed: Whether to publish the post as an embed or not. If set to true, the post will be published as an embed with the title, description (if available), and link to the RSS post.
• embedType: Type of embed. If set to card, the post will be published with an Open Graph/link card. If set to image an image will be uploaded.
• languages: The languages to set the posts to. This can be an array of ISO 639-1 language codes. If not set, it will default to en.
• ogUserAgent: The user agent to use when fetching the Open Graph data of the URL provided by the RSS post. By default, this is set to bsky.rss/1.0 (Open Graph Scraper).
• truncate: Whether or not to truncate the body of the post if it is over 300 characters. By default, this is set to true.
• runInterval: The interval (in seconds) to run the RSS poster. By default (and recommended), this is set to 60 seconds.
• dateField: The field to use for the date of the RSS post. This can be any field that is available in the RSS feed. If not set, it will default to pubDate and/or date.
• publishDate: Whether or not to use the RSS item's date for the Bluesky post's createdAt. When false, the current date is used. When true, the item's date is used. By default, this is set to false.
• imageField: The field to use for fetching the image of the RSS post. This can be any field that is available in the RSS feed. If not set, the poster will fetch the Open Graph data of the URL provided by the RSS post and use the image from there.
• mappedValues: Maps specific dc:*/itunes:* feed fields into new $key template placeholders. See CONFIGURATION.md for the full recognized-value list and examples.
• imageAlt: Alt text for the uploaded image if the embedType is set to image. Can be any variable (+ string) used in the string configuration (e.g. $title).
• forceDescriptionEmbed: Force the description of the embed to be the description of the RSS post (as opposed to using Open Graph data).
• removeDuplicate: Instead of using the last date to track which items need to be published, use a text-based database to track duplicate items.
• descriptionClearHTML: Remove HTML from the description of the Open Graph description and RSS-provided description (to make it more readable).
• titleClearHTML: Remove HTML from the title of the post (to make it more readable).
• adaptiveSpacing: Enable adaptive spacing between posts based on the queue size.
• spacingWindow: Time window (in seconds) used when calculating adaptive spacing.
• minSpacing: Minimum number of seconds between posts when adaptive spacing is enabled.
• maxSpacing: Maximum number of seconds between posts when adaptive spacing is enabled.

A docker-compose.yml file can be found in the root directory as docker-compose.example.yml, which you can use to set up the RSS poster using Docker.

Contributing & Testing

This project has comprehensive test coverage with 129+ tests across both single-bot and fleet modes (90%+ coverage).

Run tests:

# All tests
yarn test

# Single-bot mode only
yarn test:app

# Fleet mode only
yarn test:fleet

# Coverage report
yarn test:coverage

Contributing:

• 📖 Testing Guide - Test patterns, mocking strategies, debugging
• 🤝 Contributing Guide - Coding standards, PR process, development setup

All pull requests require tests for new features and bug fixes. See the guides above for detailed information.

Fleet mode

If you want to run many bots (different accounts, different feeds) at once, fleet mode runs them all as independent workers inside a single process instead of one container per bot - the same image, just a different entry point (yarn fleet / fleet/runFleet.ts instead of yarn start / app/index.ts) and a different command: in your compose file.

Fleet mode gives each bot its own config, its own SQLite-backed dedup/session state, and a staggered login schedule, while sharing fleet-wide rate limits (Open Graph scraping, image processing) across all bots so N bots polling concurrently doesn't spawn unbounded work.

Two ways to get started:

• Deploying, not building - use the bsky-rss-fleet-template repo. It's a docker-compose.yml and example config tree that pulls the prebuilt image from ghcr.io/rmdes/bsky.rss, no source checkout needed.
• Building from this repo, migrating an existing single-bot setup, or rolling back - see documentation/fleet.md for the architecture, the legacy importer/exporter, and the full cutover sequence.

License

This project is licensed under the MIT License. See the LICENSE file for more information.