{"id":48601866,"url":"https://github.com/pacnpal/polly","last_synced_at":"2026-04-08T22:32:38.182Z","repository":{"id":312627290,"uuid":"1048110857","full_name":"pacnpal/polly","owner":"pacnpal","description":"A comprehensive Discord poll bot with admin-only access, web dashboard, and scheduled polls. Built with Python, FastAPI, discord.py, and HTMX.","archived":false,"fork":false,"pushed_at":"2026-02-13T17:46:40.000Z","size":2029,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T01:24:31.927Z","etag":null,"topics":["bootstrap","discord-bot","discord-py","fastapi","htmx","oauth2","polls","python","scheduler","sqlite","voting","web-dashboard"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pacnpal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security_monitor.py","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T23:52:46.000Z","updated_at":"2026-01-16T19:46:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"08984400-962b-45cc-ac4f-d48499ae31ab","html_url":"https://github.com/pacnpal/polly","commit_stats":null,"previous_names":["pacnpal/polly"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pacnpal/polly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fpolly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fpolly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fpolly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fpolly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pacnpal","download_url":"https://codeload.github.com/pacnpal/polly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fpolly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31577444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap","discord-bot","discord-py","fastapi","htmx","oauth2","polls","python","scheduler","sqlite","voting","web-dashboard"],"created_at":"2026-04-08T22:32:37.663Z","updated_at":"2026-04-08T22:32:38.172Z","avatar_url":"https://github.com/pacnpal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polly - Discord Poll Bot\n\nA comprehensive Discord poll bot with advanced scheduling, admin-only access, and a beautiful web interface for poll management.\n\n## Features\n\n### 🔐 Admin-Only Access\n- Only server administrators can create polls\n- Discord OAuth authentication with permission verification\n- Secure JWT-based web sessions\n\n### 📊 Advanced Poll Creation\n- Named polls with custom options (up to 10)\n- Full-size image uploads (not tiny thumbnails)\n- Rich Discord embeds with real-time vote counts\n- Emoji-based voting system (🇦 🇧 🇨 🇩 🇪 🇫 🇬 🇭 🇮 🇯)\n- User preferences system - remembers last used server, channel, and timezone\n- Anonymous polls option to hide results until poll ends\n\n### ⏰ Smart Scheduling\n- Calendar and time picker for precise scheduling\n- Automatic poll opening and closing\n- Timezone-aware scheduling system\n- Background job processing with APScheduler\n\n### 🌐 Web Dashboard\n- Beautiful Bootstrap-based interface with HTMX (NO JavaScript)\n- Create and manage polls from the web\n- Live updates without page refreshes\n- View poll history and results\n- Responsive design for mobile and desktop\n\n### 🕐 Timezone Support\n- US/Eastern timezone as default\n- Poll messages display times in selected timezone\n- Timezone-aware scheduling system\n- Support for major world timezones\n\n### ⚡ Lightning Fast\n- Built with modern Python stack (FastAPI + discord.py)\n- HTMX for dynamic UI without JavaScript\n- SQLite database for zero-configuration setup\n- Single application deployment\n- Managed with `uv` for blazing fast package management\n\n## Quick Start\n\n### Prerequisites\n- Python 3.11+\n- Discord Bot Token\n- Discord Application Client ID \u0026 Secret\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd polly\n   ```\n\n2. **Install dependencies with uv**\n   ```bash\n   uv sync\n   ```\n\n3. **Configure environment**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your Discord bot credentials\n   ```\n\n4. **Run the application**\n   ```bash\n   uv run python -m polly.main\n   ```\n\n5. **Access the web interface**\n   - Open http://localhost:8000\n   - Login with Discord\n   - Start creating polls!\n\n## Discord Bot Setup\n\n1. **Create Discord Application**\n   - Go to https://discord.com/developers/applications\n   - Click \"New Application\"\n   - Give it a name (e.g., \"Polly\")\n\n2. **Create Bot**\n   - Go to \"Bot\" section\n   - Click \"Add Bot\"\n   - Copy the bot token to your `.env` file\n\n3. **Configure OAuth2**\n   - Go to \"OAuth2\" section\n   - Add redirect URI: `http://localhost:8000/auth/callback`\n   - Copy Client ID and Client Secret to your `.env` file\n\n4. **Invite Bot to Server**\n   - Go to \"OAuth2\" \u003e \"URL Generator\"\n   - Select scopes: `bot`, `applications.commands`\n   - Select permissions: `Send Messages`, `Add Reactions`, `Use Slash Commands`\n   - Use generated URL to invite bot\n\n## Environment Configuration\n\nCreate a `.env` file with the following variables:\n\n```env\n# Discord Bot Configuration\nDISCORD_TOKEN=your_discord_bot_token_here\nDISCORD_CLIENT_ID=your_discord_client_id_here\nDISCORD_CLIENT_SECRET=your_discord_client_secret_here\n\n# Web Application Configuration\nDISCORD_REDIRECT_URI=http://localhost:8000/auth/callback\nSECRET_KEY=your-secret-key-for-jwt-tokens-change-this\nBASE_URL=http://localhost:8000\n```\n\n## Usage\n\n### Discord Commands\n\n- `/poll` - Create a quick poll with up to 5 options\n  - Example: `/poll question:\"What's your favorite color?\" option1:\"Red\" option2:\"Blue\" option3:\"Green\"`\n\n### Web Interface\n\n1. **Login** - Authenticate with Discord OAuth\n2. **Dashboard** - View and manage your polls with live statistics\n3. **Create Poll** - Use the web form for advanced options:\n   - Named polls with custom scheduling\n   - Image uploads (up to 8MB)\n   - Server and channel selection\n   - Anonymous poll option\n   - Timezone selection\n4. **Poll Management** - Full CRUD operations:\n   - Edit scheduled polls before they start\n   - View detailed poll results and analytics\n   - Manually close active polls\n   - Delete polls (with automatic image cleanup)\n\n### Poll Features\n\n- **Live Vote Updates** - Poll embeds update in real-time as users vote\n- **Smart User Preferences** - Remembers your last used server, channel, and timezone\n- **Automatic Messaging** - Sends completion message to the same channel when polls end\n- **Comprehensive Logging** - Full audit trail of all poll operations\n- **Image Management** - Automatic cleanup of uploaded images when polls are deleted\n- **Status-Based Actions** - Different management options based on poll status (scheduled/active/closed)\n- **Admin Only** - Only server administrators can create and manage polls\n\n## Architecture\n\n### Technology Stack\n- **Backend**: Python 3.11+, FastAPI, discord.py\n- **Database**: SQLite with SQLAlchemy ORM\n- **Frontend**: Bootstrap 5, HTMX (NO JavaScript)\n- **Scheduling**: APScheduler\n- **Authentication**: Discord OAuth2 + JWT\n- **Package Management**: uv\n\n### Project Structure\n```\npolly/\n├── polly/                  # Main package\n│   ├── __init__.py\n│   ├── main.py            # Application entry point\n│   ├── database.py        # Database models\n│   ├── auth.py            # Authentication logic\n│   └── discord_utils.py   # Discord bot utilities\n├── templates/             # HTML templates\n│   ├── index.html         # Landing page\n│   ├── dashboard.html     # Admin dashboard (legacy)\n│   ├── dashboard_htmx.html # HTMX-powered dashboard\n│   └── htmx/              # HTMX partial templates\n│       ├── polls.html     # Poll listing\n│       ├── stats.html     # Dashboard stats\n│       ├── create_form.html # Poll creation form\n│       └── servers.html   # Server selection\n├── static/uploads/        # Image storage\n├── cline_docs/           # Project documentation\n├── pyproject.toml        # Dependencies and config\n├── .env.example          # Environment template\n└── README.md             # This file\n```\n\n## Development\n\n### Package Management with uv\n\nThis project uses [uv](https://docs.astral.sh/uv/) for blazing fast Python package management. Here are the essential commands:\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install all dependencies (creates virtual environment automatically)\nuv sync\n\n# Add a new dependency\nuv add package-name\n\n# Add a development dependency\nuv add --dev package-name\n\n# Remove a dependency\nuv remove package-name\n\n# Update all dependencies\nuv sync --upgrade\n\n# Run commands in the virtual environment\nuv run python -m polly.main\nuv run uvicorn polly.main:app --reload\n\n# Activate the virtual environment manually (optional)\nsource .venv/bin/activate  # Linux/Mac\n# or\n.venv\\Scripts\\activate     # Windows\n```\n\n### Running in Development\n```bash\n# Install dependencies\nuv sync\n\n# Run with auto-reload\nuv run uvicorn polly.main:app --reload --host 0.0.0.0 --port 8000\n\n# Or run the main module directly\nuv run python -m polly.main\n```\n\n### Database Management\nThe SQLite database is automatically created and initialized on first run. No migrations needed for the MVP.\n\n### Adding Features\n1. Update database models in `polly/database.py`\n2. Add API endpoints in `polly/main.py`\n3. Update web interface in `templates/`\n4. Test with Discord bot commands\n\n### Development Workflow\n```bash\n# Start development server\nuv run uvicorn polly.main:app --reload\n\n# Run tests (when available)\nuv run pytest\n\n# Format code\nuv run black polly/\nuv run isort polly/\n\n# Type checking\nuv run mypy polly/\n```\n\n## Deployment\n\n### Docker Deployment (Recommended)\n\n1. **Clone and Configure**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd polly\n   cp .env.example .env\n   # Edit .env with your Discord bot credentials\n   ```\n\n2. **Build and Run with Docker Compose**\n   ```bash\n   docker-compose up -d\n   ```\n\n3. **Access the Application**\n   - Web interface: http://localhost:8000\n   - With nginx proxy: http://localhost (port 80)\n\nThe Docker setup includes:\n- Polly application container\n- Nginx reverse proxy (optional)\n- Automatic restarts\n- Health checks\n- Volume mounts for data persistence\n\n### Single Server Deployment\n1. **Setup Environment**\n   ```bash\n   # On your server\n   git clone \u003crepository-url\u003e\n   cd polly\n   uv sync\n   cp .env.example .env\n   # Configure .env with production values\n   ```\n\n2. **Create Systemd Service**\n   ```ini\n   # /etc/systemd/system/polly.service\n   [Unit]\n   Description=Polly Discord Poll Bot\n   After=network.target\n\n   [Service]\n   Type=simple\n   User=polly\n   WorkingDirectory=/path/to/polly\n   ExecStart=/path/to/polly/.venv/bin/python -m polly.main\n   Restart=always\n   RestartSec=10\n\n   [Install]\n   WantedBy=multi-user.target\n   ```\n\n3. **Start Service**\n   ```bash\n   sudo systemctl enable polly\n   sudo systemctl start polly\n   ```\n\n### Nginx Configuration (Optional)\n```nginx\nserver {\n    listen 80;\n    server_name your-domain.com;\n\n    location / {\n        proxy_pass http://localhost:8000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n    }\n\n    location /static/ {\n        alias /path/to/polly/static/;\n    }\n}\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support, please:\n1. Check the documentation\n2. Search existing issues\n3. Create a new issue with detailed information\n\n---\n\n**Built with ❤️ for the Discord community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacnpal%2Fpolly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpacnpal%2Fpolly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacnpal%2Fpolly/lists"}