Add comprehensive deployment documentation
Created DEPLOYMENT.md with detailed instructions for: - Quick start guide for local Python deployment - Background process management (nohup, screen, systemd) - Docker and Docker Compose deployment - Unraid-specific deployment methods - Credential acquisition steps - Troubleshooting common issues - Monitoring and logging - Bot commands reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Michael Simard
395
DEPLOYMENT.md
Normal file
395
DEPLOYMENT.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# Discord Stock Bot - Deployment Guide
|
||||
|
||||
This guide provides detailed instructions for deploying and running the Discord stock bot.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting the bot, ensure you have the following:
|
||||
|
||||
1. **Python 3.9 or higher** installed on your system
|
||||
2. **Discord Bot Token** from Discord Developer Portal
|
||||
3. **Discord Channel ID** where the bot will post updates
|
||||
4. **Finnhub API Key** (free tier available at https://finnhub.io)
|
||||
5. **Git** (optional, for cloning the repository)
|
||||
|
||||
## Quick Start (Local Python)
|
||||
|
||||
### 1. Clone or Download the Repository
|
||||
|
||||
```bash
|
||||
# If using Git
|
||||
git clone ssh://git@git.michaelsimard.ca:28/msimard/discord-stock-bot
|
||||
cd discord-stock-bot
|
||||
|
||||
# Or download and extract the files manually
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
# Create a virtual environment (recommended)
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install required packages
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 3. Configure Environment Variables
|
||||
|
||||
```bash
|
||||
# Copy the example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env with your credentials
|
||||
nano .env # or use any text editor
|
||||
```
|
||||
|
||||
Required configuration in `.env`:
|
||||
|
||||
```env
|
||||
# Discord Configuration
|
||||
DISCORD_TOKEN=your_discord_bot_token_here
|
||||
CHANNEL_ID=your_channel_id_here
|
||||
|
||||
# Bot Configuration
|
||||
COMMAND_PREFIX=!
|
||||
|
||||
# Stock Configuration
|
||||
PRIMARY_TICKER=PYPL
|
||||
STOCK_API_PROVIDER=finnhub
|
||||
FINNHUB_API_KEY=your_finnhub_api_key_here
|
||||
|
||||
# Scheduling Configuration
|
||||
UPDATE_INTERVAL_HOURS=1
|
||||
```
|
||||
|
||||
### 4. Run the Bot
|
||||
|
||||
```bash
|
||||
python3 bot.py
|
||||
```
|
||||
|
||||
The bot will start and display connection status in the console.
|
||||
|
||||
### 5. Verify Bot is Running
|
||||
|
||||
Check the console output for:
|
||||
```
|
||||
INFO - Bot connected as [bot_name] (ID: [bot_id])
|
||||
INFO - Target channel found: #[channel_name]
|
||||
INFO - Using Finnhub API for stock data
|
||||
```
|
||||
|
||||
## Running in Background
|
||||
|
||||
### Using nohup (Unix/Linux/macOS)
|
||||
|
||||
```bash
|
||||
nohup python3 bot.py > bot.log 2>&1 &
|
||||
```
|
||||
|
||||
To stop:
|
||||
```bash
|
||||
pkill -f "python3 bot.py"
|
||||
```
|
||||
|
||||
### Using screen (Unix/Linux/macOS)
|
||||
|
||||
```bash
|
||||
screen -S discord-bot
|
||||
python3 bot.py
|
||||
|
||||
# Detach: Press Ctrl+A, then D
|
||||
# Reattach: screen -r discord-bot
|
||||
# Kill: screen -X -S discord-bot quit
|
||||
```
|
||||
|
||||
### Using systemd (Linux)
|
||||
|
||||
Create `/etc/systemd/system/discord-stock-bot.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Discord Stock Price Bot
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=your_username
|
||||
WorkingDirectory=/path/to/discord-stock-bot
|
||||
Environment="PATH=/path/to/discord-stock-bot/venv/bin"
|
||||
ExecStart=/path/to/discord-stock-bot/venv/bin/python3 bot.py
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Enable and start:
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable discord-stock-bot
|
||||
sudo systemctl start discord-stock-bot
|
||||
sudo systemctl status discord-stock-bot
|
||||
```
|
||||
|
||||
View logs:
|
||||
```bash
|
||||
sudo journalctl -u discord-stock-bot -f
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Local Docker (Development)
|
||||
|
||||
```bash
|
||||
# Build and run with Docker Compose
|
||||
docker compose up --build
|
||||
|
||||
# Run in background
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
|
||||
# Stop
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Docker without Compose
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker build -t discord-stock-bot .
|
||||
|
||||
# Run container
|
||||
docker run -d \
|
||||
--name discord-stock-bot \
|
||||
--env-file .env \
|
||||
--restart unless-stopped \
|
||||
discord-stock-bot
|
||||
|
||||
# View logs
|
||||
docker logs -f discord-stock-bot
|
||||
|
||||
# Stop
|
||||
docker stop discord-stock-bot
|
||||
docker rm discord-stock-bot
|
||||
```
|
||||
|
||||
## Unraid Deployment
|
||||
|
||||
### Method 1: Docker Compose
|
||||
|
||||
1. Copy the project directory to your Unraid server:
|
||||
```bash
|
||||
scp -r discord-stock-bot/ root@unraid-server:/mnt/user/appdata/
|
||||
```
|
||||
|
||||
2. SSH into Unraid and navigate to the directory:
|
||||
```bash
|
||||
ssh root@unraid-server
|
||||
cd /mnt/user/appdata/discord-stock-bot
|
||||
```
|
||||
|
||||
3. Create and configure `.env` file
|
||||
|
||||
4. Run with Docker Compose:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Method 2: Unraid Docker Template
|
||||
|
||||
1. Build and push your image to Docker Hub:
|
||||
```bash
|
||||
docker build -t your-username/discord-stock-bot:latest .
|
||||
docker login
|
||||
docker push your-username/discord-stock-bot:latest
|
||||
```
|
||||
|
||||
2. In Unraid web UI:
|
||||
- Navigate to Docker tab
|
||||
- Click "Add Container"
|
||||
- Configure:
|
||||
- **Name**: discord-stock-bot
|
||||
- **Repository**: your-username/discord-stock-bot:latest
|
||||
- **Network Type**: bridge
|
||||
- **Add Variables**:
|
||||
- DISCORD_TOKEN
|
||||
- CHANNEL_ID
|
||||
- PRIMARY_TICKER
|
||||
- STOCK_API_PROVIDER
|
||||
- FINNHUB_API_KEY
|
||||
- COMMAND_PREFIX
|
||||
- TZ (America/New_York)
|
||||
|
||||
3. Click "Apply"
|
||||
|
||||
## Obtaining Required Credentials
|
||||
|
||||
### Discord Bot Token
|
||||
|
||||
1. Go to https://discord.com/developers/applications
|
||||
2. Click "New Application"
|
||||
3. Navigate to "Bot" section
|
||||
4. Click "Add Bot"
|
||||
5. Enable "Message Content Intent" under Privileged Gateway Intents
|
||||
6. Click "Reset Token" and copy the token
|
||||
7. Navigate to OAuth2 > URL Generator
|
||||
8. Select scopes: `bot`
|
||||
9. Select permissions: Send Messages, Embed Links, Read Messages/View Channels
|
||||
10. Use generated URL to invite bot to your server
|
||||
|
||||
### Discord Channel ID
|
||||
|
||||
1. Enable Developer Mode in Discord (User Settings > Advanced > Developer Mode)
|
||||
2. Right-click the desired channel
|
||||
3. Click "Copy Channel ID"
|
||||
|
||||
### Finnhub API Key
|
||||
|
||||
1. Visit https://finnhub.io/register
|
||||
2. Create a free account
|
||||
3. Copy your API key from the dashboard
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot Does Not Connect
|
||||
|
||||
**Issue**: Bot shows "Could not find channel with ID"
|
||||
|
||||
**Solution**:
|
||||
- Verify the bot has been invited to the server
|
||||
- Check that CHANNEL_ID is correct
|
||||
- Ensure bot has permissions to view the channel
|
||||
|
||||
### Stock Data Not Available
|
||||
|
||||
**Issue**: "Unable to retrieve data for ticker"
|
||||
|
||||
**Solution**:
|
||||
- Verify FINNHUB_API_KEY is correct
|
||||
- Check Finnhub API status
|
||||
- Try a different ticker (e.g., AAPL) to test API connection
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
**Issue**: "429 Too Many Requests"
|
||||
|
||||
**Solution**:
|
||||
- This occurs with Yahoo Finance after excessive queries
|
||||
- Switch to Finnhub by setting `STOCK_API_PROVIDER=finnhub`
|
||||
- Wait 1-24 hours for rate limit to reset
|
||||
|
||||
### Import Errors
|
||||
|
||||
**Issue**: ModuleNotFoundError
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Bot Crashes on Startup
|
||||
|
||||
**Issue**: Bot exits immediately
|
||||
|
||||
**Solution**:
|
||||
- Check all required environment variables are set
|
||||
- Verify Python version: `python3 --version` (must be 3.9+)
|
||||
- Check logs for specific error messages
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check Bot Status
|
||||
|
||||
```bash
|
||||
# Local Python
|
||||
ps aux | grep "python3 bot.py"
|
||||
|
||||
# Docker
|
||||
docker ps | grep discord-stock-bot
|
||||
|
||||
# Systemd
|
||||
sudo systemctl status discord-stock-bot
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Local Python (if using nohup)
|
||||
tail -f bot.log
|
||||
|
||||
# Docker Compose
|
||||
docker compose logs -f
|
||||
|
||||
# Docker
|
||||
docker logs -f discord-stock-bot
|
||||
|
||||
# Systemd
|
||||
sudo journalctl -u discord-stock-bot -f
|
||||
```
|
||||
|
||||
## Stopping the Bot
|
||||
|
||||
```bash
|
||||
# Local Python
|
||||
pkill -f "python3 bot.py"
|
||||
|
||||
# Docker Compose
|
||||
docker compose down
|
||||
|
||||
# Docker
|
||||
docker stop discord-stock-bot
|
||||
|
||||
# Systemd
|
||||
sudo systemctl stop discord-stock-bot
|
||||
```
|
||||
|
||||
## Updating the Bot
|
||||
|
||||
```bash
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Reinstall dependencies (if changed)
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Restart bot
|
||||
pkill -f "python3 bot.py"
|
||||
python3 bot.py
|
||||
|
||||
# Or with Docker
|
||||
docker compose down
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
## Bot Commands
|
||||
|
||||
Once running, the bot responds to these commands in Discord:
|
||||
|
||||
- `!stock <TICKER>` - Get current stock price for any ticker
|
||||
- `!price <TICKER>` - Alternative command for stock price
|
||||
- `!market` - Check if NYSE is currently open
|
||||
- `!ping` - Check bot responsiveness
|
||||
|
||||
**Hourly Updates**: The bot automatically posts PYPL price updates every hour during NYSE market hours (9:30 AM - 4:00 PM ET, Monday-Friday).
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Never commit `.env` file to version control
|
||||
- Keep your Discord token and API keys secure
|
||||
- Regularly rotate API keys
|
||||
- Use environment variables for all sensitive data
|
||||
- Run bot with minimal necessary permissions
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Check logs for error messages
|
||||
- Verify all configuration values
|
||||
- Ensure all prerequisites are installed
|
||||
- Review README.md for additional information
|
||||
Reference in New Issue
Block a user