A feature-rich Discord bot for Arizona RP community with economy system, moderation tools, forum integration, and much more.
| Project | Status | |
|---|---|---|
| Tech Stack |         |
|
| Meta |     |
- 📋 Table of Contents
- 🛠 Tech Stack
- 📦 Requirements
- 🚀 Installation
- ⚙️ Configuration
- 🗄️ Database Migrations
- 👨💻 Development
- 📁 Project Structure
- 📝 License
- Python 3.13
- discord.py: Discord API wrapper
- PostgreSQL 16: Database with asyncpg driver
- SQLAlchemy 2.0: Async ORM
- Alembic: Database migrations
- Pydantic: Settings management and validation
- Docker: Containerized deployment
- uv: Fast Python package installer
- Docker 20.10+
- Docker Compose 2.0+
- Python 3.13+
- PostgreSQL 16+
- UV package manager (or pip)
- Git
- Clone the repository
git clone https://github.com/nightcore-team/nightcore.git
cd nightcore- Create environment file
cp .env.example .env-
Configure environment variables (see Configuration)
-
Build and start containers
docker-compose up --buildThe bot will automatically:
- Build the Docker image
- Start PostgreSQL database
- Run database migrations
- Launch the bot
To run in detached mode:
docker-compose up -dTo stop the bot:
docker-compose down- Clone the repository
git clone https://github.com/nightcore-team/nightcore.git
cd nightcore- Install UV package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh- Create virtual environment and install dependencies
uv sync- Set up PostgreSQL database
# Create database
psql -U postgres
CREATE DATABASE database;
CREATE USER user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE database TO user;
\q- Create environment file
cp .env.example .env-
Configure environment variables (see Configuration)
-
Run database migrations
uv run alembic upgrade head- Start the bot
uv run python main.pyCreate a .env file in the root directory with the following variables:
# Discord Bot
BOT_TOKEN=discord_bot_token
# PostgreSQL Database
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_HOST=host # Use 'localhost' for local setup
POSTGRES_PORT=port
POSTGRES_DB=database
# Alternative: Use full database URI instead of individual fields
# POSTGRES_DATABASE_URI=postgresql+asyncpg://user:password@host:port/database
# Forum API Integration
FORUM_API_URL=https://forum.arzguard.com/api
FORUM_API_KEY=your_forum_api_key# Bot Configuration
EMBED_DESCRIPTION_LIMIT=4096
VIEW_V2_DESCRIPTION_LIMIT=3000
VIEW_V2_COMPONENTS_LIMIT=40
DELETE_MESSAGES_SECONDS=604800
VOTEBAN_ATTACHMENTS_LIMIT=7
CLOSED_TICKET_ALIVE_HOURS=48
ROLE_REQUESTS_ALIVE_HOURS=2
CASE_REWARDS_LIMIT=30
MAX_CUSTOM_REWARD_SIZE=100
BUG_REPORT_CHANNEL_ID=1442803332233171088
DISABLE_FORUM_TASK=false
# Developer User IDs (comma-separated)
DEVELOPER_IDS=1280700292530176131,566255833684508672,451359852418039808
# Database Connection Pool
POSTGRES_ECHO=false
POSTGRES_ECHO_POOL=true
POSTGRES_POOL_MAX_OVERFLOW=30
POSTGRES_POOL_SIZE=10
POSTGRES_POOL_TIMEOUT=0
POSTGRES_POOL_PRE_PING=true- Go to Discord Developer Portal
- Create a new application or select existing one
- Go to "Bot" section
- Click "Reset Token" and copy the token
- Enable required privileged intents:
- Presence Intent
- Server Members Intent
- Message Content Intent
The project uses Alembic for database migrations.
make migration
# or manually:
alembic revision --autogenerate -m "Your migration message"make migrate
# or manually:
alembic upgrade headalembic downgrade -1alembic historyThe project uses Ruff for linting and formatting:
# Check code
uv run ruff check .
# Format code
uv run ruff format .
# Fix auto-fixable issues
uv run ruff check --fix .Check pyproject.toml for
ruffconfiguration
For development, you can mount local files in Docker:
# Already configured in docker-compose.yml
volumes:
- ./src/:/app/src/
- ./main.py:/app/main.pyThis allows live code reloading without rebuilding the container.
nightcore/
├── src/
│ ├── __init__.py
│ ├── config/ # Global configuration
│ │ ├── config.py # Main config composition
│ │ └── env.py # Base environment settings
│ ├── infra/ # Infrastructure layer
│ │ ├── api/ # External APIs
│ │ │ ├── forum/ # NightForo API client
│ │ │ │ └── ...
│ │ └── db/ # Database layer
│ │ ├── config.py # Database configuration
│ │ ├── operations.py # Common DB operations
│ │ ├── session.py # Session management
│ │ ├── uow.py # Unit of Work pattern
│ │ ├── utils.py # Database utilities
│ │ └── models/ # SQLAlchemy models
│ ├── nightcore/ # Bot core
│ │ ├── bot.py # Bot class
│ │ ├── config.py # Bot configuration
│ │ ├── exceptions.py # Custom exceptions
│ │ ├── setup.py # Setup bot instance and modules to load
│ │ ├── components/ # Reusable global UI components
│ │ │ ├── __init__.py
│ │ │ ├── embed/ # embeds
│ │ │ └── v2/ # v2 (modals, views)
│ │ ├── events/ # Discord event handlers
│ │ │ ├── error.py # Error handling
│ │ │ ├── interaction.py # Interaction events
│ │ │ ├── channel/ # Channel events
│ │ │ ├── dto/ # Event DTOs
│ │ │ ├── member/ # Member events (join, leave, etc.)
│ │ │ ├── message/ # Message events
│ │ │ ├── reaction/ # Reaction events
│ │ │ ├── role/ # Role events
│ │ │ └── voice/ # Voice state events
│ │ ├── features/ # Feature modules
│ │ │ ├── clans/ # Clan management system
│ │ │ ├── compbuilder/ # Component builder
│ │ │ ├── config/ # Bot configuration commands
│ │ │ ├── economy/ # Economy & casino system
│ │ │ ├── faq/ # FAQ system
│ │ │ ├── forum/ # Forum integration
│ │ │ ├── meta/ # Meta commands (info, stats)
│ │ │ ├── moderation/ # Moderation tools
│ │ │ ├── private_rooms/ # Private voice rooms
│ │ │ ├── proposals/ # Community voting system
│ │ │ ├── role_requests/ # Role request system
│ │ │ ├── system/ # System commands
│ │ │ └── tickets/ # Support ticket system
│ │ ├── services/ # Business logic services
│ │ │ └── ...
│ │ ├── tasks/ # Background tasks
│ │ │ ├── ...
│ │ └── utils/ # Bot utilities
│ │ ├── __init__.py
│ │ ├── ...
│ │ ├── field_validators/ # Field validation utilities
│ │ ├── permissions/ # Permission helpers
│ │ └── transformers/ # Command transformers
│ └── utils/ # Shared utilities
│ └── logging/ # Logging configuration
│ ├── config.py # Logging config
│ └── setup.py # Logging setup
├── migrations/ # Alembic database migrations
│ ├── drop_structure.sql # Drop all triggers and functions
│ ├── env.py # Alembic environment
│ ├── README # Alembic readme
│ ├── script.py.mako # Migration template
│ ├── structure.sql # Full DB triggers and functions structure
│ └── versions/ # Migration versions
│ └── ...
├── docker/ # Docker configuration
│ ├── docker-entrypoint.sh # Container entrypoint script
├── main.py # Application entry point
├── pyproject.toml # Project metadata & dependencies # rules
├── docker-compose.yml # Docker orchestration
├── Dockerfile # Docker image definition
├── alembic.ini # Alembic configuration
├── Makefile # Common development commands (only migrations)
├── LICENSE # License file
└── README.md # This file
This project is licensed under the terms specified in the LICENSE file.