Seven of Nine - Territory Defense Scheduler

A Discord bot for Star Trek Fleet Command territory defense reminders with web-based management. Named after the Borg character Seven of Nine from Star Trek: Voyager.

Features

• Web-Based Admin Panel: Manage all schedules through a simple, tabbed web interface
• Discord OAuth Authentication: Secure login with your Discord account
• Territory Defense Reminders: Schedule weekly reminders for territory takeovers
• Message Templates: Choose from predefined message templates or use defaults
• Auto-Publishing: Automatically publishes messages in announcement channels
• Role Mentions: Configure role mentions for notifications
• Advance Notifications: Send reminders 5-10 minutes before defense time
• Timezone Support: Times are in UTC with automatic conversion in Discord
• Simple Design: Blunt, efficient interface inspired by the Borg

Prerequisites

• Python 3.12+
• Discord Bot Application - Create one at the Discord Developer Portal

Discord Application Setup

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name (e.g., "Seven of Nine")
3. Navigate to the Bot tab:
   • Click "Add Bot"
   • Enable SERVER MEMBERS INTENT
   • Enable MESSAGE CONTENT INTENT
   • Copy your bot token for later
4. Navigate to OAuth2 → General:
   • Add redirect URL: http://localhost:8000/oauth/callback (or your production URL)
   • Copy your Client ID and Client Secret
5. Navigate to OAuth2 → URL Generator:
   • Select scopes: bot, applications.commands
   • Select bot permissions:
     • Read Messages/View Channels
     • Send Messages
     • Send Messages in Threads
     • Manage Messages (for auto-publishing)
     • Embed Links
     • Read Message History
     • Mention Everyone
     • Use Slash Commands
   • Copy the generated URL and use it to invite the bot to your server

Installation

1. Clone or download this repository

   git clone https://github.com/ComputerEndProgram/Seven-of-Nine.git
   cd Seven-of-Nine

2. Install Python dependencies

   python3 -m pip install -U pip
   python3 -m pip install -r requirements.txt

3. Configure the application

   Copy the example environment file:

   cp .env.example .env

   Edit .env with your settings:

   # Discord Bot Configuration
   TOKEN=your_discord_bot_token_here
   SYNC_SLASH_COMMANDS=on
   
   # Web Dashboard Configuration
   BASE_URL=http://localhost:8000
   DISCORD_CLIENT_ID=your_discord_client_id_here
   DISCORD_CLIENT_SECRET=your_discord_client_secret_here
   DISCORD_OAUTH_REDIRECT_URI=http://localhost:8000/oauth/callback
   SESSION_SECRET=generate_a_random_secret_key_here
   
   # Database
   DATABASE_URL=sqlite+aiosqlite:///./seven_of_nine.db
   
   # Web Server
   WEB_UI_PORT=8000
   

   Important Configuration Notes:

   • Get TOKEN from your bot's page in the Discord Developer Portal (Bot tab)
   • Get DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET from OAuth2 → General
   • Generate SESSION_SECRET with: python3 -c "import secrets; print(secrets.token_hex(32))" or run python3 generate_secret.py
   • Set SYNC_SLASH_COMMANDS=on on first run, then change to off for subsequent runs

4. Configure territory presets (optional)

   Edit territory_presets.json to add or modify territory names:

   {
     "territories": [
       "Astrida",
       "Corvus",
       "Kaikara",
       "Morada",
       "Talios",
       "Xind"
     ]
   }

   Note: Territory management is done by editing this file directly for admin control.

Usage

Start the application (this starts both the bot and web dashboard):

python3 main.py

The application will:

1. Start the Discord bot
2. Start the web dashboard on http://localhost:8000
3. Begin checking for scheduled reminders

Access the web dashboard at http://localhost:8000 and login with Discord to manage schedules.

Using the Dashboard

1. Login: Click "Login with Discord" on the home page
2. Select Guild: Choose a server where you have "Manage Server" permission
3. Configure Guild (Configuration Tab):
   • Enter a role ID for mentions (optional, defaults to @everyone)
   • To get a role ID: Enable Developer Mode in Discord → Right-click role → Copy ID
4. Create Schedule (Scheduled Messages Tab):
   • Select a territory name from the preset list
   • Choose a message template
   • Choose a channel where reminders will be sent
   • Select the day of the week
   • Enter the time in UTC (24-hour format)
   • Optionally set advance notice (5-10 minutes before defense)
   • Click "Create Schedule"
5. Manage Schedules: View, enable/disable, or delete existing schedules in the table
6. Manage Territories (optional):
   • Edit territory_presets.json directly to add/remove territory names
   • Changes take effect after restarting the application

Discord Commands

The bot has minimal Discord commands. All management is done through the web dashboard.

• /info - Display bot information and dashboard link

Message Format

Territory defense reminders use this format:

🛸 Territory Defense Notification: [Territory Name]

@Role

A Territory Defense is scheduled for [Timestamp].

— Transmission complete.

The timestamp is automatically converted to each user's local timezone in Discord.

Docker Deployment

You can deploy Seven of Nine using Docker for easier management.

1. Clone and configure

   git clone https://github.com/ComputerEndProgram/Seven-of-Nine.git
   cd Seven-of-Nine
   cp .env.example .env
   # Edit .env with your configuration

2. Build and run with Docker Compose

   docker compose up -d

3. View logs

   docker compose logs -f

4. Stop the container

   docker compose down

Production Deployment

Using a Reverse Proxy (Caddy)

1. Update your .env file with production URLs:

   BASE_URL=https://sevenofnine.yourdomain.com
   DISCORD_OAUTH_REDIRECT_URI=https://sevenofnine.yourdomain.com/oauth/callback
   

2. Update Discord OAuth settings in the Developer Portal with your production redirect URI

3. Configure Caddy (Caddyfile):

   sevenofnine.yourdomain.com {
       reverse_proxy localhost:8000
   }

4. Run with a process manager (e.g., systemd):

   Create /etc/systemd/system/sevenofnine.service:

   [Unit]
   Description=Seven of Nine Territory Defense Bot
   After=network.target
   
   [Service]
   Type=simple
   User=yourusername
   WorkingDirectory=/path/to/Seven-of-Nine
   Environment="PATH=/usr/local/bin:/usr/bin:/bin"
   ExecStart=/usr/bin/python3 main.py
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target

   Enable and start:

   sudo systemctl daemon-reload
   sudo systemctl enable sevenofnine
   sudo systemctl start sevenofnine

Troubleshooting

Bot won't start:

• Check that your TOKEN is correct in .env
• Verify the bot has the required intents enabled in Discord Developer Portal

Can't login to dashboard:

• Verify DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET are correct
• Check that the redirect URI is added in Discord OAuth2 settings
• Make sure BASE_URL matches your actual URL

Schedules not sending:

• Verify the bot has permissions to send messages in the channel
• Check that the schedule is enabled (not disabled)
• Look at the "Next Send" time to see when it will send

Messages not auto-publishing:

• The bot needs "Manage Messages" permission
• This only works in announcement channels (Discord News channels)

Technical Details

• Language: Python 3.12+
• Bot Framework: discord.py 2.5.2
• Web Framework: FastAPI
• Database: SQLite with SQLAlchemy (async)
• Authentication: Discord OAuth2 with signed cookies

License

GNU General Public License v3.0 - See LICENSE.txt for details.

Acknowledgments

Based on code from the message-scheduler-old project by Taaku18.

---

Seven of Nine, Tertiary Adjunct of Unimatrix 01
Resistance is futile.