From 4f0f9d58c2f1849378dfae22094b414b48fae90d Mon Sep 17 00:00:00 2001 From: SpyDrone Date: Mon, 2 Mar 2026 10:54:15 -0500 Subject: [PATCH] Update README.md --- README.md | 630 +++++++++++++++++++++++++----------------------------- 1 file changed, 292 insertions(+), 338 deletions(-) diff --git a/README.md b/README.md index 6afd31c..eab56bc 100644 --- a/README.md +++ b/README.md @@ -1,338 +1,292 @@ -# 🚀 Advanced Chat Server & Client - -A feature-rich, production-ready chat server and client built with Python and WebSockets. Supports **both centralized server mode and peer-to-peer (P2P) LAN communication** with **file sharing capabilities**. Works on local development and hosted deployment (Ubuntu). - -## ✨ Features - -### Core Features -- ✅ **Unified Client**: Single client for both Server and P2P LAN modes -- ✅ **Peer-to-Peer (P2P)**: Chat without a server on your local network -- ✅ **File Sharing**: Send and receive files up to 50MB in both modes -- ✅ **Real-time Messaging**: Instant communication with low latency -- ✅ **Multiple Rooms**: Join different channels with password protection -- ✅ **User Authentication**: Secure identification for server-based chat -- ✅ **Admin System**: Comprehensive moderation tools -- ✅ **SSL/TLS Support**: Encrypted connections for server mode - -### Advanced Features -1. **Account & Registration** - - User registration with password hashing - - Secure authentication - - Nickname management - -2. **Room Management** - - Create public and private rooms - - Password-protected rooms - - Room topics and announcements - - User lists per room - -3. **Invite System** - - Generate time-limited invite codes - - Configurable max uses - - Invite tracking and revocation - -4. **Message Search** - - Full-text search across messages - - Filter by room, user, and date - - Search history - -5. **Message Replies** - - Thread-based conversations - - Quote original messages - - Reply tracking - -6. **User Blocks** - - Block/ignore users - - Temporary or permanent blocks - - Block list management - -7. **Command Aliases** - - Create custom command shortcuts - - Alias usage tracking - - Personal alias management - -8. **Room Announcements** - - Broadcast important messages - - Time-limited announcements - - Announcement history - -9. **Scheduled Messages** - - Schedule messages for future delivery - - Multiple time formats (HH:MM, +1h, +30m, +7d) - - Cancel scheduled messages - -10. **Room Bookmarks** - - Save favorite rooms/commands - - Quick access to bookmarks - - Usage statistics - -11. **Message Export** - - Export room history - - Export user messages - - Multiple export formats - -12. **Room Backups** - - Password-protected backups - - Full room state preservation - - Backup restoration - -13. **Notification Rules** - - Keyword notifications - - User-specific notifications - - @mention support - - Cooldown periods - -14. **Offline Messages** - - Queue messages for offline users - - Automatic delivery on reconnect - - Message expiration - -15. **Admin System** - - Admin privilege management - - Clear chat history - - User management - - System monitoring - -## 🛠️ Installation - -### Prerequisites -- Python 3.8 or higher -- pip (Python package manager) -- **Optional (for Advanced Features)**: - - `cryptography`: Required for End-to-End Encryption (E2EE) - - `Pillow`: Required for ASCII Image Art features - -### Windows (Local Development) - -1. Clone or download this repository -2. Run the setup script: - ```cmd - setup_windows.bat - ``` -3. Edit `.env` file with your configuration -4. Start the server: - ```cmd - venv\Scripts\activate - python server.py - ``` -5. In a new terminal, start the client: - ```cmd - venv\Scripts\activate - python client.py - ``` - -### Ubuntu (Production Deployment) - -1. Clone or download this repository -2. Make the deployment script executable: - ```bash - chmod +x deploy_ubuntu.sh - ``` -3. Run the deployment script: - ```bash - ./deploy_ubuntu.sh - ``` -4. Follow the prompts to configure systemd service and firewall -5. Edit `.env` file with your production configuration -6. If using systemd, the server will start automatically -7. Otherwise, start manually: - ```bash - source venv/bin/activate - python3 server.py - ``` - -### Manual Installation - -```bash -# Create virtual environment -python3 -m venv venv - -# Activate virtual environment -# On Windows: -venv\Scripts\activate -# On Linux/Mac: -source venv/bin/activate - -# Install dependencies -pip install -r requirements.txt - -# Copy environment template -cp .env.example .env - -# Edit .env with your configuration -# Start server -python server.py - -# In another terminal, start client -python client.py -``` - -## ⚙️ Configuration - -Edit the `.env` file to configure the server: - -```env -# Server Configuration -HOST=0.0.0.0 # Bind to all interfaces -PORT=8765 # WebSocket port -MAX_HISTORY=100 # Messages to keep in history - -# Admin Configuration -ADMIN_PASSWORD=admin123 # Change this! - -# SSL Configuration (optional) -USE_SSL=false -SSL_CERT_PATH=/path/to/cert.pem -SSL_KEY_PATH=/path/to/key.pem - -# Database -DB_PATH=chat.db - -# Logging -LOG_LEVEL=INFO -LOG_FILE=chat_server.log - -# Security -MAX_MESSAGE_LENGTH=4096 -MAX_NICKNAME_LENGTH=32 -RATE_LIMIT_MESSAGES=120 -RATE_LIMIT_WINDOW=60 - -# Session -SESSION_TIMEOUT=3600 -KEEPALIVE_INTERVAL=30 -RECONNECT_TIMEOUT=300 - -# Backups -BACKUP_DIR=./backups -AUTO_BACKUP_ENABLED=false -AUTO_BACKUP_INTERVAL=86400 -``` - -## 🎮 Usage - -### Server - -Start the server with default settings: -```bash -python server.py -``` - -Or with custom options: -```bash -python server.py --host 0.0.0.0 --port 8765 --admin-pass mypassword -``` - -### Client - -Start the unified client: -```bash -python client.py -``` - -The client will prompt you to choose a mode: -1. **Central Server Mode**: Connect to a central server (ws://...) -2. **P2P LAN Mode**: Connect directly to peers on your local network - -In **P2P Mode**, it will also ask for a port (80, 443, or custom) and automatically discover others in the same room on your LAN. - -### File Sharing - -To share a file: -1. Type `/send ` -2. Others in the room will see a file offer -3. They can type `/accept ` to download - -Files are saved to the `./downloads` folder by default. - -### Commands - -Type `/help` in the client to see all available commands. - -## 🔒 Security Features - -- **Password Hashing**: PBKDF2-HMAC-SHA256 with salt -- **SSL/TLS Support**: Encrypted connections -- **Rate Limiting**: Prevent spam and abuse (120 msg / 60s) -- **Input Validation**: Sanitize all user inputs -- **Session Management**: Automatic timeout and cleanup -- **Admin Controls**: Privilege-based access control - -## 🌐 Deployment - -### Local Network - -1. Start server on your machine -2. Find your local IP address -3. Clients connect to: `ws://YOUR_LOCAL_IP:8765` - -### Public Internet (Ubuntu Server) - -1. Use the deployment script: `./deploy_ubuntu.sh` -2. Configure firewall to allow port 8765 -3. Clients connect to: `wss://yourdomain.com:8765` - -## 📊 Monitoring - -### Systemd Service (Ubuntu) -- `sudo systemctl status chatserver` -- `sudo journalctl -u chatserver -f` - -### Log Files -- `tail -f chat_server.log` - -## 🗄️ Database - -The server uses SQLite for persistence (`chat.db`). - -## 🐛 Troubleshooting - -### Connection Issues -1. **Cannot connect to server**: Check if server is running and firewall status. -2. **SSL/TLS errors**: Verify certificate paths in `.env`. -3. **Database errors**: Check disk space and permissions. - -## 📝 Development - -### Project Structure - -``` -radio/ -├── server.py # Main server application -├── client.py # Unified client (Server & P2P Mode) -├── config.py # Configuration management -├── requirements.txt # Python dependencies -├── .env.example # Environment template -├── .env # Your configuration -├── setup_windows.bat # Windows setup script -├── deploy_ubuntu.sh # Ubuntu deployment script -├── README.md # Main documentation -├── docs/ # Detailed documentation files -├── chat.db # SQLite database -├── backups/ # Room backups directory -└── logs/ # Log files directory -``` - -### Documentation Index - -For more detailed information, please refer to the files in the `docs/` folder: - -- **QUICKSTART.md**: Step-by-step guide for beginners -- **P2P_GUIDE.md**: In-depth guide for P2P and LAN communication -- **P2P_FEATURES.md**: Technical details of the P2P engine -- **IMPROVEMENTS.md**: Summary of latest optimizations and features -- **QUICK_REFERENCE.md**: Most common commands and tips -- **CHANGELOG.md**: Version history and future plans -- **FINAL_SUMMARY.md**: Overview of the unified chat system architecture - -### Contributing - -Contributions are welcome! Please fork the repository, create a feature branch, and submit a pull request. - -## 📜 License - -This project is open source and available under the MIT License. - ---- - -**Made with ❤️ for the chat community** +# 🚀 Advanced Chat Server & Client + +A feature-rich, production-ready chat server and client built with Python and WebSockets. Supports **both centralized server mode and peer-to-peer (P2P) LAN communication** with **file sharing capabilities**. Works on local development and hosted deployment (Ubuntu). + +## ✨ Features + +### Core Features +- ✅ **Unified Client**: Single client for both Server and P2P LAN modes +- ✅ **Peer-to-Peer (P2P)**: Chat without a server on your local network +- ✅ **File Sharing**: Send and receive files up to 50MB in both modes +- ✅ **Real-time Messaging**: Instant communication with low latency +- ✅ **Multiple Rooms**: Join different channels with password protection +- ✅ **User Authentication**: Secure identification for server-based chat +- ✅ **Admin System**: Comprehensive moderation tools +- ✅ **SSL/TLS Support**: Encrypted connections for server mode + +### Advanced Features +1. **Account & Registration** + - User registration with password hashing + - Secure authentication + - Nickname management + +2. **Room Management** + - Create public and private rooms + - Password-protected rooms + - Room topics and announcements + - User lists per room + +3. **Invite System** + - Generate time-limited invite codes + - Configurable max uses + - Invite tracking and revocation + +4. **Message Search** + - Full-text search across messages + - Filter by room, user, and date + - Search history + +5. **Message Replies** + - Thread-based conversations + - Quote original messages + - Reply tracking + +6. **User Blocks** + - Block/ignore users + - Temporary or permanent blocks + - Block list management + +7. **Command Aliases** + - Create custom command shortcuts + - Alias usage tracking + - Personal alias management + +8. **Room Announcements** + - Broadcast important messages + - Time-limited announcements + - Announcement history + +9. **Scheduled Messages** + - Schedule messages for future delivery + - Multiple time formats (HH:MM, +1h, +30m, +7d) + - Cancel scheduled messages + +10. **Room Bookmarks** + - Save favorite rooms/commands + - Quick access to bookmarks + - Usage statistics + +11. **Message Export** + - Export room history + - Export user messages + - Multiple export formats + +12. **Room Backups** + - Password-protected backups + - Full room state preservation + - Backup restoration + +13. **Notification Rules** + - Keyword notifications + - User-specific notifications + - @mention support + - Cooldown periods + +14. **Offline Messages** + - Queue messages for offline users + - Automatic delivery on reconnect + - Message expiration + +15. **Admin System** + - Admin privilege management + - Clear chat history + - User management + - System monitoring + +## 🛠️ Installation + +### Prerequisites +- Python 3.8 or higher +- pip (Python package manager) +- **Optional (for Advanced Features)**: + - `cryptography`: Required for End-to-End Encryption (E2EE) + - `Pillow`: Required for ASCII Image Art features + - `prompt-toolkit` + +### Windows (Local Development) + +1. Clone or download this repository +2. Run the setup script: + ```cmd + setup_windows.bat + ``` +3. Edit `.env` file with your configuration +4. Start the server: + ```cmd + python server.py + ``` +5. In a new terminal, start the client: + ```cmd + python client.py + ``` + +### Manual Installation + +```bash +# Install dependencies +pip install -r requirements.txt + +# Copy environment template +cp .env.example .env + +# Edit .env with your configuration +# Start server +python server.py + +# In another terminal, start client +python client.py +``` + +## ⚙️ Configuration + +Edit the `.env` file to configure the server: + +```env +# Server Configuration +HOST=0.0.0.0 # Bind to all interfaces +PORT=8765 # WebSocket port +MAX_HISTORY=100 # Messages to keep in history + +# Admin Configuration +ADMIN_PASSWORD=admin123 # Change this! + +# SSL Configuration (optional) +USE_SSL=false +SSL_CERT_PATH=/path/to/cert.pem +SSL_KEY_PATH=/path/to/key.pem + +# Database +DB_PATH=chat.db + +# Logging +LOG_LEVEL=INFO +LOG_FILE=chat_server.log + +# Security +MAX_MESSAGE_LENGTH=4096 +MAX_NICKNAME_LENGTH=32 +RATE_LIMIT_MESSAGES=120 +RATE_LIMIT_WINDOW=60 + +# Session +SESSION_TIMEOUT=3600 +KEEPALIVE_INTERVAL=30 +RECONNECT_TIMEOUT=300 + +# Backups +BACKUP_DIR=./backups +AUTO_BACKUP_ENABLED=false +AUTO_BACKUP_INTERVAL=86400 +``` + +## 🎮 Usage + +### Server + +Start the server with default settings: +```bash +python server.py +``` + +Or with custom options: +```bash +python server.py --host 0.0.0.0 --port 8765 --admin-pass mypassword +``` + +### Client + +Start the unified client: +```bash +python client.py +``` + +The client will prompt you to choose a server: +1. On default it will say wss://server.wholeworldcoding.com/radio +2. If you are running the server locally please type: ws:/localhost:8765 + +### File Sharing + +To share a file: +1. Type `/send ` +2. Others in the room will see a file offer +3. They can type `/accept ` to download + +Files are saved to the `./downloads` folder by default. + +### Commands + +Type `/help` in the client to see all available commands. + +## 🔒 Security Features + +- **Password Hashing**: PBKDF2-HMAC-SHA256 with salt +- **SSL/TLS Support**: Encrypted connections +- **Rate Limiting**: Prevent spam and abuse (120 msg / 60s) +- **Input Validation**: Sanitize all user inputs +- **Session Management**: Automatic timeout and cleanup +- **Admin Controls**: Privilege-based access control + +## 🌐 Deployment + +### Local Network + +1. Start server on your machine +2. Find your local IP address +3. Clients connect to: `ws://YOUR_LOCAL_IP:8765` + +### Public Internet (Ubuntu Server) + +1. Deploy the server +2. Configure firewall to allow port 8765 +3. Clients connect to: `wss://yourdomain.com:8765` + +## 📊 Monitoring + +### Systemd Service (Ubuntu) +- `sudo systemctl status chatserver` +- `sudo journalctl -u chatserver -f` + +### Log Files +- `tail -f chat_server.log` + +## 🗄️ Database + +The server uses SQLite for persistence (`chat.db`). + +## 🐛 Troubleshooting + +### Connection Issues +1. **Cannot connect to server**: Check if server is running and firewall status. +2. **SSL/TLS errors**: Verify certificate paths in `.env`. +3. **Database errors**: Check disk space and permissions. + +## 📝 Development + +### Project Structure + +``` +radio/ +├── server.py # Main server application +├── client.py # Unified client (Server & P2P Mode) +├── config.py # Configuration management +├── requirements.txt # Python dependencies +├── .env.example # Environment template +├── .env # Your configuration +├── setup_windows.bat # Windows setup script +├── README.md # Main documentation +├── docs/ # Detailed documentation files +├── chat.db # SQLite database +└── logs/ # Log files directory +``` + +### Contributing + +Contributions are welcome! Please fork the repository, create a feature branch, and submit a pull request. + +## 📜 License + +This project is open source and available under the MIT License. + +--- + +**Made with ❤️ for the chat community**