Description

This module integrates Blesta with EasyPanel, a modern server control panel that makes it easy to manage your applications with a simple web interface.

Key Features

• Multi-server Support: Configure multiple EasyPanel servers with different aliases, hostnames, and API credentials
• Dual Service Types:
  • EasyPanel Templates: Use predefined application templates via createFromSchema API
  • Custom Apps: Create custom applications with full control via createService API
• Manual SSH Key Generation: Generate SSH keys on-demand for custom apps via client Actions tab (avoids race conditions)
• Template System: JSON-based configuration with dynamic variable replacement
• Comprehensive Logging: Full API request/response logging for debugging and monitoring
• Client Management: Domain management and service statistics through client interface
• GitHub Integration: Seamless code deployment from repositories

GitHub Integration

The EasyPanel module now includes comprehensive GitHub integration that allows customers to deploy code directly from their GitHub repositories to their EasyPanel services, similar to platforms like Vercel and Dokploy.

Features

• Easy Repository Connection: Customers can connect their GitHub repositories using either HTTPS or SSH URLs
• Branch and Path Selection: Deploy from specific branches and subdirectories
• One-Click Deployment: Deploy latest code with a single button click
• SSH Key Management: Automatic SSH key generation and display for private repositories
• GitHub App Integration: Seamless integration through GitHub Apps (no need for admin to create GitHub developer apps)

Customer Workflow

1. Repository Connection: Customers can directly connect their GitHub repositories using the repository URL
2. Branch and Path Selection: Choose specific branches and subdirectories to deploy from
3. SSH Key Setup (for private repos): Copy the generated SSH key to repository’s deploy keys
4. Deploy: Use the deploy button to pull latest code from the selected branch

Technical Implementation

Repository URL Handling

• Accepts both HTTPS and SSH GitHub URLs
• Automatically converts HTTPS URLs to SSH format for EasyPanel compatibility
• Validates repository URL format

SSH Key Integration

For private repositories:

1. Customer generates SSH key through the Actions tab (custom apps only)
2. SSH public key is displayed with instructions
3. Customer adds the public key to GitHub repository’s deploy keys
4. EasyPanel can then access the private repository

Customer Experience

Actions Tab Features

1. Service Information: Display service details and current domain
2. SSH Key Management: Generate and view SSH keys for custom apps
3. GitHub Integration: Connect, configure, and deploy from GitHub repositories
4. Domain Management: Update service domains with DNS configuration guidance

User Interface

• Repository Connection Form: Input fields for repository URL, branch, and path
• Connected Repository Display: Shows current repository details with deploy/disconnect options
• SSH Key Instructions: Clear instructions for adding deploy keys to private repositories
• Service Type Guidance: Contextual information about GitHub integration availability

Installation Requirements

1. EasyPanel server with API access
2. SSH key configuration for private repositories (custom apps only)
3. GitHub repository access (public or with deploy keys for private repos)

Configuration

No additional admin configuration required. Customers can connect repositories directly through the service interface.

Service Types

Template Services

• Uses EasyPanel’s template system for predefined application stacks
• Template variable replacement for dynamic configuration
• Suitable for standard applications with known configurations

Custom App Services

• Creates custom applications with full configuration control
• SSH key generation available for Git repository access
• GitHub integration for code deployment
• Ideal for custom applications and development workflows

SSH Key Management

• Available for custom apps only via client Actions tab
• Manual generation after service provisioning to avoid race conditions
• Checks existing keys
• Generates new keys

Service Name Handling

• Generated name (plan_name + random string) used for all operations
• Used for service management, deletion, statistics, and domain management

JSON Template Placeholders

• $service_id → Blesta service ID (replaced after service creation)
• $domain → Customer hostname/domain from order form
• $ram_limit → RAM limit in MB from package configuration
• $cpu_limit → CPU limit in cores from package configuration
• $project_name → Server’s project name
• $custom_field_1 → Custom field from configurable options named ‘custom_field_1’
• $custom_field_2 → Custom field from configurable options named ‘custom_field_2’

Installation

1. Extract easypanel.zip to components/modules/ in your Blesta installation or copy extracted easypanel folder to components/modules/.
2. Navigate to Settings > Modules in Blesta admin
3. Install the EasyPanel module
4. If license.json not exist, rename license.example.json to license.json and insert your serial key in key object.
5. Configure your EasyPanel servers
6. Customers can then deploy GitHub App and connect repositories as needed

Configuration

Adding a Server

1. Go to Settings > Modules > EasyPanel > Manage
2. Click Add Server
3. Configure the following settings:
   • Hostname: Your EasyPanel server hostname (e.g., panel.yourdomain.com)
   • Server Label: A friendly name for the server
   • API Key: Your EasyPanel API key
   • Project Name: The EasyPanel project name where services will be created

Creating Packages

1. Go to Packages > Browse
2. Create a new package and select the EasyPanel module
3. Configure package settings:
   • EasyPanel Server: Select which server to use
   • Plan Name: A unique name for this service plan
   • JSON Template: The EasyPanel service configuration in JSON format
   • CPU Limit: CPU cores limit
   • RAM Limit: RAM limit in MB

JSON Template Format

The JSON template should follow EasyPanel’s service schema format. Placeholders will be automatically replaced:

• $service_id → Blesta service ID (replaced after service creation)
• $domain → Customer-provided hostname/domain from order form
• $ram_limit → RAM limit in MB from package configuration
• $cpu_limit → CPU limit in cores from package configuration
• $project_name → Server’s project name
• $custom_field_1 → Custom field from configurable options
• $custom_field_2 → Custom field from configurable options

Example template:

{
  "json": {
    "name": "LinkStack",
    "projectName": "$project_name",
    "schema": {
      "services": [
        {
          "type": "app",
          "data": {
            "serviceName": "$service_id",
            "env": "SERVER_ADMIN=$custom_field_1\nHTTPS_SERVER_NAME=$domain\nHTTP_SERVER_NAME=$domain\nFORCE_HTTPS=true",
            "source": {
              "type": "image",
              "image": "linkstackorg/linkstack:latest"
            },
            "domains": [
              {
                "host": "$domain",
                "port": 80
              }
            ],
            "mounts": [
              {
                "type": "volume",
                "name": "htdocs",
                "mountPath": "/htdocs"
              }
            ],
            "resources": {
              "memoryReservation": 0,
              "memoryLimit": $ram_limit,
              "cpuReservation": 0,
              "cpuLimit": $cpu_limit
            }
          }
        }
      ]
    }
  }
}

Note: The $service_id placeholder is replaced with a temporary value during initial provisioning and updated with the actual Blesta service ID after the service is created in the database.

How to get Easypanel Templates

From Easypanel Template Github repository

• Get template collections from Easypanel template repository in https://github.com/easypanel-io/templates/tree/main/templates

From Easypanel GUI

• Activate browser’s debug window/development mode
• Inspect on Network tab
• Deploy a template in Easypanel
• Wait for traffic to host + /api/trpc/templates.createFromSchema
• Open Payload tab
• Copy the JSON and modify with available Placeholders

Service Name Tracking

The module automatically captures the actual service name returned by EasyPanel after service creation. This enables accurate resource tracking and monitoring:

Service Fields Stored

• easypanel_hostname: Customer-provided hostname
• easypanel_service_name: Generated service name (customer_id + plan_name)
• easypanel_actual_service_name: Actual service name returned by EasyPanel (used for API calls)

Service Lifecycle Management

The module handles the complete service lifecycle:

Service Creation

• Automatically provisions services in EasyPanel when orders are activated
• Captures the actual service name for future management
• Supports JSON template placeholders for dynamic configuration

Service Deletion

When a service is cancelled in Blesta, the module automatically deletes it from EasyPanel. This ensures that cancelled services are properly cleaned up on the EasyPanel server.

API Requirements

• EasyPanel server with API access enabled (Can use EasyPanel free version)
• Valid API key with service management permissions
• Network connectivity between Blesta and EasyPanel servers
• Cloudflare or ClouDNS API key/auth/token if provisioned service will use generated subdomain

System Requirements

• Tested on Blesta 5+ (recommended to update to latest version)
• IonCude Loaders 14
• PHP 8.1+
• Module License Key

Support

Have questions or ideas to make this module even better? We’re here to help and always open to your feedback. Your input helps us improve and serve you better.

Licensing

• One license valid to one company and one hosting instance for a year.
• When license expired, customer’s services in EasyPanel will continue to run without any interuption but admin will not able to add more servers and provision new services.