tfgrid/myceliumcloud-examples
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
61a911649b94663ebf27e4e8b2cb506084bca490
myceliumcloud-examples/examples/nginx-mycelium/nginx-mycelium.md

434 lines
12 KiB
Markdown
Raw Blame History

# Mycelium Cloud - Nginx with IPv6 Website Hosting
A complete, production-ready example for deploying a globally accessible website on Mycelium Cloud using IPv6 networking. This demonstrates **peer-to-peer web hosting** without traditional hosting infrastructure.
## 📁 What This Contains
This directory contains everything you need to deploy a professional website with global IPv6 accessibility:
- **nginx-mycelium.md** - This comprehensive guide
- **mycelium-website-nodeport.yaml** - Complete deployment configuration
- **test-ipv6-website.sh** - IPv6 testing and verification script
- **update-content.sh** - Content update script (for future use)
## 🚀 Quick Start (3 minutes)
```bash
# 1. Deploy the website
kubectl apply -f mycelium-website-nodeport.yaml
# 2. Wait for deployment to be ready
kubectl wait --for=condition=ready pod -l app=mycelium-website --timeout=60s
# 3. Get your IPv6 address
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | head -1
# 4. Access your website globally
# Use the IPv6 address from step 3, replace [YOUR-IPV6] below:
curl -6 "http://[YOUR-IPV6]:8080/"
```
**Expected Result:** You'll see a professional website with gradient styling and IPv6 address detection.
## 📋 What You'll Learn
- ✅ IPv6-only web hosting on Mycelium Cloud
- ✅ Production nginx configuration with dual-stack support
- ✅ ConfigMap-based content management
- ✅ Global accessibility via peer-to-peer networking
- ✅ hostNetwork deployment patterns
- ✅ IPv6 troubleshooting and verification
## 🏗️ Architecture
This example uses a **single-file approach** with integrated components:
1. **Deployment** - Pod with nginx and custom content
2. **ConfigMaps** - HTML content and nginx configuration
3. **Service** - NodePort for external accessibility
**Network Flow:** `Direct IPv6 → nginx:8080 → Custom HTML`
**Key Innovation:** Uses `hostNetwork: true` for direct access to Mycelium IPv6 interfaces.
## 🔧 Files Explanation
### mycelium-website-nodeport.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mycelium-website
spec:
replicas: 1
template:
spec:
hostNetwork: true # Direct IPv6 access
containers:
- name: nginx
image: nginx:alpine
ports:
- containerPort: 8080
hostPort: 8080
volumeMounts:
- name: html-content
mountPath: /usr/share/nginx/html
- name: nginx-config
mountPath: /etc/nginx/conf.d
volumes:
- name: html-content
configMap:
name: mycelium-website-content
- name: nginx-config
configMap:
name: mycelium-nginx-config
```
**What it does:**
- Creates 1 pod with nginx and custom website content
- Uses `hostNetwork: true` for direct IPv6 interface access
- Includes ConfigMaps for dynamic content management
- Dual-stack nginx (IPv4 + IPv6) configuration
## 🌐 Access Methods
### Method 1: Direct IPv6 (Primary - Recommended)
```bash
# Get your pod's IPv6 address
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
IPV6=$(kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | head -1 | awk '{print $2}' | cut -d'/' -f1)
# Access your website
curl -6 "http://[$IPV6]:8080/"
curl -6 "http://[$IPV6]:8080/health"
# Or in browser: http://[YOUR-IPV6]:8080/
```
**Why this works:**
- `hostNetwork: true` gives direct access to host IPv6 interfaces
- nginx listens on both IPv4 and IPv6
- Mycelium provides globally routable IPv6 addresses
- No port translation or proxy needed
### Method 2: Health Check Verification
```bash
# Test health endpoint
curl -6 "http://[YOUR-IPV6]:8080/health"
# Expected: "healthy"
# Test main page (should return 3975+ bytes)
curl -6 "http://[YOUR-IPV6]:8080/" | wc -c
# Expected: 3975 (or similar large number)
```
### Method 3: Interactive Testing
```bash
# Keep testing connection
watch -n 2 'curl -6 -s "http://[YOUR-IPV6]:8080/health" && echo " - $(date)"'
```
## 🔍 Troubleshooting
### Check Deployment Status
```bash
# Check if pods are running
kubectl get pods -l app=mycelium-website
# Check service details
kubectl get svc mycelium-website-service
# Check what's deployed
kubectl get all -l app=mycelium-website
# Verify nginx is listening on both IPv4 and IPv6
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
kubectl exec $POD_NAME -- netstat -tuln | grep 8080
```
### Common Issues
#### IPv6 Binding Problems
```bash
# Problem: nginx only listening on IPv4
# Check current binding:
kubectl exec $POD_NAME -- netstat -tuln | grep 8080
# Should show:
# tcp 0 0 0.0.0.0:8080 0.0.0.0:* LISTEN
# tcp 0 0 :::8080 :::* LISTEN (IPv6)
# If missing IPv6, restart the deployment:
kubectl delete pod $POD_NAME
```
#### Pod Not Starting
```bash
# Check pod status and events
kubectl describe pod -l app=mycelium-website
# Check pod logs
kubectl logs -l app=mycelium-website
# Check nginx configuration
kubectl exec $POD_NAME -- cat /etc/nginx/conf.d/default.conf
```
#### IPv6 Not Accessible
```bash
# Verify IPv6 address exists
kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:"
# Test IPv6 connectivity
ping6 [YOUR-IPV6]
# Test nginx inside pod
kubectl exec $POD_NAME -- curl -s http://localhost:8080/health
```
#### Content Not Loading
```bash
# Verify ConfigMaps are mounted
kubectl exec $POD_NAME -- ls -la /usr/share/nginx/html/
# Check actual content
kubectl exec $POD_NAME -- cat /usr/share/nginx/html/index.html | head -10
# Verify nginx config is loaded
kubectl exec $POD_NAME -- nginx -t
```
## 🛠️ Common Operations
### Updating Website Content
```bash
# Update the ConfigMap with new HTML content
kubectl create configmap mycelium-website-content \
--from-file=index.html=./new-website.html \
--dry-run=client -o yaml | kubectl apply -f -
# Restart pod to pick up changes
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
kubectl delete pod $POD_NAME
```
### Scaling
```bash
# Scale to 2 replicas (each gets different IPv6)
kubectl scale deployment mycelium-website --replicas=2
# Check distribution across nodes
kubectl get pods -o wide -l app=mycelium-website
```
### Monitoring
```bash
# View nginx logs
kubectl logs -f deployment/mycelium-website
# Check resource usage
kubectl top pod -l app=mycelium-website
# Monitor IPv6 addresses
watch 'kubectl get pods -o wide -l app=mycelium-website'
```
### IPv6 Address Discovery
```bash
# Get all IPv6 addresses for the website pod
POD_NAME=$(kubectl get pods -l app=mycelium-website -o name | head -1)
kubectl exec $POD_NAME -- ip addr show | grep "inet6" | grep "scope global"
# Test multiple IPv6 addresses
for ipv6 in $(kubectl exec $POD_NAME -- ip addr show | grep "476:\|51d:\|552:" | awk '{print $2}' | cut -d'/' -f1); do
echo "Testing IPv6: $ipv6"
curl -6 -m 2 "http://[$ipv6]:8080/health" && echo " - SUCCESS" || echo " - FAILED"
done
```
## 🧹 Cleanup
When you're done testing:
```bash
# Delete the entire deployment
kubectl delete -f mycelium-website-nodeport.yaml
# Verify cleanup
kubectl get all -l app=mycelium-website
# Remove any lingering ConfigMaps (optional)
kubectl delete configmap mycelium-website-content mycelium-nginx-config
```
## 🎯 What This Demonstrates
This example shows:
- **IPv6-Only Web Hosting** - Complete website delivery via peer-to-peer networking
- **Production nginx Configuration** - Dual-stack (IPv4/IPv6) web server
- **Dynamic Content Management** - ConfigMaps for easy updates
- **Global Accessibility** - Direct IPv6 URL access worldwide
- **Kubernetes Best Practices** - Proper separation of concerns
## 🔗 Next Steps
Once you understand this example, try:
1. **SSL/HTTPS** - Add TLS termination for secure communications
2. **Custom Domains** - Integrate with Mycelium DNS services
3. **Multiple Applications** - Deploy several websites with load balancing
4. **Monitoring** - Add Prometheus/Grafana for observability
5. **CDN Integration** - Leverage Mycelium's distributed nature
## 📚 Advanced Features
### Custom nginx Configuration
```bash
# Edit nginx config
kubectl create configmap mycelium-nginx-config \
--from-file=default.conf=./custom-nginx.conf \
--dry-run=client -o yaml | kubectl apply -f -
# Restart to apply
kubectl rollout restart deployment/mycelium-website
```
### Multiple Website Support
```bash
# Deploy multiple websites (each gets unique IPv6)
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
name: mycelium-website-2
spec:
replicas: 1
selector:
matchLabels:
app: mycelium-website-2
template:
metadata:
labels:
app: mycelium-website-2
spec:
hostNetwork: true
containers:
- name: nginx
image: nginx:alpine
ports:
- containerPort: 8080
hostPort: 8081
EOF
```
## 💡 Pro Tips
1. **IPv6 First**: Always test IPv6 connectivity before troubleshooting
2. **Multiple Addresses**: Each pod gets unique IPv6 addresses - test them all
3. **Health Checks**: Use `/health` endpoint for automated monitoring
4. **Content Updates**: ConfigMaps enable zero-downtime content updates
5. **Resource Monitoring**: Watch pod distribution across nodes
6. **Network Testing**: Use `ping6` to test basic IPv6 connectivity
7. **Browser Testing**: Modern browsers support IPv6 - test in Chrome/Firefox
## 🎉 Success Indicators
You'll know everything is working when:
- ✅ `kubectl get pods` shows "Running" status
- ✅ IPv6 address is discoverable via `ip addr show`
- ✅ `curl -6 "http://[ipv6]:8080/"` returns complete HTML (3975+ bytes)
- ✅ `curl -6 "http://[ipv6]:8080/health"` returns "healthy"
- ✅ Browser can load the website at `http://[ipv6]:8080/`
**Congratulations! You've successfully deployed a globally accessible website on Mycelium Cloud! 🚀**
---
## 📊 Technical Specifications
### Network Configuration
- **Protocol**: IPv6 with IPv4 fallback
- **Port**: 8080 (internal), direct IPv6 access
- **Service**: NodePort 30090 (optional)
- **Access Method**: Direct IPv6 URLs
### Resource Requirements
- **CPU**: Minimal (nginx alpine)
- **Memory**: ~50MB
- **Storage**: ConfigMap-based content
- **Network**: IPv6-capable interfaces
### Performance Metrics
- **Response Time**: ~136ms typical
- **Content Size**: 3,975 bytes (full page)
- **Concurrent Connections**: nginx standard limits
- **Uptime**: Kubernetes-managed (99.9%+ expected)
## 🌍 Global Accessibility Proof
**Live Website Access:**
- **URL**: `http://[YOUR-IPV6]:8080/`
- **Health Check**: `http://[YOUR-IPV6]:8080/health`
- **Content**: Professional website with IPv6 detection
**What makes this globally accessible:**
- Mycelium provides globally routable IPv6 addresses
- Peer-to-peer networking eliminates traditional ISP dependencies
- Direct IPv6 URLs work from anywhere with IPv6 connectivity
- No DNS or traditional hosting infrastructure required
## 🆘 Support
If you encounter issues:
1. Check the troubleshooting section above
2. Verify your cluster is healthy: `kubectl get nodes`
3. Ensure IPv6 is working: `ping6 [YOUR-IPV6]`
4. Test pod networking: `kubectl exec $POD_NAME -- curl localhost:8080`
For more help, visit our [documentation](../../README.md) or contact support.
---
## 🔧 Advanced Troubleshooting
### Network Interface Analysis
```bash
# Analyze all network interfaces
kubectl exec $POD_NAME -- ip addr show
# Find Mycelium-specific interfaces
kubectl exec $POD_NAME -- ip addr show | grep -E "(476:|51d:|552:)"
# Check routing table
kubectl exec $POD_NAME -- ip -6 route show
```
### nginx Configuration Validation
```bash
# Test nginx configuration syntax
kubectl exec $POD_NAME -- nginx -t
# Reload nginx configuration
kubectl exec $POD_NAME -- nginx -s reload
# Check nginx status
kubectl exec $POD_NAME -- ps aux | grep nginx
```
### IPv6 Connectivity Testing
```bash
# Test from external IPv6 network
ping6 [YOUR-IPV6]
# Test specific port
nc -6 -zv [YOUR-IPV6] 8080
# Test HTTP endpoint
curl -6 -I "http://[YOUR-IPV6]:8080/"
```
This comprehensive guide ensures you can successfully deploy and access your IPv6 website on Mycelium Cloud!
Reference in New Issue View Git Blame Copy Permalink