Update README.md with project overview, features, and installation instructions

2025-12-08 07:35:03 -05:00
parent 86f5f38b76
commit c185770c19
1 changed files with 478 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,478 @@
+<p align="center">
+  <a href="https://virtnet.bond">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/logo-light.svg">
+      <img alt="Virtnet.bond" src="https://raw.githubusercontent.com/VirtnetBond/assets/main/logo-light.svg" width="350">
+    </picture>
+  </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>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/dashboard-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/dashboard-light.png">
+    <img alt="Dashboard Preview" src="https://raw.githubusercontent.com/VirtnetBond/assets/main/dashboard-light.png" width="100%">
+  </picture>
+</p>
+
+<br>
+
+## ✨ Features
+
+### 🎛️ Admin Panel
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/admin-panel-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/admin-panel-light.png">
+    <img alt="Admin Panel" src="https://raw.githubusercontent.com/VirtnetBond/assets/main/admin-panel-light.png" width="100%">
+  </picture>
+</p>
+
+- **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
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/server-integrations-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/server-integrations-light.png">
+    <img alt="Server Integrations" src="https://raw.githubusercontent.com/VirtnetBond/assets/main/server-integrations-light.png" width="100%">
+  </picture>
+</p>
+
+| Server Type | Features |
+|-------------|----------|
+| **Proxmox** | VM/LXC management, console access, statistics, firewall, snapshots, cloud-init |
+| **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 |
+
+### 💳 Payment Gateways
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/payment-gateways-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/VirtnetBond/assets/main/payment-gateways-light.png">
+    <img alt="Payment Gateways" src="https://raw.githubusercontent.com/VirtnetBond/assets/main/payment-gateways-light.png" width="100%">
+  </picture>
+</p>
+
+- **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>
+
+## 👥 Contributors
+
+<a href="https://github.com/VirtnetBond/Virtnet.bond/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=VirtnetBond/Virtnet.bond" />
+</a>
+
+<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>