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