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)

# 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

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)

# 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

# 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

# Keep testing connection
watch -n 2 'curl -6 -s "http://[YOUR-IPV6]:8080/health" && echo " - $(date)"'

🔍 Troubleshooting

Check Deployment Status

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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 or contact support.

---

🔧 Advanced Troubleshooting

Network Interface Analysis

# 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

# 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

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