Files
Virtnet.bond/README.md

639 lines
23 KiB
Markdown

<p align="center">
<a href="https://virtnet.bond">
<h1 align="center">Virtnet.bond</h1>
</a>
</p>
<h3 align="center">
Enterprise-Grade Billing & Service Automation Platform for Hosting Providers 🚀
</h3>
<p align="center">
<a href="https://github.com/VirtnetBond/Virtnet.bond/actions/workflows/ci.yml">
<img src="https://img.shields.io/github/actions/workflow/status/VirtnetBond/Virtnet.bond/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI Status">
</a>
<a href="https://github.com/VirtnetBond/Virtnet.bond/graphs/contributors">
<img src="https://img.shields.io/github/contributors/VirtnetBond/Virtnet.bond?style=for-the-badge&logo=github" alt="Contributors">
</a>
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="License">
</a>
<a href="https://discord.gg/virtnetbond">
<img src="https://img.shields.io/discord/123456789?style=for-the-badge&logo=discord&label=Discord" alt="Discord">
</a>
</p>
<p align="center">
<a href="https://virtnet.bond">Website</a> •
<a href="https://docs.virtnet.bond">Documentation</a> •
<a href="https://discord.gg/virtnetbond">Community</a> •
<a href="https://github.com/VirtnetBond/Virtnet.bond/issues">Issues</a>
</p>
<br>
---
## 📖 Introduction
**Virtnet.bond** is a powerful, self-hosted billing and service automation platform built specifically for hosting providers. It provides a centralized solution for managing product catalogs, automating server provisioning, processing payments, and delivering exceptional customer experiences.
Built on **Laravel**, **Livewire**, and **Filament**, Virtnet.bond offers a modern, reactive single-page application experience with a comprehensive admin panel and customer portal.
<br>
## ✨ Features
### 🎛️ Admin Panel
- **Filament-Powered Dashboard** - Modern admin interface with real-time statistics
- **Product & Service Management** - Create and manage products, pricing, and configurations
- **Customer Management** - View customer details, services, invoices, and activity
- **Ticket System** - Handle support tickets with attachments and priority levels
- **Announcements** - Publish system-wide or targeted announcements
- **Knowledge Base** - Create documentation and guides for customers
### 🖥️ Server Integrations
| Server Type | Features |
|-------------|----------|
| **Proxmox** | VM/LXC management, console access, statistics, firewall, cloud-init, backups |
| **Pterodactyl** | Game server management, file manager, console, backups |
| **Virtualizor** | VPS management, OS reinstall, network configuration |
| **VirtFusion** | Virtual machine provisioning and management |
| **cPanel** | Web hosting account automation |
| **DirectAdmin** | Web hosting panel integration |
| **Plesk** | Web hosting automation |
| **Convoy** | Container orchestration |
| **Enhance** | Web hosting platform |
| **Froxlor** | Server management panel |
<br>
## 🖥️ Proxmox VE Integration
Virtnet.bond includes a comprehensive **Proxmox VE** extension that provides enterprise-grade virtual machine and container management directly within the client portal. This powerful integration enables hosting providers to offer self-service VPS and cloud computing products.
### Overview Dashboard
The Proxmox extension provides customers with a real-time overview of their virtual servers:
- **Server Status** - Live VM/LXC status (running, stopped, suspended)
- **Resource Usage** - CPU, memory, disk, and network utilization
- **Quick Actions** - Start, stop, reboot, and shutdown controls
- **Hostname Management** - Customizable server hostname
- **Server Notes** - Add custom notes stored in Proxmox VM description
### 📊 Statistics & Monitoring
Comprehensive real-time and historical statistics with interactive charts:
- **CPU Usage** - Percentage utilization over time (hour/day/week/month views)
- **Memory Consumption** - RAM usage with average and maximum aggregation
- **Network Traffic** - Inbound/outbound data transfer visualization
- **Disk I/O** - Read/write operations performance
- **Network Analysis** - Connection tracking, top ports, and security insights
- **Task History** - Complete audit log of all VM operations with timing
### 🔒 Firewall Management
Full firewall control integrated with Proxmox and CoreRouter:
- **Enable/Disable Firewall** - Per-interface firewall toggling
- **Default Policies** - Configure inbound/outbound DROP or ACCEPT policies
- **Rule Management** - Create, edit, delete, and reorder firewall rules
- **Protocol Support** - TCP, UDP, ICMP, and all IP protocols
- **Proxmox Macros** - 50+ predefined service macros (HTTP, HTTPS, SSH, RDP, MySQL, etc.)
- **Logging Options** - Configure rule logging levels (none, alert, critical, error, warning)
- **CoreRouter Integration** - Advanced routing and firewall synchronization
- **Save/Load Configurations** - Save firewall configurations and apply them across multiple VPS instances
#### 💾 Firewall Configuration Templates
The firewall module includes a powerful configuration save/load system:
- **Save Current Configuration** - Capture all firewall rules and policies as a named template
- **Configuration Library** - Store unlimited configurations per user account
- **Quick Apply** - One-click application of saved configurations to any VPS
- **Cross-VPS Compatibility** - Intelligent compatibility checking when applying configurations
- **Auto-Disable Incompatible Rules** - Rules targeting non-existent interfaces or IPs are automatically disabled
- **Configuration Preview** - View saved configuration details including rules count and policies
- **Delete Configurations** - Remove outdated configurations from your library
### 🌐 Network Configuration
Complete network interface management:
- **Interface Types** - VirtIO, Intel E1000/E1000e, Realtek RTL8139, VMware vmxnet3, AMD PCnet
- **Multi-queue Support** - Configure network adapter queues for performance
- **Link State Control** - Enable/disable network interfaces
- **MTU Configuration** - Custom Maximum Transmission Unit settings
- **Guest Agent Networks** - View IP addresses assigned via QEMU guest agent
### 💾 Storage Management
Comprehensive disk and storage operations:
- **Drive Management** - View, add, resize, and remove virtual disks
- **Bus Types** - IDE, SATA, SCSI, and VirtIO block devices
- **SCSI Controllers** - LSI, MegaRAID SAS, VirtIO SCSI, VMware PVSCSI
- **Cache Modes** - No cache, directsync, writethrough, writeback, unsafe
- **Async I/O** - io_uring, native, and threads options
- **SSD Emulation** - Enable SSD emulation for solid-state performance
- **Discard/TRIM** - Enable discard for thin-provisioned storage
- **I/O Threads** - Dedicated I/O threads for improved performance
- **Unused Disks** - Manage detached/unused drives
### 🔄 Boot Order Configuration
Control VM boot sequence and media:
- **Boot Device Order** - Drag-and-drop reordering of boot devices
- **Multiple CD/DVD Drives** - Support for multiple optical drives
- **ISO Management** - Mount/unmount ISO images from storage
- **Available Devices** - Add/remove boot devices from sequence
### 🖼️ Display Settings
Graphics adapter configuration:
- **Display Types** - Standard VGA, VirtIO-GPU, VMware compatible, Cirrus, Serial console
- **Video Memory** - Configurable display memory (VirtIO-GPU)
- **USB Tablet** - Toggle tablet device for pointer synchronization
### ☁️ Cloud-Init Support
Automated VM configuration via cloud-init:
- **User Configuration** - Set default user and password
- **SSH Keys** - Manage authorized SSH public keys
- **DNS Settings** - Configure DNS domain and nameservers
- **Network Configuration** - Static IP, gateway, and IPv6 settings per interface
- **OS Type Selection** - Linux (modern/legacy), Windows variants, Solaris, and generic
- **Package Upgrades** - Enable automatic package upgrades on boot
### 📦 Backup Management
Integrated backup and restore functionality:
- **Backup List** - View all available VM backups with timestamps
- **Restore Operations** - One-click backup restoration with confirmation
- **Backup Deletion** - Remove old backups to free storage space
- **Configurable Limits** - Per-product backup quantity limits
### 🔧 OS Reinstallation
Self-service operating system reinstallation:
- **OS Selection** - Choose from available operating system templates
- **Location-Based Templates** - OS options filtered by server location
- **Protection Check** - Prevents reinstall on protected VMs
- **Confirmation Required** - Multi-step confirmation to prevent accidents
### 🌍 Subdomain Management
Dynamic DNS subdomain creation (Technitium DNS integration):
- **Auto-Generated Subdomains** - Randomly generated memorable subdomains
- **Custom Subdomains** - User-defined subdomain names
- **Multiple Zones** - Support for multiple DNS zones
- **Record Types** - A records for IPv4 addresses
- **IP Selection** - Bind subdomains to specific server IP addresses
### 🖥️ Console Access
Multiple console options for server access:
- **VNC Console** - Browser-based graphical console via noVNC
- **xterm.js Terminal** - Web-based terminal access
- **Node Configuration** - Per-node VNC enable/disable settings
### System Configuration
Advanced VM system settings:
- **Resource Limits** - CPU cores, sockets, memory allocation
- **CPU Models** - 70+ CPU models (Intel, AMD, generic)
- **Resource Pools** - Organize VMs into Proxmox resource pools
- **IP Address Allocation** - IPv4 and IPv6 address management
- **Location-Based Provisioning** - Node selection by location
### Extension Configuration
Flexible product configuration options:
```php
// Available product settings
[
'location_id' => 'Server location for provisioning',
'ipv4' => 'Number of IPv4 addresses',
'ipv6' => 'Number of IPv6 addresses',
'pool' => 'Proxmox resource pool',
'cpu' => 'CPU model (70+ options)',
'cores' => 'Number of CPU cores',
'sockets' => 'Number of CPU sockets',
'memory' => 'RAM allocation (MiB)',
'disk' => 'Storage allocation (GiB)',
'backups' => 'Number of backup slots',
]
```
### Proxmox Extension Structure
```
extensions/Servers/Proxmox/
├── Proxmox.php # Main extension class
├── TechnitiumDns.php # DNS integration
├── routes.php # Extension routes
├── Admin/ # Admin panel resources
├── Console/ # Artisan commands
├── database/ # Migrations
├── Http/ # Controllers
├── Jobs/ # Queue jobs
├── Livewire/ # Livewire components
│ ├── Overview.php # Dashboard with stats
│ ├── Statistics.php # Detailed analytics
│ ├── Firewall.php # Firewall management
│ ├── Network.php # Network interfaces
│ ├── Storage.php # Disk management
│ ├── BootOrder.php # Boot configuration
│ ├── Display.php # Graphics settings
│ ├── CloudInit.php # Cloud-init config
│ ├── Subdomain.php # DNS subdomains
│ ├── Reinstall.php # OS reinstallation
│ ├── VNC.php # VNC console
│ ├── XTerm.php # Terminal access
│ └── Backups/ # Backup management
├── Models/ # Eloquent models
├── Providers/ # Service providers
├── Services/ # API services
│ └── CoreRouterClient.php # Router integration
└── views/ # Blade templates
```
### 💳 Payment Gateways
- **Stripe** - Credit cards, Apple Pay, Google Pay, and more
- **PayPal** - PayPal payments and subscriptions
- *Extensible architecture for additional gateways*
### 🧩 Extensions & Plugins
| Category | Extensions |
|----------|------------|
| **Communication** | Announcements, Knowledge Base, Contact Page, JivoChat, OpenWidget |
| **Security** | AntiVPN, Authentik SSO, Security Suite, Compliance Tools |
| **Analytics** | Cloudflare Analytics, UptimeLab |
| **Customization** | NavbarManager, Custom Pages, Cookie Banner, Force Theme |
| **Social** | Discord+, Social Base |
| **Billing** | Credits Plus, Onboarding |
<br>
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Virtnet.bond │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Themes │ │ Extensions │ │ Core Platform │ │
│ │ (LucentUI) │ │ (Modular) │ │ (Laravel + Livewire) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Filament Admin Panel │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│ │
│ │ │Products │ │Services │ │ Tickets │ │ Configuration ││ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘│ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │
│ │ Servers │ │ Gateways │ │ Others │ │
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────────┐ │ │
│ │ │Proxmox │ │ │ │ Stripe │ │ │ │Announcements│ │ │
│ │ │Pterodac.│ │ │ │ PayPal │ │ │ │KnowledgeBase│ │ │
│ │ │Virtuali.│ │ │ └─────────┘ │ │ │ Security │ │ │
│ │ │VirtFusi.│ │ │ │ │ │ Analytics │ │ │
│ │ │ cPanel │ │ │ │ │ └─────────────┘ │ │
│ │ └─────────┘ │ │ │ │ │ │
│ └───────────────┘ └───────────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
<br>
## 🚀 Quick Start
### Prerequisites
Before installing Virtnet.bond, ensure you have:
- **PHP** ^8.2 or ^8.3
- **MySQL/MariaDB** 8.0+
- **Redis** (recommended for caching/queues)
- **Node.js** 18+ and npm
- **Composer** 2.x
### Required PHP Extensions
```
bcmath, curl, exif, gd, gmp, intl, json, mbstring, pcntl, pdo, pdo_mysql, redis, sockets, xml, zip
```
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/VirtnetBond/Virtnet.bond.git
cd Virtnet.bond
```
2. **Install PHP dependencies**
```bash
composer install --no-dev --optimize-autoloader
```
3. **Install Node.js dependencies and build assets**
```bash
npm install
npm run build
```
4. **Configure environment**
```bash
cp .env.example .env
php artisan key:generate
```
5. **Configure your `.env` file**
```env
APP_URL=https://your-domain.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=virtnetbond
DB_USERNAME=your_username
DB_PASSWORD=your_password
```
6. **Run migrations and seed database**
```bash
php artisan migrate --seed
```
7. **Create storage link**
```bash
php artisan storage:link
```
8. **Set up queue worker** (recommended)
```bash
php artisan queue:work
```
### Docker Installation
```bash
docker-compose up -d
```
<br>
## 📂 Project Structure
```
Virtnet.bond/
├── app/
│ ├── Admin/ # Filament admin resources
│ │ ├── Resources/ # CRUD resources
│ │ ├── Pages/ # Custom admin pages
│ │ └── Widgets/ # Dashboard widgets
│ ├── Livewire/ # Livewire components
│ │ ├── Tickets/ # Ticket management
│ │ ├── Services/ # Service management
│ │ └── Products/ # Product browsing
│ ├── Models/ # Eloquent models
│ └── Helpers/ # Utility classes
├── extensions/
│ ├── Gateways/ # Payment gateway integrations
│ │ ├── PayPal/
│ │ └── Stripe/
│ ├── Servers/ # Server provisioning integrations
│ │ ├── Proxmox/
│ │ ├── Pterodactyl/
│ │ └── ...
│ └── Others/ # Additional extensions
│ ├── Announcements/
│ ├── KnowledgeBase/
│ └── ...
├── themes/
│ └── lucentui/ # Default theme
│ ├── css/
│ ├── views/
│ └── vite.config.js
├── resources/
│ └── views/ # Core Blade templates
├── routes/
│ ├── web.php # Web routes
│ └── api.php # API routes
└── config/ # Configuration files
```
<br>
## 🎨 Theming
Virtnet.bond uses a powerful theming system powered by **LucentUI**. Themes support:
- **CSS Custom Properties** - Theme tokens for consistent styling
- **Dark/Light Mode** - Automatic theme switching
- **Tailwind CSS** - Utility-first styling
- **Remix Icons** - Comprehensive icon library
### Creating a Custom Theme
```bash
# Create a new theme
cp -r themes/lucentui themes/mytheme
# Update theme.php with your theme details
# Customize CSS and Blade templates
# Build assets
node vite.js mytheme
```
<br>
## 🔌 Extension Development
Extensions are the heart of Virtnet.bond's modularity. Create your own extensions to add:
- Server integrations
- Payment gateways
- Custom pages and features
- Admin panel additions
### Extension Structure
```php
extensions/
└── YourExtension/
├── YourExtension.php # Main extension class
├── Livewire/ # Livewire components
├── views/ # Blade templates
├── routes/ # Custom routes
└── migrations/ # Database migrations
```
### Basic Extension Class
```php
<?php
namespace Paymenter\Extensions\Others\YourExtension;
use App\Helpers\ExtensionHelper;
class YourExtension
{
public function enabled(): bool
{
// Run migrations, register routes, etc.
return true;
}
public function getConfig(): array
{
return [
[
'name' => 'setting_name',
'type' => 'text',
'label' => 'Setting Label',
'description' => 'Description of the setting',
],
];
}
}
```
<br>
## 🛠️ Development
### Running in Development Mode
```bash
# Start the development server
php artisan serve
# Watch for asset changes
npm run dev
# Or run both simultaneously
composer dev
```
### Running Tests
```bash
php artisan test
```
### Code Style
```bash
# Fix code style issues
./vendor/bin/pint
```
### Database Migrations
```bash
# Create a new migration
php artisan make:migration create_example_table
# Run migrations
php artisan migrate
# Rollback migrations
php artisan migrate:rollback
```
<br>
## 📊 API Documentation
Virtnet.bond provides a comprehensive REST API for integration with external systems.
- **API Documentation**: Available at `/docs/api` when enabled
- **Authentication**: Laravel Passport OAuth2
- **Rate Limiting**: Configurable per-endpoint limits
```bash
# Generate API documentation
php artisan scramble:export
```
<br>
## 🤝 Contributing
We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or spreading the word - we'd love to have you.
### 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**
### Contribution Types
- 🐛 **Bug Reports** - Found an issue? [Create a bug report](https://github.com/VirtnetBond/Virtnet.bond/issues/new?template=bug_report.md)
- ✨ **Feature Requests** - Have an idea? [Submit a feature request](https://github.com/VirtnetBond/Virtnet.bond/issues/new?template=feature_request.md)
- 📖 **Documentation** - Help improve our docs
- 🧩 **Extensions** - Build and share extensions
<br>
## 📜 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
<br>
## 🙏 Acknowledgments
Virtnet.bond is built on the shoulders of giants:
- [Laravel](https://laravel.com) - The PHP Framework
- [Livewire](https://livewire.laravel.com) - Full-stack framework for Laravel
- [Filament](https://filamentphp.com) - Admin panel framework
- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
- [Alpine.js](https://alpinejs.dev) - Lightweight JavaScript framework
- [Paymenter](https://paymenter.org) - Original billing platform inspiration
<br>
---
<p align="center">
<sub>Built with ❤️ by the Virtnet.bond team</sub>
</p>
<p align="center">
<a href="https://virtnet.bond">Website</a> •
<a href="https://docs.virtnet.bond">Docs</a> •
<a href="https://discord.gg/virtnetbond">Discord</a> •
<a href="https://twitter.com/virtnetbond">Twitter</a>
</p>