discopilot

A Discord bot that monitors channels and publishes content to social media platforms.

Features

• 🤖 Monitor Discord channels for specific emoji reactions
• 📢 Publish messages to Twitter (X) and other social media platforms
• 🔄 Smart rate limiting to prevent API throttling
• 🧙‍♂️ Named after Hedwig from Harry Potter - your magical messenger

Installation

From PyPI

pip install discopilot

From Source

git clone https://github.com/twinko-ai/discopilot.git
cd discopilot
uv venv .venv
source .venv/bin/activate
uv pip install -e .

Configuration

DiscoPilot requires a configuration file to run. You can set up your configuration in one of these ways:

1. Automatic setup:

   discopilot-setup
   

   This will create a configuration file at ~/.config/discopilot/config.yaml.

2. Manual setup:

   • Copy the example configuration from examples/config.example.yaml
   • Place it in one of these locations:
     • The current working directory as config.yaml
     • Your home directory at ~/.config/discopilot/config.yaml
   • Edit the file with your Discord token and other settings

3. Environment variable:

   • Set the DISCOPILOT_CONFIG environment variable to the path of your config file

   export DISCOPILOT_CONFIG=/path/to/your/config.yaml
   

Configuration Options

Option	Description	Required
discord.token	Your Discord bot token	Yes
discord.server_ids	List of server IDs the bot should listen to (empty = all servers)	No
admin_ids	List of Discord user IDs that can trigger publishing	Yes
triggers.emoji	The emoji that triggers publishing	No (default: 📢)
twitter.api_key	Twitter API key	Yes (for Twitter)
twitter.api_secret	Twitter API secret	Yes (for Twitter)
twitter.access_token	Twitter access token	Yes (for Twitter)
twitter.access_secret	Twitter access token secret	Yes (for Twitter)
twitter.bearer_token	Twitter bearer token	Yes (for Twitter)

Usage

1. Invite your bot to your Discord server using the OAuth2 URL from the Discord Developer Portal.

2. Send a message in any channel where the bot has access.

3. React to the message with the configured emoji (default: 📢). Note: Only users listed in admin_ids can trigger publishing.

4. The bot will publish the message to configured social media platforms and reply with the results.

Running on a Server (24/7)

Using Systemd (Linux)

1. Create a systemd service file:

   sudo nano /etc/systemd/system/discopilot.service

2. Add the following content (adjust paths as needed):

   [Unit]
   Description=DiscoPilot Discord Bot
   After=network.target
   
   [Service]
   User=yourusername
   WorkingDirectory=/path/to/working/directory
   ExecStart=/path/to/python -m discopilot.scripts.run_bot
   Restart=always
   RestartSec=10
   StandardOutput=syslog
   StandardError=syslog
   SyslogIdentifier=discopilot
   
   [Install]
   WantedBy=multi-user.target
   

3. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable discopilot
   sudo systemctl start discopilot

Using Docker

1. Create a Dockerfile:

   FROM python:3.11-slim
   
   WORKDIR /app
   
   COPY . .
   RUN pip install -e .
   
   CMD ["python", "-m", "discopilot.scripts.run_bot"]

2. Build and run:

   docker build -t discopilot .
   docker run -d --name discopilot --restart unless-stopped \
     -v /path/to/config.yaml:/root/.config/discopilot/config.yaml discopilot

Extending

Adding New Social Media Platforms

1. Create a new publisher class in discopilot/publishers/
2. Implement the publish() and check_rate_limit() methods
3. Add your publisher to the bot's setup_publishers() method

Development

Running Tests

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=discopilot

Deployment

AWS Lightsail Deployment

To deploy DiscoPilot on AWS Lightsail:

1. Go to the AWS Lightsail console
2. Click "Create instance"
3. Choose a location (AWS Region) close to you
4. Select "Linux/Unix" platform
5. Choose "Ubuntu 24.04 LTS" as the blueprint
6. Click "Add launch script" and paste the content of scripts/deployment/lightsail_launch.sh
7. Use default SSH key or create a new one
8. Enable automatic snapshots
9. Select network type
10. Select the instance plan like $5/month
11. Name your instance (e.g., "discopilot")
12. Click "Create instance"

After the instance is created:

1. Connect to your instance via SSH
2. Update the configuration file:

   edit-config

   or

   sudo nano /home/botuser/.config/discopilot/config.yaml

3. Start the service:

   sudo systemctl start discopilot

Maintenance Commands

The following commands are available after deployment:

• update-bot: Pull the latest code from GitHub, update scripts, reinstall dependencies, and restart the bot
• restart-bot: Restart the bot without updating
• bot-logs: View the bot's logs in real-time
• edit-config: Edit the bot configuration file

Manual Script Usage

If you prefer to run the scripts directly instead of using the aliases:

• /usr/local/bin/update_discopilot.sh: Update the bot from GitHub and restart
• /usr/local/bin/restart_discopilot.sh: Restart the bot without updating
• /usr/local/bin/run_discopilot.sh: Run the bot manually (used by the systemd service)
• /usr/local/bin/update-discopilot-scripts.sh: Update the scripts in /usr/local/bin with the latest versions from the repository