# EPT-MX-ADM v1.0.0
[](https://badge.fury.io/py/ept-mx-adm)
[](https://pypi.org/project/ept-mx-adm/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/ept-mx-adm)
```
_____ ____ _____ __ ____ __ _ ____ __ __
| ____| _ \_ _| | \/ \ \ / / / \ | _ \| \/ |
| _| | |_) || |_____| |\/ |\ \ /____/ _ \ | | | | |\/| |
| |___| __/ | |_____| | | |/ / \___/ ___ \| |_| | | | |
|_____|_| |_| |__| |_/_/\_\ /_/ \_\____/|_| |_|
```
**Web-Based Administration Panel for Matrix Synapse Server**
Universal admin tool that works with ANY Matrix server - local, remote, cloud, or self-hosted. Just admin credentials needed.
---
## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running the Application](#running-the-application)
- [Usage](#usage)
- [Localization](#localization)
- [Production Deployment](#production-deployment)
- [Troubleshooting](#troubleshooting)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
---
## Features
### Universal Compatibility
- Works with ANY Matrix server (local, remote, cloud, self-hosted)
- Supports self-signed SSL certificates
- No complex configuration needed
- Multi-server support in one installation
### Dashboard
- Real-time server statistics
- User analytics (active, deactivated, total)
- Room statistics and analytics
- Media storage monitoring
- API health status
- Synapse version information
- Python version display
### User Management
- View all users with pagination
- Create new users
- Edit user profiles and settings
- Deactivate/reactivate users
- Reset user passwords
- View user devices and sessions
- Media storage per user
- Filter by guests and deactivated users
- CSV export/import
- Advanced search functionality
### Room Management
- List all rooms with detailed information
- View room details and statistics
- Edit room settings
- Delete rooms
- Unblock rooms
- Assign room administrators
- Column visibility toggles
- Advanced filtering and search
- CSV export
- Pagination with customizable rows per page
### Space Management
- List all Matrix spaces
- View space hierarchies
- Manage space settings
- Consistent pagination
- Modern card-based UI
### Media Management
- Overall media statistics dashboard
- Users with media list
- Detailed user media files view
- File type filtering (Images, Videos, Audio, Documents, Other)
- Quarantine system for suspicious files
- Media file deletion
- CSV export
- Human-readable file sizes
- Status filtering (Normal, Quarantined)
### Authentication & Security
- Simplified login form
- Server auto-detection
- Username auto-formatting
- Real Matrix admin rights verification
- Session management
- SSL certificate support
- Secure API integration
### Localization
- Multi-language support: English, Russian, German, French, Italian, Spanish, Turkish
- Easy language switching
- Full interface translation
- RTL support ready
### Modern UI/UX
- Responsive design for all devices
- Dark/Light theme toggle
- Bootstrap 5 framework
- Bootstrap Icons
- Chart.js for analytics
- Smooth animations
- Modal dialogs
- Toast notifications
---
## Requirements
### System Requirements
- **Python**: 3.8 or higher
- **pip**: Latest version recommended
- **Operating System**: Linux, macOS, or Windows
### Matrix Server Requirements
- **Matrix Synapse**: Any version with Admin API enabled
- **Admin Account**: User with admin privileges on the Matrix server
- **Network Access**: HTTP/HTTPS access to Matrix server
### Python Dependencies
All dependencies are listed in `requirements.txt`:
- Flask >= 2.3.0
- requests >= 2.31.0
- Jinja2 >= 3.1.0
- MarkupSafe >= 2.1.0
- werkzeug >= 2.3.0
---
## Installation
### Quick Start (PyPI - Recommended)
```bash
# Install from PyPI
pip install ept-mx-adm
# Download static assets
cd $(pip show ept-mx-adm | grep Location | cut -d' ' -f2)/ept-mx-adm
chmod +x install_assets.sh
./install_assets.sh
# Run the application
python -m ept-mx-adm
# or
ept-mx-adm
```
### Installation from Source
#### Option 1: Simple Installation
```bash
# Clone the repository
git clone https://github.com/EPTLLC/EPT-MX-ADM.git
cd EPT-MX-ADM
# Install dependencies
pip install -r requirements.txt
# Download static assets
chmod +x install_assets.sh
./install_assets.sh
# Run the application
python app.py
```
#### Option 2: Using Helper Script
```bash
# Clone the repository
git clone https://github.com/EPTLLC/EPT-MX-ADM.git
cd EPT-MX-ADM
# Make script executable
chmod +x run.sh
# Run (auto-installs dependencies and starts app)
./run.sh
```
#### Option 3: With Virtual Environment
```bash
# Clone the repository
git clone https://github.com/EPTLLC/EPT-MX-ADM.git
cd EPT-MX-ADM
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate
# Upgrade pip
pip install --upgrade pip
# Install dependencies
pip install -r requirements.txt
# Download static assets
chmod +x install_assets.sh
./install_assets.sh
# Run the application
python app.py
```
#### Option 4: With pipx (Isolated)
```bash
# Install pipx if not already installed
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Clone and setup
git clone https://github.com/EPTLLC/EPT-MX-ADM.git
cd EPT-MX-ADM
# Install dependencies (pipx manages isolation)
pip install -r requirements.txt
# Download static assets
chmod +x install_assets.sh
./install_assets.sh
# Run
python app.py
```
---
## Configuration
### config.json
The main configuration file is `config.json` in the project root.
**Default Configuration:**
```json
{
"matrix_server": "https://matrix.example.com",
"app": {
"host": "127.0.0.1",
"port": 5000,
"debug": true
},
"session": {
"secret_key": "your-secret-key-here-change-this"
}
}
```
**Configuration Options:**
| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `matrix_server` | Your Matrix Synapse server URL (can be changed at login) | `https://matrix.example.com` | No |
| `app.host` | Application host | `127.0.0.1` | Yes |
| `app.port` | Application port | `5000` | Yes |
| `app.debug` | Debug mode (disable in production) | `true` | Yes |
| `session.secret_key` | Flask session secret key (change in production) | Generated | Yes |
### Important Notes
1. **Matrix Server**: The `matrix_server` in config.json is optional - you can specify any server at login
2. **Secret Key**: Change `session.secret_key` in production to a random string
3. **Debug Mode**: Set `app.debug` to `false` in production
4. **SSL Certificates**: Self-signed certificates are automatically supported
---
## Running the Application
### Development Mode
```bash
# Activate virtual environment if using one
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the application
python app.py
```
The application will start on `http://127.0.0.1:5000` (or the host/port specified in config.json).
### Production Mode (Gunicorn)
```bash
# Activate virtual environment if using one
source venv/bin/activate
# Run with Gunicorn
gunicorn -c gunicorn.conf.py app:app
```
### Systemd Service (Linux)
Create `/etc/systemd/system/ept-mx-adm.service`:
```ini
[Unit]
Description=EPT-MX-ADM Matrix Admin Panel
After=network.target
[Service]
Type=notify
User=your-user
Group=your-group
WorkingDirectory=/path/to/EPT-MX-ADM
Environment="PATH=/path/to/EPT-MX-ADM/venv/bin"
ExecStart=/path/to/EPT-MX-ADM/venv/bin/gunicorn -c gunicorn.conf.py app:app
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable ept-mx-adm
sudo systemctl start ept-mx-adm
sudo systemctl status ept-mx-adm
```
---
## Usage
### First Login
1. Open your browser and navigate to `http://localhost:5000` (or your configured host:port)
2. **Login Form:**
- **Matrix Server**: Enter your server domain (e.g., `matrix.example.com` or `localhost`)
- No need for `https://` - it's added automatically
- Works with local servers, remote servers, and self-signed certificates
- **Username**: Enter your admin username (e.g., `admin`)
- No need for `@` or domain - it's formatted automatically
- **Password**: Enter your Matrix admin password
3. Click "Login"
The application will:
- Automatically format the server URL (add `https://` if needed)
- Automatically format the username into Matrix ID (add `@` and domain)
- Verify admin privileges via Matrix API
- Create a session for your admin user
### Managing Users
**View Users:**
- Navigate to "Users" tab
- See all users with pagination
- Filter by guests and deactivated users
- View media storage per user
**Create User:**
- Click "Create User" button
- Fill in username, password, and optional display name
- Choose if user should be admin
- Click "Create"
**Edit User:**
- Click on user card dropdown menu
- Select "Edit"
- Modify user settings
- Save changes
**Deactivate User:**
- Click on user dropdown menu
- Select "Deactivate"
- Confirm action
### Managing Rooms
**View Rooms:**
- Navigate to "Rooms" tab
- See all rooms with statistics
- Toggle column visibility
- Use search to find specific rooms
**View Room Details:**
- Click "View" button on room card
- See detailed information in modal
- View members, settings, and statistics
**Edit Room:**
- Click dropdown menu on room card
- Select "Edit"
- Modify room settings
- Save changes
**Delete Room:**
- Click dropdown menu
- Select "Delete"
- Confirm action (room will be permanently deleted)
### Managing Media
**View Media Statistics:**
- Navigate to "Media" tab
- See overall statistics dashboard
- View total files, storage, and users with media
**View User Media:**
- Click on user in media list
- See all media files for that user
- Filter by file type (Images, Videos, Audio, Documents, Other)
- Filter by status (Normal, Quarantined)
**Quarantine Media:**
- In user media view, click dropdown on file
- Select "Quarantine"
- File will be marked as quarantined
**Delete Media:**
- Click dropdown on file
- Select "Delete"
- Confirm action
### Managing Spaces
**View Spaces:**
- Navigate to "Spaces" tab
- See all Matrix spaces
- View space hierarchies
- Manage space settings
---
## Localization
EPT-MX-ADM supports multiple languages out of the box.
### Available Languages
- English (en)
- Russian (ru)
- German (de)
- French (fr)
- Italian (it)
- Spanish (es)
- Turkish (tr)
### Changing Language
**In Application:**
1. Click on language selector in top navigation
2. Choose your preferred language
3. Interface will update immediately
4. Language preference is saved in session
**Adding New Language:**
1. Copy `locales/en/messages.json` to `locales/[language_code]/messages.json`
2. Translate all strings in the new file
3. Language will be automatically detected and available
---
## Production Deployment
### Security Checklist
- [ ] Change `session.secret_key` in config.json to a random string
- [ ] Set `app.debug` to `false` in config.json
- [ ] Use strong passwords for admin accounts
- [ ] Enable HTTPS (use nginx or Apache as reverse proxy)
- [ ] Restrict access to the application (firewall, VPN)
- [ ] Keep Python and dependencies up to date
- [ ] Regular backups of config.json
- [ ] Monitor logs for suspicious activity
### Nginx Configuration Example
```nginx
server {
listen 80;
server_name admin.yourdomain.com;
# Redirect to HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name admin.yourdomain.com;
# SSL certificates
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### Apache Configuration Example
```apache
<VirtualHost *:80>
ServerName admin.yourdomain.com
Redirect permanent / https://admin.yourdomain.com/
</VirtualHost>
<VirtualHost *:443>
ServerName admin.yourdomain.com
SSLEngine on
SSLCertificateFile /path/to/cert.pem
SSLCertificateKeyFile /path/to/key.pem
ProxyPass / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5000/
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>
```
---
## Troubleshooting
### Common Issues
#### "Connection refused" or "Cannot connect to Matrix server"
**Solution:**
- Verify Matrix server URL is correct
- Check if Matrix server is running
- Ensure network connectivity
- For local servers, try `localhost` or `127.0.0.1`
- Check firewall rules
#### "SSL: CERTIFICATE_VERIFY_FAILED" error
**Solution:**
- EPT-MX-ADM automatically handles self-signed certificates
- If error persists, verify server URL starts with `https://`
- Check if Matrix server certificate is properly configured
#### "Invalid credentials" or "Not an admin"
**Solution:**
- Verify username and password are correct
- Ensure user has admin privileges on Matrix server
- Check if user is deactivated
- Try logging in via Matrix client first to verify credentials
#### Login form only shows username/password (no server field)
**Solution:**
- This is normal - server field is optional
- Enter server domain at login or use default from config.json
- Server field will be shown after first failed attempt
#### Dashboard shows "N/A" or "0" for statistics
**Solution:**
- Verify admin API is enabled on Matrix server
- Check if user has proper admin rights
- Wait a few seconds for data to load
- Check browser console for errors
- Verify Matrix server API endpoints are accessible
#### Pagination not working (users/rooms/spaces)
**Solution:**
- Clear browser cache and reload
- Check browser console for JavaScript errors
- Verify API responses in Network tab
- Ensure using latest version of EPT-MX-ADM
#### Media page shows "Error loading media data"
**Solution:**
- Verify `/v1/statistics/users/media` endpoint is available on Matrix server
- Check if user has admin rights
- Clear browser cache
- Check server logs for errors
---
## Security
### Best Practices
1. **Passwords**: Use strong, unique passwords for admin accounts
2. **Session Secret**: Change `session.secret_key` to a random string
3. **Debug Mode**: Disable debug mode in production
4. **HTTPS**: Always use HTTPS in production (via reverse proxy)
5. **Access Control**: Restrict access to the application via firewall or VPN
6. **Updates**: Keep Python, Flask, and all dependencies up to date
7. **Logs**: Monitor application and server logs regularly
8. **Backups**: Regular backups of configuration and data
### SSL/TLS Support
EPT-MX-ADM automatically:
- Supports self-signed SSL certificates
- Disables SSL verification for local/development servers
- Adds `https://` to server URLs if not present
- Suppresses SSL warnings in logs
For production, always use valid SSL certificates via reverse proxy.
---
## Contributing
We welcome contributions to EPT-MX-ADM!
### How to Contribute
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request
### Development Guidelines
- Follow PEP 8 style guide for Python code
- Add comments and docstrings
- Update documentation for new features
- Test your changes thoroughly
- Update CHANGELOG.md
### Reporting Issues
Found a bug or have a feature request?
1. Check if issue already exists
2. Create new issue with detailed description
3. Include steps to reproduce (for bugs)
4. Provide environment details (OS, Python version, Matrix Synapse version)
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
MIT License allows you to:
- Use the software for any purpose
- Modify the source code
- Distribute copies
- Include in proprietary software
With the following conditions:
- Include the original license and copyright notice
- Provide attribution to original authors
---
## Support
### Getting Help
- **Documentation**: [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md)
- **Issues**: [GitHub Issues](https://github.com/EPTLLC/EPT-MX-ADM/issues)
- **Telegram**: [@EasyProTech](https://t.me/EasyProTech)
- **Email**: Contact via GitHub profile
### Commercial Support
For commercial support, custom development, or consulting services, contact EasyProTech LLC via:
- Website: [www.easypro.tech](https://www.easypro.tech)
- Telegram: [@EasyProTech](https://t.me/EasyProTech)
---
## Project Information
- **Project Name**: EPT-MX-ADM
- **Version**: 1.0.0
- **Status**: Production Ready
- **PyPI**: [pypi.org/project/ept-mx-adm](https://pypi.org/project/ept-mx-adm/)
- **Company**: EasyProTech LLC
- **Website**: [www.easypro.tech](https://www.easypro.tech)
- **Developer**: Brabus
- **Repository**: [github.com/EPTLLC/EPT-MX-ADM](https://github.com/EPTLLC/EPT-MX-ADM)
- **License**: MIT
- **Python**: 3.8+
- **Supported Languages**: EN, RU, DE, FR, IT, ES, TR
---
## Acknowledgments
- **Matrix Foundation** for the Matrix protocol
- **Synapse Team** for the Matrix Synapse server
- **Flask Team** for the amazing web framework
- **Bootstrap Team** for the UI framework
- **Chart.js Team** for visualization library
- **Community Contributors** for feedback and contributions
---
## Changelog
For detailed history of changes, see [CHANGELOG.md](CHANGELOG.md).
---
**Created with care by EasyProTech LLC**
Visit us: [www.easypro.tech](https://www.easypro.tech) | Telegram: [@EasyProTech](https://t.me/EasyProTech)
Raw data
{
"_id": null,
"home_page": "https://github.com/EPTLLC/EPT-MX-ADM",
"name": "ept-mx-adm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "matrix, synapse, admin, administration, panel, web, flask, matrix-synapse, admin-panel, chat, communication, server-management, user-management, room-management",
"author": "Brabus (EasyProTech LLC)",
"author_email": "support@easypro.tech",
"download_url": "https://files.pythonhosted.org/packages/a2/77/d9b3b0ea7c257bfb2abc0ae13240ab3c3101108d33f262cae8f7cd768a38/ept_mx_adm-1.0.0.tar.gz",
"platform": null,
"description": "# EPT-MX-ADM v1.0.0\n\n[](https://badge.fury.io/py/ept-mx-adm)\n[](https://pypi.org/project/ept-mx-adm/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/ept-mx-adm)\n\n```\n _____ ____ _____ __ ____ __ _ ____ __ __ \n | ____| _ \\_ _| | \\/ \\ \\ / / / \\ | _ \\| \\/ |\n | _| | |_) || |_____| |\\/ |\\ \\ /____/ _ \\ | | | | |\\/| |\n | |___| __/ | |_____| | | |/ / \\___/ ___ \\| |_| | | | |\n |_____|_| |_| |__| |_/_/\\_\\ /_/ \\_\\____/|_| |_|\n```\n\n**Web-Based Administration Panel for Matrix Synapse Server**\n\nUniversal admin tool that works with ANY Matrix server - local, remote, cloud, or self-hosted. Just admin credentials needed.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Running the Application](#running-the-application)\n- [Usage](#usage)\n- [Localization](#localization)\n- [Production Deployment](#production-deployment)\n- [Troubleshooting](#troubleshooting)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n---\n\n## Features\n\n### Universal Compatibility\n- Works with ANY Matrix server (local, remote, cloud, self-hosted)\n- Supports self-signed SSL certificates\n- No complex configuration needed\n- Multi-server support in one installation\n\n### Dashboard\n- Real-time server statistics\n- User analytics (active, deactivated, total)\n- Room statistics and analytics\n- Media storage monitoring\n- API health status\n- Synapse version information\n- Python version display\n\n### User Management\n- View all users with pagination\n- Create new users\n- Edit user profiles and settings\n- Deactivate/reactivate users\n- Reset user passwords\n- View user devices and sessions\n- Media storage per user\n- Filter by guests and deactivated users\n- CSV export/import\n- Advanced search functionality\n\n### Room Management\n- List all rooms with detailed information\n- View room details and statistics\n- Edit room settings\n- Delete rooms\n- Unblock rooms\n- Assign room administrators\n- Column visibility toggles\n- Advanced filtering and search\n- CSV export\n- Pagination with customizable rows per page\n\n### Space Management\n- List all Matrix spaces\n- View space hierarchies\n- Manage space settings\n- Consistent pagination\n- Modern card-based UI\n\n### Media Management\n- Overall media statistics dashboard\n- Users with media list\n- Detailed user media files view\n- File type filtering (Images, Videos, Audio, Documents, Other)\n- Quarantine system for suspicious files\n- Media file deletion\n- CSV export\n- Human-readable file sizes\n- Status filtering (Normal, Quarantined)\n\n### Authentication & Security\n- Simplified login form\n- Server auto-detection\n- Username auto-formatting\n- Real Matrix admin rights verification\n- Session management\n- SSL certificate support\n- Secure API integration\n\n### Localization\n- Multi-language support: English, Russian, German, French, Italian, Spanish, Turkish\n- Easy language switching\n- Full interface translation\n- RTL support ready\n\n### Modern UI/UX\n- Responsive design for all devices\n- Dark/Light theme toggle\n- Bootstrap 5 framework\n- Bootstrap Icons\n- Chart.js for analytics\n- Smooth animations\n- Modal dialogs\n- Toast notifications\n\n---\n\n## Requirements\n\n### System Requirements\n- **Python**: 3.8 or higher\n- **pip**: Latest version recommended\n- **Operating System**: Linux, macOS, or Windows\n\n### Matrix Server Requirements\n- **Matrix Synapse**: Any version with Admin API enabled\n- **Admin Account**: User with admin privileges on the Matrix server\n- **Network Access**: HTTP/HTTPS access to Matrix server\n\n### Python Dependencies\nAll dependencies are listed in `requirements.txt`:\n- Flask >= 2.3.0\n- requests >= 2.31.0\n- Jinja2 >= 3.1.0\n- MarkupSafe >= 2.1.0\n- werkzeug >= 2.3.0\n\n---\n\n## Installation\n\n### Quick Start (PyPI - Recommended)\n\n```bash\n# Install from PyPI\npip install ept-mx-adm\n\n# Download static assets\ncd $(pip show ept-mx-adm | grep Location | cut -d' ' -f2)/ept-mx-adm\nchmod +x install_assets.sh\n./install_assets.sh\n\n# Run the application\npython -m ept-mx-adm\n# or\nept-mx-adm\n```\n\n### Installation from Source\n\n#### Option 1: Simple Installation\n```bash\n# Clone the repository\ngit clone https://github.com/EPTLLC/EPT-MX-ADM.git\ncd EPT-MX-ADM\n\n# Install dependencies\npip install -r requirements.txt\n\n# Download static assets\nchmod +x install_assets.sh\n./install_assets.sh\n\n# Run the application\npython app.py\n```\n\n#### Option 2: Using Helper Script\n```bash\n# Clone the repository\ngit clone https://github.com/EPTLLC/EPT-MX-ADM.git\ncd EPT-MX-ADM\n\n# Make script executable\nchmod +x run.sh\n\n# Run (auto-installs dependencies and starts app)\n./run.sh\n```\n\n#### Option 3: With Virtual Environment\n```bash\n# Clone the repository\ngit clone https://github.com/EPTLLC/EPT-MX-ADM.git\ncd EPT-MX-ADM\n\n# Create virtual environment\npython3 -m venv venv\n\n# Activate virtual environment\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Upgrade pip\npip install --upgrade pip\n\n# Install dependencies\npip install -r requirements.txt\n\n# Download static assets\nchmod +x install_assets.sh\n./install_assets.sh\n\n# Run the application\npython app.py\n```\n\n#### Option 4: With pipx (Isolated)\n```bash\n# Install pipx if not already installed\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# Clone and setup\ngit clone https://github.com/EPTLLC/EPT-MX-ADM.git\ncd EPT-MX-ADM\n\n# Install dependencies (pipx manages isolation)\npip install -r requirements.txt\n\n# Download static assets\nchmod +x install_assets.sh\n./install_assets.sh\n\n# Run\npython app.py\n```\n\n---\n\n## Configuration\n\n### config.json\n\nThe main configuration file is `config.json` in the project root.\n\n**Default Configuration:**\n```json\n{\n \"matrix_server\": \"https://matrix.example.com\",\n \"app\": {\n \"host\": \"127.0.0.1\",\n \"port\": 5000,\n \"debug\": true\n },\n \"session\": {\n \"secret_key\": \"your-secret-key-here-change-this\"\n }\n}\n```\n\n**Configuration Options:**\n\n| Parameter | Description | Default | Required |\n|-----------|-------------|---------|----------|\n| `matrix_server` | Your Matrix Synapse server URL (can be changed at login) | `https://matrix.example.com` | No |\n| `app.host` | Application host | `127.0.0.1` | Yes |\n| `app.port` | Application port | `5000` | Yes |\n| `app.debug` | Debug mode (disable in production) | `true` | Yes |\n| `session.secret_key` | Flask session secret key (change in production) | Generated | Yes |\n\n### Important Notes\n\n1. **Matrix Server**: The `matrix_server` in config.json is optional - you can specify any server at login\n2. **Secret Key**: Change `session.secret_key` in production to a random string\n3. **Debug Mode**: Set `app.debug` to `false` in production\n4. **SSL Certificates**: Self-signed certificates are automatically supported\n\n---\n\n## Running the Application\n\n### Development Mode\n\n```bash\n# Activate virtual environment if using one\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Run the application\npython app.py\n```\n\nThe application will start on `http://127.0.0.1:5000` (or the host/port specified in config.json).\n\n### Production Mode (Gunicorn)\n\n```bash\n# Activate virtual environment if using one\nsource venv/bin/activate\n\n# Run with Gunicorn\ngunicorn -c gunicorn.conf.py app:app\n```\n\n### Systemd Service (Linux)\n\nCreate `/etc/systemd/system/ept-mx-adm.service`:\n\n```ini\n[Unit]\nDescription=EPT-MX-ADM Matrix Admin Panel\nAfter=network.target\n\n[Service]\nType=notify\nUser=your-user\nGroup=your-group\nWorkingDirectory=/path/to/EPT-MX-ADM\nEnvironment=\"PATH=/path/to/EPT-MX-ADM/venv/bin\"\nExecStart=/path/to/EPT-MX-ADM/venv/bin/gunicorn -c gunicorn.conf.py app:app\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable ept-mx-adm\nsudo systemctl start ept-mx-adm\nsudo systemctl status ept-mx-adm\n```\n\n---\n\n## Usage\n\n### First Login\n\n1. Open your browser and navigate to `http://localhost:5000` (or your configured host:port)\n\n2. **Login Form:**\n - **Matrix Server**: Enter your server domain (e.g., `matrix.example.com` or `localhost`)\n - No need for `https://` - it's added automatically\n - Works with local servers, remote servers, and self-signed certificates\n \n - **Username**: Enter your admin username (e.g., `admin`)\n - No need for `@` or domain - it's formatted automatically\n \n - **Password**: Enter your Matrix admin password\n\n3. Click \"Login\"\n\nThe application will:\n- Automatically format the server URL (add `https://` if needed)\n- Automatically format the username into Matrix ID (add `@` and domain)\n- Verify admin privileges via Matrix API\n- Create a session for your admin user\n\n### Managing Users\n\n**View Users:**\n- Navigate to \"Users\" tab\n- See all users with pagination\n- Filter by guests and deactivated users\n- View media storage per user\n\n**Create User:**\n- Click \"Create User\" button\n- Fill in username, password, and optional display name\n- Choose if user should be admin\n- Click \"Create\"\n\n**Edit User:**\n- Click on user card dropdown menu\n- Select \"Edit\"\n- Modify user settings\n- Save changes\n\n**Deactivate User:**\n- Click on user dropdown menu\n- Select \"Deactivate\"\n- Confirm action\n\n### Managing Rooms\n\n**View Rooms:**\n- Navigate to \"Rooms\" tab\n- See all rooms with statistics\n- Toggle column visibility\n- Use search to find specific rooms\n\n**View Room Details:**\n- Click \"View\" button on room card\n- See detailed information in modal\n- View members, settings, and statistics\n\n**Edit Room:**\n- Click dropdown menu on room card\n- Select \"Edit\"\n- Modify room settings\n- Save changes\n\n**Delete Room:**\n- Click dropdown menu\n- Select \"Delete\"\n- Confirm action (room will be permanently deleted)\n\n### Managing Media\n\n**View Media Statistics:**\n- Navigate to \"Media\" tab\n- See overall statistics dashboard\n- View total files, storage, and users with media\n\n**View User Media:**\n- Click on user in media list\n- See all media files for that user\n- Filter by file type (Images, Videos, Audio, Documents, Other)\n- Filter by status (Normal, Quarantined)\n\n**Quarantine Media:**\n- In user media view, click dropdown on file\n- Select \"Quarantine\"\n- File will be marked as quarantined\n\n**Delete Media:**\n- Click dropdown on file\n- Select \"Delete\"\n- Confirm action\n\n### Managing Spaces\n\n**View Spaces:**\n- Navigate to \"Spaces\" tab\n- See all Matrix spaces\n- View space hierarchies\n- Manage space settings\n\n---\n\n## Localization\n\nEPT-MX-ADM supports multiple languages out of the box.\n\n### Available Languages\n- English (en)\n- Russian (ru)\n- German (de)\n- French (fr)\n- Italian (it)\n- Spanish (es)\n- Turkish (tr)\n\n### Changing Language\n\n**In Application:**\n1. Click on language selector in top navigation\n2. Choose your preferred language\n3. Interface will update immediately\n4. Language preference is saved in session\n\n**Adding New Language:**\n1. Copy `locales/en/messages.json` to `locales/[language_code]/messages.json`\n2. Translate all strings in the new file\n3. Language will be automatically detected and available\n\n---\n\n## Production Deployment\n\n### Security Checklist\n\n- [ ] Change `session.secret_key` in config.json to a random string\n- [ ] Set `app.debug` to `false` in config.json\n- [ ] Use strong passwords for admin accounts\n- [ ] Enable HTTPS (use nginx or Apache as reverse proxy)\n- [ ] Restrict access to the application (firewall, VPN)\n- [ ] Keep Python and dependencies up to date\n- [ ] Regular backups of config.json\n- [ ] Monitor logs for suspicious activity\n\n### Nginx Configuration Example\n\n```nginx\nserver {\n listen 80;\n server_name admin.yourdomain.com;\n \n # Redirect to HTTPS\n return 301 https://$server_name$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n server_name admin.yourdomain.com;\n \n # SSL certificates\n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n \n # Security headers\n add_header X-Frame-Options \"SAMEORIGIN\" always;\n add_header X-Content-Type-Options \"nosniff\" always;\n add_header X-XSS-Protection \"1; mode=block\" always;\n \n location / {\n proxy_pass http://127.0.0.1:5000;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n}\n```\n\n### Apache Configuration Example\n\n```apache\n<VirtualHost *:80>\n ServerName admin.yourdomain.com\n Redirect permanent / https://admin.yourdomain.com/\n</VirtualHost>\n\n<VirtualHost *:443>\n ServerName admin.yourdomain.com\n \n SSLEngine on\n SSLCertificateFile /path/to/cert.pem\n SSLCertificateKeyFile /path/to/key.pem\n \n ProxyPass / http://127.0.0.1:5000/\n ProxyPassReverse / http://127.0.0.1:5000/\n \n ProxyPreserveHost On\n RequestHeader set X-Forwarded-Proto \"https\"\n</VirtualHost>\n```\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"Connection refused\" or \"Cannot connect to Matrix server\"\n**Solution:**\n- Verify Matrix server URL is correct\n- Check if Matrix server is running\n- Ensure network connectivity\n- For local servers, try `localhost` or `127.0.0.1`\n- Check firewall rules\n\n#### \"SSL: CERTIFICATE_VERIFY_FAILED\" error\n**Solution:**\n- EPT-MX-ADM automatically handles self-signed certificates\n- If error persists, verify server URL starts with `https://`\n- Check if Matrix server certificate is properly configured\n\n#### \"Invalid credentials\" or \"Not an admin\"\n**Solution:**\n- Verify username and password are correct\n- Ensure user has admin privileges on Matrix server\n- Check if user is deactivated\n- Try logging in via Matrix client first to verify credentials\n\n#### Login form only shows username/password (no server field)\n**Solution:**\n- This is normal - server field is optional\n- Enter server domain at login or use default from config.json\n- Server field will be shown after first failed attempt\n\n#### Dashboard shows \"N/A\" or \"0\" for statistics\n**Solution:**\n- Verify admin API is enabled on Matrix server\n- Check if user has proper admin rights\n- Wait a few seconds for data to load\n- Check browser console for errors\n- Verify Matrix server API endpoints are accessible\n\n#### Pagination not working (users/rooms/spaces)\n**Solution:**\n- Clear browser cache and reload\n- Check browser console for JavaScript errors\n- Verify API responses in Network tab\n- Ensure using latest version of EPT-MX-ADM\n\n#### Media page shows \"Error loading media data\"\n**Solution:**\n- Verify `/v1/statistics/users/media` endpoint is available on Matrix server\n- Check if user has admin rights\n- Clear browser cache\n- Check server logs for errors\n\n---\n\n## Security\n\n### Best Practices\n\n1. **Passwords**: Use strong, unique passwords for admin accounts\n2. **Session Secret**: Change `session.secret_key` to a random string\n3. **Debug Mode**: Disable debug mode in production\n4. **HTTPS**: Always use HTTPS in production (via reverse proxy)\n5. **Access Control**: Restrict access to the application via firewall or VPN\n6. **Updates**: Keep Python, Flask, and all dependencies up to date\n7. **Logs**: Monitor application and server logs regularly\n8. **Backups**: Regular backups of configuration and data\n\n### SSL/TLS Support\n\nEPT-MX-ADM automatically:\n- Supports self-signed SSL certificates\n- Disables SSL verification for local/development servers\n- Adds `https://` to server URLs if not present\n- Suppresses SSL warnings in logs\n\nFor production, always use valid SSL certificates via reverse proxy.\n\n---\n\n## Contributing\n\nWe welcome contributions to EPT-MX-ADM!\n\n### How to Contribute\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Development Guidelines\n\n- Follow PEP 8 style guide for Python code\n- Add comments and docstrings\n- Update documentation for new features\n- Test your changes thoroughly\n- Update CHANGELOG.md\n\n### Reporting Issues\n\nFound a bug or have a feature request?\n\n1. Check if issue already exists\n2. Create new issue with detailed description\n3. Include steps to reproduce (for bugs)\n4. Provide environment details (OS, Python version, Matrix Synapse version)\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nMIT License allows you to:\n- Use the software for any purpose\n- Modify the source code\n- Distribute copies\n- Include in proprietary software\n\nWith the following conditions:\n- Include the original license and copyright notice\n- Provide attribution to original authors\n\n---\n\n## Support\n\n### Getting Help\n\n- **Documentation**: [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md)\n- **Issues**: [GitHub Issues](https://github.com/EPTLLC/EPT-MX-ADM/issues)\n- **Telegram**: [@EasyProTech](https://t.me/EasyProTech)\n- **Email**: Contact via GitHub profile\n\n### Commercial Support\n\nFor commercial support, custom development, or consulting services, contact EasyProTech LLC via:\n- Website: [www.easypro.tech](https://www.easypro.tech)\n- Telegram: [@EasyProTech](https://t.me/EasyProTech)\n\n---\n\n## Project Information\n\n- **Project Name**: EPT-MX-ADM\n- **Version**: 1.0.0\n- **Status**: Production Ready\n- **PyPI**: [pypi.org/project/ept-mx-adm](https://pypi.org/project/ept-mx-adm/)\n- **Company**: EasyProTech LLC\n- **Website**: [www.easypro.tech](https://www.easypro.tech)\n- **Developer**: Brabus\n- **Repository**: [github.com/EPTLLC/EPT-MX-ADM](https://github.com/EPTLLC/EPT-MX-ADM)\n- **License**: MIT\n- **Python**: 3.8+\n- **Supported Languages**: EN, RU, DE, FR, IT, ES, TR\n\n---\n\n## Acknowledgments\n\n- **Matrix Foundation** for the Matrix protocol\n- **Synapse Team** for the Matrix Synapse server\n- **Flask Team** for the amazing web framework\n- **Bootstrap Team** for the UI framework\n- **Chart.js Team** for visualization library\n- **Community Contributors** for feedback and contributions\n\n---\n\n## Changelog\n\nFor detailed history of changes, see [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n**Created with care by EasyProTech LLC**\n\nVisit us: [www.easypro.tech](https://www.easypro.tech) | Telegram: [@EasyProTech](https://t.me/EasyProTech)\n",
"bugtrack_url": null,
"license": null,
"summary": "Web-Based Administration Panel for Matrix Synapse Server",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/EPTLLC/EPT-MX-ADM/issues",
"Changelog": "https://github.com/EPTLLC/EPT-MX-ADM/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/EPTLLC/EPT-MX-ADM/blob/main/README.md",
"Homepage": "https://github.com/EPTLLC/EPT-MX-ADM",
"Source": "https://github.com/EPTLLC/EPT-MX-ADM",
"Telegram": "https://t.me/EasyProTech"
},
"split_keywords": [
"matrix",
" synapse",
" admin",
" administration",
" panel",
" web",
" flask",
" matrix-synapse",
" admin-panel",
" chat",
" communication",
" server-management",
" user-management",
" room-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5b94584846d6e0a7dd231e72ca2ce5e4cff85cd5a0efa7245b033e6f0b35520a",
"md5": "bee73c0d056d7697ddda8a9bb7f08e29",
"sha256": "76aea91895020f4630b454e483183dbb1a5c821bc339cb41ad0f5a67e465c0a8"
},
"downloads": -1,
"filename": "ept_mx_adm-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bee73c0d056d7697ddda8a9bb7f08e29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 45232,
"upload_time": "2025-10-23T23:14:26",
"upload_time_iso_8601": "2025-10-23T23:14:26.015592Z",
"url": "https://files.pythonhosted.org/packages/5b/94/584846d6e0a7dd231e72ca2ce5e4cff85cd5a0efa7245b033e6f0b35520a/ept_mx_adm-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a277d9b3b0ea7c257bfb2abc0ae13240ab3c3101108d33f262cae8f7cd768a38",
"md5": "6997223fdb22f610c47d4b144094a219",
"sha256": "35dab1e8ea3f566fd8aa0c111b6c8c6e05714540a68bcdd09bf749c20ddf10cc"
},
"downloads": -1,
"filename": "ept_mx_adm-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6997223fdb22f610c47d4b144094a219",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 272288,
"upload_time": "2025-10-23T23:14:28",
"upload_time_iso_8601": "2025-10-23T23:14:28.159076Z",
"url": "https://files.pythonhosted.org/packages/a2/77/d9b3b0ea7c257bfb2abc0ae13240ab3c3101108d33f262cae8f7cd768a38/ept_mx_adm-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 23:14:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EPTLLC",
"github_project": "EPT-MX-ADM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Flask",
"specs": [
[
"==",
"2.3.3"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
"==",
"2.3.7"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.2"
]
]
},
{
"name": "gunicorn",
"specs": [
[
"==",
"21.2.0"
]
]
},
{
"name": "psutil",
"specs": [
[
"==",
"5.9.5"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.0.4"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2023.7.22"
]
]
}
],
"lcname": "ept-mx-adm"
}
JSON
