myceliumcloud-examples/examples/nginx-mycelium/nginx-mycelium.md

# 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.

![nginx-mycelium-screenshot](./img/nginx-mycelium-screenshot.png)

## 📋 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!