Update README.md
This commit is contained in:
630
README.md
630
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 <file_path>`
|
||||
2. Others in the room will see a file offer
|
||||
3. They can type `/accept <file_id>` 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 <file_path>`
|
||||
2. Others in the room will see a file offer
|
||||
3. They can type `/accept <file_id>` 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**
|
||||
|
||||
Reference in New Issue
Block a user