Feedmaster Achievement Bot

Automatically posts achievement notifications to Bluesky and/or Discord when users earn achievements in your feeds.

Quick Start

1. Clone and setup:

   git clone https://github.com/femavibes/feedmaster-bluesky-bot
   cd feedmaster-bluesky-bot

2. Start the bot (uses pre-built images):

   docker compose up -d

   Or for development (builds locally):

   docker compose -f docker-compose.dev.yml up -d

3. Configure via web interface:

   • Local deployment: Open http://localhost:8080
   • VPS deployment: Open http://YOUR_VPS_IP:8080 (e.g., http://123.45.67.89:8080)
   • Default login: Username: admin, Password: changeme
   • Fill in your Feedmaster API URL and Feed IDs
   • Add your Bluesky credentials
   • Adjust bot settings as needed
   • Click "Save Configuration" then "Restart Bot"

Configuration Methods

Option 1: Web Interface (Recommended)

1. Copy .env.example to .env
2. Change CONFIG_USERNAME and CONFIG_PASSWORD (required for security)
3. Start containers: docker compose up -d
4. Access configuration page:
   • Local: http://localhost:8080
   • VPS: http://YOUR_VPS_IP:8080
5. Fill out all bot settings via web form
6. Save & restart bot

Option 2: Manual Configuration

1. Copy .env.example to .env
2. Fill out all settings in the .env file
3. Start containers: docker compose up -d
4. Bot runs immediately with your settings

VPS Security Options

1. Change default password: Set CONFIG_USERNAME and CONFIG_PASSWORD in .env
2. SSH Tunnel: ssh -L 8080:localhost:8080 user@your-vps then use http://localhost:8080
3. Firewall: Restrict port 8080 to your IP only

Configuration Options

Required Settings

• FEED_IDS: Which feeds to monitor for achievements
• Either Bluesky OR Discord (or both):
  • BLUESKY_USERNAME: Bot account username (e.g., musicfeed.bsky.social) OR BLUESKY_DID: Account DID as fallback
  • BLUESKY_APP_PASSWORD: Generate this in Bluesky Settings → App Passwords
  • DISCORD_WEBHOOK_URL: Discord webhook URL for posting achievements

Optional Settings

• MIN_RARITY_TIER: Only post achievements of this rarity or higher (default: Diamond)
• POLL_INTERVAL_MINUTES: How often to check for new achievements (default: 5)
• MAX_POSTS_PER_HOUR: Rate limit to avoid spam (default: 10)
• MESSAGE_TEMPLATE: Custom message format (see below)

Message Template Variables

• {username}: User's handle (e.g., alice.bsky.social)
• {display_name}: User's display name (e.g., Alice Smith)
• {achievement}: Achievement name
• {rarity}: Rarity tier (Diamond, Legendary, etc.)
• {percentage}: Rarity percentage

Getting Feed IDs

1. Go to your feed on Feedmaster
2. Look at the URL: https://feedmaster.fema.monster/feed/3654
3. The number (3654) is your feed ID

Getting Bluesky App Password

1. Go to Bluesky Settings → Privacy and Security → App Passwords
2. Click "Add App Password"
3. Name it "Feedmaster Bot"
4. Copy the generated password to your .env file

Example Posts

Bluesky posts:

🎉 Congratulations Alice Smith on earning "Power Poster II"! 
Only 0.06% of users have achieved this Mythic rarity! 

[Achievement card with user avatar and rarity badge]

Discord posts:

• Rich embed with achievement title
• User avatar thumbnail
• Color-coded by rarity (Mythic = magenta, Diamond = light blue, etc.)
• Direct link to achievement page
• User handle and rarity percentage in fields

Monitoring

Check bot logs:

docker compose logs -f bluesky-bot

Troubleshooting

• "Authentication failed": Check your username and app password
• "No achievements found": Verify your feed IDs are correct
• "Rate limited": Bot automatically handles this, just wait

Support

For issues or questions, visit: https://github.com/femavibes/feedmaster-bluesky-bot

Getting Discord Webhook URL

1. Go to your Discord server settings
2. Navigate to Integrations → Webhooks
3. Click "New Webhook" or "Create Webhook"
4. Choose the channel where achievements should be posted
5. Copy the webhook URL to your .env file

Platform Configuration

The bot supports three modes:

• Bluesky only: Set BLUESKY_USERNAME and BLUESKY_APP_PASSWORD
• Discord only: Set DISCORD_WEBHOOK_URL
• Both platforms: Set all three variables above

Discord-Only Deployment

For Discord-only deployment:

1. Get Discord webhook URL (see above)
2. Configure via web interface:

   docker compose up -d
   # Open http://localhost:8080
   # Leave Bluesky fields empty
   # Fill in Discord Webhook URL
   # Configure other settings

3. Or configure via .env file:

   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_URL
   FEED_IDS=3654,5555
   MIN_RARITY_TIER=Diamond
   # Leave Bluesky fields empty

Discord Features:

• Rich embeds with achievement cards
• Color-coded by rarity tier
• User avatar thumbnails
• Direct links to achievement pages
• Same rate limiting and filtering as Bluesky