feat: Add comprehensive WordPress example with multi-container deployment and documentation

This commit is contained in:
mik-tf
2025-11-09 00:59:37 -05:00
parent 59a662ac1e
commit a356271d8b
5 changed files with 1017 additions and 6 deletions

View File

@@ -0,0 +1,540 @@
# Mycelium Cloud - WordPress Example
A complete, production-ready example for deploying a WordPress CMS with MariaDB database on Mycelium Cloud Kubernetes cluster. Features multi-container pod architecture, persistent storage, and comprehensive WordPress management patterns.
## 📁 What This Contains
This directory contains everything you need to deploy a WordPress CMS system:
- **wordpress.md** - This comprehensive guide
- **wordpress-deployment.yaml** - Multi-container pod deployment (WordPress + MariaDB)
- **wordpress-service.yaml** - LoadBalancer service configuration
- **wordpress-configmap.yaml** - WordPress configuration, Apache config, and initialization scripts
## 🚀 Quick Start (3 minutes)
```bash
# 1. Deploy WordPress stack (ConfigMaps, PVCs, Deployment, Service)
kubectl apply -f wordpress-configmap.yaml
kubectl apply -f wordpress-deployment.yaml
kubectl apply -f wordpress-service.yaml
# 2. Wait for pods to be ready
kubectl wait --for=condition=ready pod -l app=wordpress --timeout=300s
# 3. Access WordPress
kubectl port-forward service/wordpress-service 8080:80 &
# 4. Visit WordPress setup
echo "🌐 Visit: http://localhost:8080"
```
**Expected Result:** WordPress installation page will appear, ready for initial setup and configuration.
## 📋 What You'll Learn
- ✅ Advanced Kubernetes patterns (multi-container pods, init containers)
- ✅ WordPress deployment and configuration
- ✅ MariaDB database deployment with persistent storage
- ✅ ConfigMap usage for application configuration
- ✅ LoadBalancer services on Mycelium Cloud
- ✅ PersistentVolume claims for data persistence
- ✅ Init container patterns for database initialization
- ✅ Production WordPress management
- ✅ Resource limits and container orchestration
- ✅ Health checks for both web and database services
## 🏗️ Architecture
This example uses a **multi-container pod pattern** with **persistent storage** and **init containers**:
**Network Flow:**
```
kubectl port-forward → LoadBalancer Service → Pod (wordpress + mariadb)
```
**Multi-Container Architecture:**
- **wordpress**: WordPress 6.4 with PHP 8.2 and Apache (port 80)
- **mariadb**: MariaDB 10.11 database server (port 3306)
- **init-mariadb**: Init container for database setup
- **init-wordpress**: Init container for WordPress configuration
- **PersistentVolumes**: Database and WordPress content storage
## 🔧 Files Explanation
### wordpress-deployment.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: wordpress
spec:
replicas: 1
selector:
matchLabels:
app: wordpress
template:
metadata:
labels:
app: wordpress
spec:
# Worker node preference (like nginx-nodeport)
affinity:
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
preference:
matchExpressions:
- key: node-role.kubernetes.io/master
operator: DoesNotExist
containers:
- name: wordpress
image: wordpress:6.4-php8.2-apache
ports:
- containerPort: 80
env:
- name: WORDPRESS_DB_HOST
value: "localhost"
# ... WordPress environment variables
- name: mariadb
image: mariadb:10.11
ports:
- containerPort: 3306
env:
- name: MARIADB_ROOT_PASSWORD
value: "mycelium-root-password-2025"
# ... MariaDB environment variables
initContainers:
- name: init-mariadb
# Database initialization
- name: init-wordpress
# WordPress setup
```
**What it does:**
- Creates multi-container pod with WordPress + MariaDB
- ConfigMap mounts for configuration and initialization scripts
- PersistentVolume claims for database and content storage
- Init containers for database and WordPress setup
- Resource limits for both containers
- Worker node preference for production deployments
### wordpress-service.yaml
```yaml
apiVersion: v1
kind: Service
metadata:
name: wordpress-service
spec:
selector:
app: wordpress
ports:
- name: wordpress
port: 80
targetPort: 80
type: LoadBalancer
ipFamilies:
- IPv4
- IPv6
ipFamilyPolicy: RequireDualStack
```
**What it does:**
- Creates LoadBalancer service for Mycelium Cloud
- Exposes WordPress port 80
- Dual-stack (IPv4 + IPv6) support
- Routes traffic to multi-container pod
### wordpress-configmap.yaml
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: wordpress-config
data:
wp-config.php: |
<?php
define('DB_NAME', 'wordpress');
define('DB_USER', 'wordpress');
define('DB_PASSWORD', 'mycelium-secure-password-2025');
# ... WordPress configuration
wordpress.conf: |
<VirtualHost *:80>
# ... Apache configuration
init-wordpress.sh: |
#!/bin/bash
# WordPress initialization script
```
**What it does:**
- WordPress configuration (wp-config.php)
- Apache virtual host configuration
- Database initialization scripts
- WordPress setup automation
## 🌐 Access Methods
### Method 1: Port-Forward (Recommended for Mycelium Cloud)
**Option 1: Simple (Recommended)**
```bash
# Keep terminal open, forward WordPress port
kubectl port-forward service/wordpress-service 8080:80
# Access WordPress setup
curl http://localhost:8080
```
**Option 2: Background**
```bash
# Start in background
nohup kubectl port-forward service/wordpress-service 8080:80 > wordpress-access.log 2>&1 &
# Access WordPress
curl http://localhost:8080
```
### Method 2: Direct Pod Access (Inside Cluster)
**WordPress CLI Access:**
```bash
# Execute WordPress commands
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- wp --allow-root --info
# Access WordPress shell
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- /bin/bash
```
**Database Access:**
```bash
# Access MariaDB
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- mysql -u root -p"mycelium-root-password-2025"
# WordPress database access
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- mysql -u wordpress -p"mycelium-secure-password-2025" wordpress
```
### Method 3: LoadBalancer IP Access (If Available)
```bash
# Get LoadBalancer IP (may be internal on Mycelium Cloud)
kubectl get svc wordpress-service
# Access WordPress (if external IP available)
curl http://<external-ip>:80
```
## 📊 WordPress Management
### Initial Setup
1. **Visit WordPress Setup**: http://localhost:8080
2. **Choose Language**: Select your preferred language
3. **Site Configuration**:
- Site Title: "Mycelium Cloud WordPress"
- Username: "admin" (or your choice)
- Password: Generate secure password
- Email: Your email address
4. **Complete Setup**: WordPress will create database tables and configure
### WordPress CLI Management
```bash
# Install WordPress CLI in pod
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/master/phar/wp-cli.phar && \
chmod +x wp-cli.phar
# Basic WordPress operations
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root --info
# List plugins
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root plugin list
# Install theme
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root theme install twentytwentyfour
```
### Database Operations
```bash
# Access WordPress database
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysql -u wordpress -p"mycelium-secure-password-2025" wordpress -e "SHOW TABLES;"
# Check WordPress users
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysql -u wordpress -p"mycelium-secure-password-2025" wordpress -e "SELECT * FROM wp_users;"
# Database backup
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysqldump -u wordpress -p"mycelium-secure-password-2025" wordpress > wordpress-backup.sql
```
## 🔍 Troubleshooting
### Check Deployment Status
```bash
# Check pods status (should show 2/2 Ready)
kubectl get pods -l app=wordpress
# Check service details
kubectl get svc wordpress-service
# Check PersistentVolumeClaims
kubectl get pvc wordpress-database-pvc wordpress-content-pvc
# Check ConfigMaps
kubectl get configmap wordpress-config wordpress-mariadb-config
```
### Common Issues
#### Pod Not Starting
```bash
# Check pod status and events
kubectl describe pod -l app=wordpress
# Check container logs
kubectl logs -l app=wordpress
kubectl logs -l app=wordpress -c wordpress
kubectl logs -l app=wordpress -c mariadb --previous
```
#### Database Connection Issues
```bash
# Check MariaDB connectivity from WordPress container
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
mysqladmin ping -h localhost -u wordpress -p"mycelium-secure-password-2025"
# Test database access
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysql -u root -p"mycelium-root-password-2025" -e "SHOW DATABASES;"
```
#### WordPress Installation Issues
```bash
# Check WordPress configuration
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
cat /var/www/html/wp-config.php
# Check WordPress directory permissions
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
ls -la /var/www/html/
# Test WordPress initialization
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
/init-wordpress.sh
```
#### Persistent Volume Issues
```bash
# Check PVC status
kubectl describe pvc wordpress-database-pvc
kubectl describe pvc wordpress-content-pvc
# Check volume mount in containers
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
ls -la /var/lib/mysql/
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
ls -la /var/www/html/
```
#### Port Conflicts
```bash
# Check if port 8080 is in use
lsof -i :8080
# Check port 80 conflicts
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
netstat -tlnp | grep :80
```
## 🛠️ Common Operations
### Scaling (Note: WordPress scaling is complex)
```bash
# Note: WordPress is typically single-instance due to file-based sessions
# For horizontal scaling, you'd need shared storage and session management
kubectl scale deployment wordpress --replicas=1
# Check distribution
kubectl get pods -o wide
```
### Updates
```bash
# Update WordPress image
kubectl set image deployment/wordpress wordpress=wordpress:6.5-php8.2-apache
# Update MariaDB image
kubectl set image deployment/wordpress mariadb=mariadb:11.0
# Restart deployment
kubectl rollout restart deployment/wordpress
# Check rollout status
kubectl rollout status deployment/wordpress
```
### Data Management
```bash
# Access WordPress database
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- mysql -u wordpress -p"mycelium-secure-password-2025" wordpress
# Common database operations inside pod:
# SHOW TABLES;
# DESCRIBE wp_posts;
# SELECT * FROM wp_options;
# FLUSH PRIVILEGES;
```
### Monitoring
```bash
# View logs from both containers
kubectl logs -f deployment/wordpress
kubectl logs -f deployment/wordpress -c wordpress
kubectl logs -f deployment/wordpress -c mariadb
# Monitor resource usage
kubectl top pod -l app=wordpress
# Check database status
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysqladmin -u root -p"mycelium-root-password-2025" status
```
## 🧹 Cleanup
When you're done testing:
```bash
# Delete the application and service
kubectl delete -f wordpress-deployment.yaml -f wordpress-service.yaml -f wordpress-configmap.yaml
# Wait for cleanup
kubectl wait --for=delete pod -l app=wordpress --timeout=60s
# Kill any port-forwards
lsof -ti:8080 | xargs kill -9 2>/dev/null || true
# Verify cleanup
kubectl get all -l app=wordpress
kubectl get pvc wordpress-database-pvc wordpress-content-pvc 2>/dev/null || echo "PVCs deleted"
kubectl get configmap wordpress-config wordpress-mariadb-config 2>/dev/null || echo "ConfigMaps deleted"
```
## 🎯 What This Demonstrates
This example shows:
- **Advanced Kubernetes patterns** - multi-container pods, init containers, persistent volumes
- **Production WordPress deployment** - proper configuration, security, performance
- **Database integration** - MariaDB setup, persistent storage, initialization
- **Mycelium Cloud networking** - LoadBalancer services, port-forwarding, dual-stack
- **Container orchestration** - resource management, health monitoring, init containers
- **Development workflows** - testing, debugging, configuration management
- **Production patterns** - worker node preferences, scaling considerations
## 🔗 Next Steps
Once you understand this example, try:
1. **WordPress Clustering** - Multiple WordPress instances with shared database
2. **Advanced Scaling** - Load balancing, shared storage, session management
3. **WordPress Multisite** - Multiple WordPress sites on one deployment
4. **Plugin Management** - Automated plugin/theme deployment
5. **Backup Strategies** - Database and file backups
6. **Security Hardening** - SSL/TLS, security headers, access controls
7. **Performance Optimization** - Caching, CDN integration
8. **Monitoring** - WordPress performance and database monitoring
## 📚 More Examples
Other available examples:
- **hello-world/** - Basic web application deployment
- **nginx-static/** - Static website hosting
- **python-flask/** - Python API server
- **redis-cache/** - Data caching services
- **nginx-nodeport/** - NodePort scaling with workers
## 💡 Pro Tips
1. **Multi-Container Access**: Use `-c container-name` to access specific containers
2. **Init Containers**: Check init container logs for setup issues
3. **WordPress CLI**: Great for automated WordPress management
4. **Database Backup**: Always backup before major changes
5. **Resource Monitoring**: Watch memory usage, especially during WordPress operations
6. **Network Testing**: Use `kubectl exec` for internal cluster testing
7. **Background Services**: Use `&` to run multiple port-forwards
8. **Persistent Storage**: Verify PVC mounting for data persistence
## 🔧 WordPress-Specific Tips
### Plugin Management
```bash
# List installed plugins
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root plugin list
# Install popular plugins
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root plugin install seo yoast-seo contact-form-7
```
### Theme Management
```bash
# List installed themes
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root theme list
# Install and activate theme
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root theme install twentytwentyfour --activate
```
### Content Management
```bash
# Create sample post
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c wordpress -- \
./wp-cli.phar --allow-root post create --post_type=post --post_title="Welcome to Mycelium Cloud WordPress" --post_content="This is a sample post deployed on Mycelium Cloud!" --post_status=publish
```
### Database Maintenance
```bash
# Optimize database tables
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysql -u wordpress -p"mycelium-secure-password-2025" wordpress -e "OPTIMIZE TABLE wp_posts, wp_options;"
# Check database size
kubectl exec -it $(kubectl get pod -l app=wordpress -o jsonpath='{.items[0].metadata.name}') -c mariadb -- \
mysql -u wordpress -p"mycelium-secure-password-2025" wordpress -e "SELECT table_schema AS 'Database', ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS 'Size (MB)' FROM information_schema.tables WHERE table_schema = 'wordpress' GROUP BY table_schema;"
```
## 🎉 Success Indicators
You'll know everything is working when:
-`kubectl get pods` shows "2/2 Running" for wordpress pod
-`kubectl get svc` shows wordpress-service with LoadBalancer type
-`kubectl get pvc` shows both PVCs as "Bound"
-`curl http://localhost:8080` returns WordPress installation page
- ✅ Database initialization completes without errors
- ✅ WordPress setup wizard can be accessed and completed
- ✅ No errors in `kubectl get events`
**Congratulations! You've successfully deployed a production-ready WordPress CMS system on Mycelium Cloud! 🚀**
---
## 🆘 Support
If you encounter issues:
1. Check the troubleshooting section above
2. Verify your kubeconfig is set correctly: `kubectl get nodes`
3. Ensure your cluster is healthy: `kubectl get pods --all-namespaces`
4. Check WordPress logs: `kubectl logs -l app=wordpress -c wordpress`
5. Check MariaDB logs: `kubectl logs -l app=wordpress -c mariadb`
6. Verify PersistentVolumeClaim status: `kubectl get pvc`
7. Test WordPress functionality via browser at http://localhost:8080
For more help, visit our [documentation](../../README.md) or contact support.