discord-stock-bot/DEPLOYMENT.md

# 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