GTS-HolMirDas 🚀

RSS-based content discovery for GoToSocial instances.

Automatically discovers and federates content from RSS feeds across the Fediverse, helping small GoToSocial instances populate their federated timeline without relying on traditional relays.

Features

• 📡 Multi-Instance RSS Discovery - Fetches content from configurable RSS feeds across Fediverse instances
• ⚡ Efficient Processing - Configurable rate limiting and duplicate detection
• 🔧 Production Ready - Environment-based config, Docker deployment, health monitoring
• 📊 Comprehensive Statistics - Runtime metrics, content processing, and federation growth tracking
• 🐳 Containerized - Simple Docker Compose deployment
• 📁 File-based Configuration - Easy RSS feed management via text files

How it Works

GTS-HolMirDas reads RSS feeds from various Fediverse instances and uses GoToSocial's search API to federate the discovered content. This approach:

• Maintains proper ActivityPub federation (posts remain interactive)
• Respects rate limits and instance policies
• Provides better content discovery for small instances
• Works alongside tools like FediFetcher for comprehensive federation

Quick Start

# Clone the repository
git clone https://git.klein.ruhr/user/gts-holmirdas
cd gts-holmirdas

# Copy configuration templates
cp .env.example .env
cp rss_feeds.example.txt rss_feeds.txt

# Edit configuration
nano .env          # Add your GTS credentials
nano rss_feeds.txt # Customize RSS feeds

# Deploy
docker compose up -d

# Monitor
docker compose logs -f

Configuration

Environment Variables (.env)

# GTS Server Configuration
GTS_SERVER_URL=https://your-gts-instance.tld
GTS_ACCESS_TOKEN=your_gts_access_token

# Processing Configuration
MAX_POSTS_PER_RUN=25              # Posts per feed per run
DELAY_BETWEEN_REQUESTS=1          # Seconds between API calls
LOG_LEVEL=INFO                    # Logging verbosity

# RSS Configuration
RSS_URLS_FILE=/app/rss_feeds.txt  # Path to RSS feeds file

# Optional: Monitoring
HEALTHCHECK_URL=https://hc-ping.com/your-uuid

RSS Feeds (rss_feeds.txt)

# Example RSS feeds - customize for your interests
# homelab
https://mastodon.social/tags/homelab.rss
https://fosstodon.org/tags/homelab.rss

# selfhosting
https://mastodon.social/tags/selfhosting.rss
https://infosec.exchange/tags/selfhosting.rss

# Add your preferred instances and hashtags

Access Token Setup

1. Login to your GoToSocial instance
2. Go to Settings → Applications
3. Create new application with scopes: read, read:search, read:statuses
4. Copy the access token to your .env file

Statistics Output

📊 GTS-HolMirDas Run Statistics:
   ⏱️ Runtime: 0:04:14
   📄 Total posts processed: 45
   🌐 Current known instances: 2519
   ➕ New instances discovered: +3
   📡 RSS feeds processed: 25
   ⚡ Posts per minute: 10.6

Resource Requirements

• Memory: ~200-500MB depending on feed count
• CPU: Minimal (mostly I/O bound)
• Storage: <100MB for application, plus log storage
• Network: Depends on RSS feed count and frequency

Deployment Options

Docker Compose (Recommended)

docker compose up -d

Standalone Docker

docker build -t gts-holmirdas .
docker run -d --env-file .env \
  -v ./data:/app/data \
  -v ./gts_holmirdas.py:/app/gts_holmirdas.py:ro \
  -v ./rss_feeds.txt:/app/rss_feeds.txt:ro \
  gts-holmirdas

Monitoring

• Logs: docker compose logs -f
• Health: Optional Healthchecks.io integration
• Statistics: Built-in runtime and performance metrics
• Resource Usage: Docker stats or container monitoring tools

Troubleshooting

Common Issues

No posts processed: Check access token permissions and RSS feed URLs

Rate limiting errors: Increase DELAY_BETWEEN_REQUESTS or reduce feed count

High memory usage: Reduce MAX_POSTS_PER_RUN or feed frequency

Container won't start: Verify .env file format and required variables

Debug Mode

# Enable debug logging
echo "LOG_LEVEL=DEBUG" >> .env
docker compose restart gts-holmirdas

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Related Projects

• FediFetcher - Fetches missing replies and posts
• GoToSocial - Lightweight ActivityPub server
• slurp - Import posts from other instances

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by the HolMirDas concept
• Built for the GoToSocial community
• RSS-to-ActivityPub approach inspired by Fediverse discovery challenges