Liberu — Kubernetes, Docker or Standalone Webhosting Control Panel

Welcome to Liberu, our visionary open-source initiative that marries the power of Laravel 12, PHP 8.5 and Filament 5.2 to redefine the landscape of web development.

A modular, Kubernetes-native Laravel control panel for managing web hosting: virtual hosts (NGINX), BIND DNS zones, Postfix/Dovecot mail, MySQL databases, and container orchestration. Designed for sysadmins and self-hosting teams who want a single web interface to manage hosting infrastructure with production-grade Kubernetes deployment (recommended), as well as Docker Compose and standalone options.

🚀 Production-Ready Kubernetes Deployment
Kubernetes is the recommended deployment method for production environments, offering auto-scaling, high availability, and enterprise-grade orchestration. See our Complete Kubernetes Installation Guide and Managed Kubernetes Setup for AWS EKS, Azure AKS, Google GKE, and DigitalOcean DOKS.

Key features

• Production-ready Kubernetes deployment with auto-scaling, high availability, and container orchestration
• User and team management with Jetstream and role-based policies
• Multi-site management with comprehensive performance monitoring and uptime tracking
• Multi-deployment support: Kubernetes (recommended), Docker Compose, Standalone, and Standalone DNS Only deployments
• Auto-scaling: Automatic horizontal and vertical scaling on AWS EKS, Azure AKS, Google GKE, DigitalOcean DOKS, OVH
• Production-optimized nginx with gzip compression, security headers, and static caching
• Manage NGINX virtual hosts with automated Let's Encrypt support
• BIND DNS zone and record management (A, AAAA, CNAME, MX, TXT, ...)
• Mail domain and mailbox management (Postfix + Dovecot)
• MySQL database + user lifecycle and backup/restore helpers
• Managed database support for AWS RDS, Azure Database, DigitalOcean, OVH, and Google Cloud SQL (see Managed Databases Guide)
• Kubernetes and Docker orchestration: deploy, monitor, and manage services
• Secure SSH-based remote server management
• Managed Kubernetes storage support with platform-specific storage classes (EBS, Azure Disk, GCE PD, DO Block Storage)
• S3-compatible storage support for persistent volumes (AWS S3, MinIO, DigitalOcean Spaces, etc.)
• WordPress auto-deployment with one-click installation and automatic updates
• Git repository deployment from GitHub, GitLab, Bitbucket with webhook support
• Performance metrics tracking including uptime, response times, bandwidth, and visitor analytics
• cPanel/Plesk/DirectAdmin alternative with modern cloud-native architecture

Quick Start

🚀 Unified Installation (Recommended)

The easiest way to install the control panel is using our unified installation script that supports:

• Kubernetes (recommended for production)
• Docker Compose (for development/small-scale)
• Standalone (traditional server setup)
• Standalone DNS Only (DNS cluster node)

Supported Operating Systems:

• Ubuntu LTS (20.04, 22.04, 24.04)
• Debian (11, 12)
• AlmaLinux / RHEL 8/9/10
• Rocky Linux 8/9/10
• CloudLinux 8/9/10 (Standalone only)

One-Line Installation:

# Clone the repository
git clone https://github.com/liberu-control-panel/control-panel-laravel.git
cd control-panel-laravel

# Run the unified installer
sudo ./install.sh

The script will:

1. Detect your operating system
2. Present a menu to choose installation method
3. Install all required dependencies
4. Configure and deploy the control panel
5. Provide next steps and access information

See the complete Installation Guide for detailed instructions.

---

Complete Kubernetes Installation (Advanced)

For a complete, production-ready installation including Kubernetes cluster setup, control panel, and all services (mail, DNS, PHP multi-version, etc.), see the Complete Kubernetes Installation Guide.

Installation Options:

1. Self-Managed Cluster - Install complete Kubernetes cluster from scratch

   • Automated installation on Ubuntu LTS & AlmaLinux/RHEL
   • Full control over infrastructure
   • See: Kubernetes Installation Guide

2. Managed Kubernetes - Deploy on cloud-managed Kubernetes (recommended for production)

   • AWS EKS, Azure AKS, Google GKE, or DigitalOcean DOKS
   • No control plane management needed
   • Auto-scaling and high availability
   • See: Managed Kubernetes Setup Guide

What's Included:

• Control Panel with Laravel Octane support
• NGINX Ingress with Let's Encrypt SSL
• MariaDB cluster with replication
• Redis for caching
• Postfix + Dovecot mail services
• PowerDNS DNS cluster
• PHP multi-version support (8.1-8.5)
• Queue workers and scheduler
• S3-compatible storage integration for persistent volumes

Quick Installation (Self-Managed):

# Step 1: Install Kubernetes cluster (auto-detects managed K8s)
sudo ./install-k8s.sh

# Step 2: Install control panel and all services
# The script will prompt for S3 storage configuration
./install-control-panel.sh

Quick Installation (Managed Kubernetes):

# Step 1: Create cluster using cloud provider tools
# See docs/MANAGED_KUBERNETES_SETUP.md for detailed instructions

# Step 2: Configure kubectl access
aws eks update-kubeconfig --region us-west-2 --name control-panel-cluster
# OR: az aks get-credentials --resource-group rg --name cluster
# OR: gcloud container clusters get-credentials cluster --region region
# OR: doctl kubernetes cluster kubeconfig save cluster

# Step 3: Install add-ons and control panel (auto-detected)
sudo ./install-k8s.sh
./install-control-panel.sh

Storage Options:

• During installation, you'll be prompted to configure S3-compatible storage
• Supports AWS S3, MinIO, DigitalOcean Spaces, Backblaze B2, Cloudflare R2, and more
• All services including MariaDB can use S3 storage for persistent volumes
• See S3 Storage Guide for detailed configuration

Kubernetes Deployment (Manual)

Deploy the control panel on an existing Kubernetes cluster. See the detailed Kubernetes Setup Guide for complete instructions.

Prerequisites:

• Kubernetes cluster (v1.20+)
• NGINX Ingress Controller
• cert-manager (for automatic SSL certificates)
• kubectl and Helm installed locally

Option 1: Deploy with Helm

git clone https://github.com/liberu-control-panel/control-panel-laravel.git
cd control-panel-laravel

# Generate app key
APP_KEY=$(php artisan key:generate --show)

# Install with Helm
helm install control-panel ./helm/control-panel \
  --set app.key="$APP_KEY" \
  --set app.url="https://control.yourdomain.com" \
  --set mysql.auth.password="secure-password" \
  --set mysql.auth.rootPassword="secure-root-password" \
  --set ingress.hosts[0].host="control.yourdomain.com" \
  --namespace control-panel \
  --create-namespace

# Optional: Enable S3 storage for persistent volumes
helm install control-panel ./helm/control-panel \
  --set app.key="$APP_KEY" \
  --set app.url="https://control.yourdomain.com" \
  --set s3.enabled=true \
  --set s3.endpoint="https://s3.amazonaws.com" \
  --set s3.accessKey="your-access-key" \
  --set s3.secretKey="your-secret-key" \
  --set s3.bucket="control-panel-storage" \
  --set s3.region="us-east-1" \
  --namespace control-panel \
  --create-namespace

Option 2: Deploy with Kustomize

export APP_KEY="base64:YOUR_KEY"
export DB_PASSWORD="secure-password"
export DB_ROOT_PASSWORD="secure-root-password"
export DOMAIN="control.yourdomain.com"

./k8s/deploy.sh

Option 3: Deploy with Makefile

make deploy-prod
make migrate
make status

Managing Kubernetes Clusters

After deploying the control panel, you can use it to manage remote Kubernetes clusters:

1. Access the web interface at your configured domain
2. Navigate to Servers → Create Server
3. Add your Kubernetes cluster details with SSH credentials
4. Deploy customer applications to managed Kubernetes clusters

Docker Deployment (Legacy)

For development or legacy deployments, use Docker Compose:

1. Clone the repository and switch to the project directory:

git clone https://github.com/liberu-control-panel/control-panel-laravel.git
cd control-panel-laravel

2. Copy the example environment and adjust the values you need:

cp .env.example .env
# Edit .env: set CONTROL_PANEL_DOMAIN, LETSENCRYPT_EMAIL, DB credentials, etc.

3. Start the services (build on first run):

docker compose up -d --build

4. (Optional) Run database migrations and seeders inside the main app container:

docker compose exec control-panel php artisan migrate --force
docker compose exec control-panel php artisan db:seed --class=DatabaseSeeder

5. Open your browser at http://localhost (or the domain set in CONTROL_PANEL_DOMAIN).

Database Backend Options

The control panel supports both MariaDB (default) and PostgreSQL as database backends:

MariaDB/MySQL (Default)

# Default - MariaDB starts automatically with docker-compose up
docker compose up -d

PostgreSQL (Optional)

# Start with PostgreSQL profile
docker compose --profile postgresql up -d

# Update .env file:
DB_CONNECTION=pgsql
DB_HOST=postgresql
DB_PORT=5432

The default configuration uses MariaDB 11.2. To switch to PostgreSQL, use the --profile postgresql flag and update your .env file accordingly.

Standalone DNS Only Deployment

For lightweight DNS cluster nodes, use the Standalone DNS Only installation option:

# Clone the repository
git clone https://github.com/liberu-control-panel/control-panel-laravel.git
cd control-panel-laravel

# Run the unified installer
sudo ./install.sh
# Select option 4: Standalone DNS Only

Features:

• Choice between BIND9 (default, stable) or PowerDNS (modern, API-enabled)
• DNS cluster configuration (Master/Slave/Both)
• Nameserver hostname setup
• Zone transfer (AXFR) configuration
• Minimal resource footprint

Perfect for:

• DNS cluster nodes (primary, secondary, tertiary nameservers)
• Distributed nameserver infrastructure
• Geographic DNS redundancy
• Lightweight DNS-only servers

Post-Installation:

• Configure DNS zones via BIND9 zone files or PowerDNS API
• Set up zone transfers between cluster nodes
• Update domain registrar with nameserver details
• Configure firewall to allow DNS traffic (port 53 UDP/TCP)

Notes

• The setup.sh script in the repo automates build + migrations + seeding for supported environments.
• For development using Laravel Sail follow Sail's instructions (see repository docs).

Documentation

Installation & Getting Started

• Installation Guide - ⭐ START HERE: Unified installation guide for all deployment methods
• Quick Start Guide - Quick start guide for new features

Infrastructure & Deployment

• Multi-Deployment & Auto-Scaling Guide - Support for Kubernetes, Docker, and Standalone deployments with cloud auto-scaling
• Complete Kubernetes Installation - Full installation guide for Kubernetes cluster and all services
• Managed Kubernetes Setup - Deploy on AWS EKS, Azure AKS, Google GKE, or DigitalOcean DOKS
• Load Balancing Guide - Advanced load balancing configurations for NGINX Ingress and AWS EKS
• Storage Class Selection Guide - ⭐ NEW: Choose the right storage for managed Kubernetes platforms
• S3 Storage Guide - Configure S3-compatible storage for persistent volumes
• Nginx Configuration Guide - ⭐ NEW: Production-ready nginx setup with security and performance
• Helm GUI Installer - Graphical interface for installing services via Helm charts
• Kubernetes Setup Guide - Deploy control panel on existing Kubernetes cluster
• Kubernetes Manifests - Raw Kubernetes manifests and Kustomize overlays
• Helm Chart - Helm chart for easy deployment
• Mail Services - Postfix and Dovecot mail services
• DNS Cluster - PowerDNS DNS cluster setup
• PHP Multi-Version - PHP 8.1-8.5 multi-version support

Application Deployment

• WordPress Auto-Deployment - Install and manage WordPress sites with one-click deployment
• Git Repository Deployment - Deploy applications from GitHub, GitLab, Bitbucket, or any Git repository

Security & Configuration

• SSH Configuration Guide - Configure secure SSH connections
• Security Best Practices - Essential security guidelines
• Makefile Reference - Common deployment commands

Deployment Architecture

Control Panel on Kubernetes

When deployed on Kubernetes, the control panel uses this architecture:

┌─────────────────────────────────────────┐
│           Ingress (TLS)                 │
│  control-panel.yourdomain.com           │
└────────────┬────────────────────────────┘
             │
┌────────────▼────────────────────────────┐
│        Control Panel Service            │
└────────────┬────────────────────────────┘
             │
┌────────────▼────────────────────────────┐
│   Control Panel Deployment (2-10 pods)  │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │   NGINX      │  │   PHP-FPM       │ │
│  │   (Alpine)   │  │  (Laravel App)  │ │
│  └──────────────┘  └─────────────────┘ │
└─────────┬───────────────────┬───────────┘
          │                   │
    ┌─────▼──────┐     ┌─────▼──────┐
    │   Redis    │     │   MySQL    │
    │  (Cache)   │     │ StatefulSet│
    └────────────┘     └────────────┘

Managing Remote Kubernetes Clusters

Control Panel (Laravel Application)
    │ SSH Connection (Encrypted)
    ▼
Remote Kubernetes Server
├── Namespace: hosting-example-com
│   ├── Deployment: NGINX + PHP-FPM
│   ├── Service: Load balancer
│   ├── Ingress: TLS termination
│   ├── PVC: Persistent storage
│   ├── StatefulSet: Database (MySQL/PostgreSQL)
│   └── Security: RBAC + NetworkPolicy

Security Layers

1. SSH Layer: Encrypted connections with key-based or password authentication
2. Kubernetes RBAC: Namespace isolation and limited privileges
3. NetworkPolicies: Traffic segmentation between services
4. Resource Quotas: Prevent resource exhaustion
5. Pod Security: Run as non-root, drop capabilities
6. Secrets Management: Encrypted credential storage

Makefile Commands

The project includes a Makefile for common Kubernetes operations:

make help           # Show all available commands
make deploy-dev     # Deploy to development environment
make deploy-prod    # Deploy to production environment
make validate       # Validate Kubernetes manifests
make status         # Check deployment status
make logs           # View application logs
make migrate        # Run database migrations
make seed           # Seed database
make shell          # Open shell in application pod
make helm-install   # Install using Helm chart
make helm-upgrade   # Upgrade Helm release
make clean          # Remove deployment

Example workflow:

# Deploy to production
make deploy-prod

# Check status
make status

# Run migrations
make migrate

# View real-time logs
make logs

Our projects

The Liberu ecosystem contains a number of companion repositories and packages that extend or demonstrate functionality used in this boilerplate. Below is a concise, professional list of those projects with quick descriptions — follow the links to learn more or to contribute.

Project	Repository	Short description
Accounting	liberu-accounting/accounting-laravel	Accounting and invoicing features tailored for Laravel applications.
Automation	liberu-automation/automation-laravel	Automation tooling and workflow integrations for Laravel projects.
Billing	liberu-billing/billing-laravel	Subscription and billing management integrations (payments, invoices).
Boilerplate (core)	liberusoftware/boilerplate	Core starter and shared utilities used across Liberu projects.
Browser Game	liberu-browser-game/browser-game-laravel	Example Laravel-based browser game platform and mechanics.
CMS	liberu-cms/cms-laravel	Content management features and modular page administration.
Control Panel	liberu-control-panel/control-panel-laravel	Administration/control-panel components for managing services.
CRM	liberu-crm/crm-laravel	Customer relationship management features and integrations.
E‑commerce	liberu-ecommerce/ecommerce-laravel	E‑commerce storefront, product and order management.
Genealogy	liberu-genealogy/genealogy-laravel	Family tree and genealogy features built on Laravel.
Maintenance	liberu-maintenance/maintenance-laravel	Scheduling, tracking and reporting for maintenance tasks.
Real Estate	liberu-real-estate/real-estate-laravel	Property listings and real-estate management features.
Social Network	liberu-social-network/social-network-laravel	Social features, profiles, feeds and messaging for Laravel apps.

If you maintain or use one of these projects and would like a more detailed description or a different categorisation, open an issue or submit a pull request and we'll update the list. Contributions and cross-repo collaboration are warmly encouraged.

Contributing

Contributions are welcome. Please open issues for bugs or feature requests, and submit pull requests from a feature branch. Ensure CI passes and include tests for new behavior where appropriate. For larger changes, open a short proposal issue first.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Where to get help

• Use GitHub Issues for bugs and feature requests.
• For direct support or urgent questions, contact the maintainers via the project site: https://liberu.co.uk

Acknowledgements

Thanks to contributors and the open-source community. See the contributors graph below.