This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

❓ FAQ - Frequently Asked Questions

Common questions and answers about GTS-HolMirDas deployment, configuration, and troubleshooting.

🚀 Getting Started

Q: What exactly does GTS-HolMirDas do?

A: GTS-HolMirDas monitors RSS feeds for new content and uses GoToSocial's search API to help your instance discover and federate with new content and instances. It essentially bootstraps your GoToSocial federation by automatically finding interesting posts from across the Fediverse.

Q: Do I need a GoToSocial instance to use this?

A: Yes, GTS-HolMirDas is specifically designed for GoToSocial instances. It uses GoToSocial's API for content discovery and federation. For Mastodon instances, consider using relays or FediFetcher for thread completion instead.

Q: How is this different from FediFetcher?

FediFetcher: Fetches replies/context from followed accounts (Mastodon/GoToSocial)
GTS-HolMirDas: Discovers new content via RSS feeds (GoToSocial only)
Best Practice: Use both together for maximum federation

🔧 Configuration

Q: How many RSS feeds should I configure?

A: Start with 20-30 high-quality feeds. More isn't always better:

20-30 feeds: Good balance of discovery vs. performance
50+ feeds: Higher resource usage, potential duplicates
Quality > Quantity: 20 active feeds better than 50 inactive ones

Q: Which RSS feeds work best?

A: Recommended feed types:

Mastodon/GoToSocial tag feeds (best federation discovery)
- https://mastodon.social/tags/homelab.rss
- https://social.tchncs.de/tags/docker.rss
Tech community feeds (good quality content)
- https://lobste.rs/rss
- https://planet.debian.org/rss20.xml
Specialized Reddit RSS (medium quality)
- https://www.reddit.com/r/selfhosted/.rss

Q: What access token permissions do I need?

A: Your GoToSocial access token needs these scopes:

read (general read access)
read:search (for search API - this is crucial!)
read:statuses (for status lookup)

Common mistake: Using only read without read:search causes 401 errors.

Q: How often should GTS-HolMirDas run?

A: Recommended intervals:

1 hour: Active discovery, more resource usage
3 hours: Balanced approach (recommended)
6+ hours: Light discovery, minimal resources

📊 Performance & Resources

Q: How much memory does GTS-HolMirDas use?

A: Typical memory usage:

20 feeds: 50-150MB
30 feeds: 100-250MB
50+ feeds: 200-400MB

Memory usage scales with feed count and post processing volume.

Q: Why is my runtime so long (>10 minutes)?

A: Common causes:

Too many feeds: Reduce to 20-30 feeds
Broken RSS feeds: Check feed validity with curl -I
Network issues: Check your internet connection
Rate limiting: GoToSocial API limits exceeded

Quick fix: Reduce MAX_POSTS_PER_RUN to 15-20.

Q: How many new instances should I expect to discover?

A: Realistic expectations:

Week 1: 500-1,500 instances (rapid initial discovery)
Month 1: 2,000-4,000 instances (steady growth)
Mature deployment: 5,000+ instances, +10-30 new/day

🛠️ Troubleshooting

Q: I get "401 Unauthorized" errors for RSS feeds

A: This indicates your access token lacks read:search permissions:

Go to GoToSocial Settings → Applications
Create new token with read, read:search, read:statuses
Update your .env file with the new token
Restart the container

Q: GTS-HolMirDas reports "0 posts processed" every run

A: This is normal after initial runs! Reasons:

All URLs in RSS feeds already processed (duplicate detection working)
RSS feeds haven't updated with new content
Feeds are inactive/low-volume

Not a problem unless it persists for days with active feeds.

Q: The "New instances discovered" number looks wrong

A: Known issue where it shows total instances instead of increment:

➕ New instances discovered: +2,431  # Should be ~+12

Workaround: Look at the progression of "Current known instances" between runs. The actual discovery is working correctly.

Q: Docker container keeps restarting

A: Check these common issues:

Invalid .env file: Verify all required variables are set
Bad access token: Test token with GoToSocial API
File permissions: Ensure processed_urls.txt is writable
Memory limits: Check if container hits memory limit

Debug with: docker logs gts-holmirdas

🌐 Federation & Content

Q: Will this flood my GoToSocial instance with posts?

A: No! GTS-HolMirDas only helps your instance discover content - it doesn't automatically boost or import posts. Users still need to follow accounts or search for content to see it in their timelines.

Q: Can I control what type of content gets discovered?

A: Yes, through RSS feed selection:

Tech content: Use tech blog RSS feeds
General Fediverse: Use Mastodon tag feeds
Specific topics: Use topic-specific RSS feeds
Quality control: Regularly review and rotate feeds

Q: Does this work with Mastodon instances?

A: No, GTS-HolMirDas is GoToSocial-specific due to API differences. For Mastodon, use:

FediFetcher for reply/context fetching
Mastodon's built-in relay system for federation

🔒 Security & Privacy

Q: Is it safe to run this on my production instance?

A: Yes, with proper configuration:

Uses read-only API calls (no posting/modification)
Respects GoToSocial rate limits
Only processes public RSS feeds
No sensitive data storage

Q: What data does GTS-HolMirDas store?

A: Minimal data storage:

processed_urls.txt: List of already-processed URLs (for duplicate prevention)
No post content, no user data, no credentials (beyond access token)

Q: Can I run multiple instances of GTS-HolMirDas?

A: Not recommended on the same GoToSocial instance:

API rate limiting conflicts
Duplicate processing overhead
No benefit over single instance with more feeds

🚀 Advanced Usage

Q: Can I integrate this with monitoring systems?

A: Yes! GTS-HolMirDas supports:

Healthchecks.io: Set HEALTHCHECK_URL environment variable
Log monitoring: Parse output for metrics
Docker monitoring: Standard Docker stats integration
Custom monitoring: Parse JSON-structured logs (future feature)

Q: How do I backup my configuration?

A: Backup these files:

.env (environment configuration)
processed_urls.txt (processed URL history)
compose.yml (deployment configuration)

Q: Can I run this without Docker?

A: Yes, but Docker is recommended:

# Direct Python execution
pip install -r requirements.txt
python gts_holmirdas.py

Set environment variables manually instead of using .env file.

Q: How do I contribute new RSS feeds?

A: Share good RSS feeds via:

GitHub/Gitea issues with feed URL and description
Pull requests updating documentation
Community discussions in Fediverse

Good RSS feed criteria:

Regular updates (daily/weekly)
Fediverse-relevant content
Reliable uptime
Not behind paywalls

📈 Scaling & Production

Q: My GoToSocial instance is small - is this overkill?

A: Not at all! Benefits scale with instance size:

Small instances: Discover initial content and communities
Medium instances: Maintain federation breadth
Large instances: Fine-tune content discovery

Start with 10-15 feeds and scale up based on results.

Q: Can I run this on a schedule instead of continuous loops?

A: Yes! Use cron instead of internal sleep:

# Remove SLEEP_INTERVAL from .env
# Add to crontab:
0 */3 * * * docker run --env-file .env gts-holmirdas

Q: How do I update GTS-HolMirDas?

A: Standard Docker update process:

docker compose down
docker compose pull  # If using pre-built image
# OR
git pull origin main  # If building from source
docker compose build --no-cache
docker compose up -d

🆘 Still Need Help?

Where to get support:

Documentation: Check the Wiki
Common Issues: See Troubleshooting Guide
Bug Reports: Open an issue on the repository
Community Support: Ask on Fediverse @matthias@me.klein.ruhr
Feature Requests: GitHub/Gitea issues with "enhancement" label

Before asking for help:

Check Docker logs: docker logs gts-holmirdas
Verify access token permissions
Test a single RSS feed manually
Check if your GoToSocial instance is accessible

Most common solution: Recreate access token with proper scopes! 🔑