tfgrid/myceliumcloud-examples

Fork 0

Files

mik-tf d116c641fe feat: Add complete nginx static site example with deployment, service, and documentation

2025-11-04 12:02:02 -05:00

8.7 KiB

Raw Permalink Blame History

Mycelium Cloud - Nginx Static Site Example

A complete, standalone example for deploying a static website using Nginx on Mycelium Cloud Kubernetes cluster.

📁 What This Contains

This directory contains everything you need to deploy a static website:

nginx-static.md - This guide
nginx-static-deployment.yaml - Nginx deployment with custom content
nginx-static-service.yaml - Service configuration
default-index.html - Default website content (used to create ConfigMap)

🚀 Quick Start (2 minutes)

# 1. Deploy the application
kubectl apply -f nginx-static-deployment.yaml

# 2. Create ConfigMap with default content
kubectl create configmap nginx-static-content --from-file=index.html=default-index.html

# 3. Create the service
kubectl apply -f nginx-static-service.yaml

# 3. Access your static site via port-forward

**Option 1: Simple (Recommended)**
```bash
# Keep terminal open, see connection logs (Ctrl+C to stop)
kubectl port-forward service/nginx-static-service 8080:80

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/nginx-static-service 8080:80 > /dev/null 2>&1 &

# Kill when done
lsof -ti:8080 | xargs kill -9

4. Visit http://localhost:8080

curl http://localhost:8080


**Expected Result:** You'll see a custom static website served by Nginx.

## 📋 What You'll Learn

- ✅ Nginx container deployment
- ✅ Static content serving
- ✅ ConfigMap usage for custom HTML
- ✅ Service creation and networking
- ✅ Port-forwarding for external access (Mycelium Cloud method)
- ✅ Basic nginx configuration patterns

## 🏗️ Architecture

This example demonstrates:

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ User │ │ Port-Forward │ │ Nginx │ │ (Browser) │────│ localhost:8080 │────│ Pod │ │ │ │ │ │ :80 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ┌───────────────┐ │ ConfigMap │ │ (HTML/CSS) │ └───────────────┘


**Components:**
- **Nginx Pod**: Serves static content from /usr/share/nginx/html
- **ConfigMap**: Stores custom HTML, CSS, and other static files
- **Service**: LoadBalancer exposing the nginx pod
- **Port-Forward**: Mycelium Cloud method for external access

## 📊 Resource Details

```bash
# Expected output
kubectl get pods
NAME                           READY   STATUS    RESTARTS   AGE
nginx-static-xxxxxx-xxxxx      1/1     Running   0          2m

kubectl get svc
NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP              PORT(S)
nginx-static-service   LoadBalancer   10.43.xx.x      10.20.x.x,10.20.x.x      80:xxxxx/TCP

🔧 Customization Guide

Change the Content

Create a custom ConfigMap with your content:

# Create your custom HTML file
cat << EOF > custom-index.html
<!DOCTYPE html>
<html>
<head>
    <title>My Custom Site</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .container { max-width: 800px; margin: 0 auto; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Welcome to My Static Site</h1>
        <p>This site is running on Mycelium Cloud!</p>
        <p>Current time: $(date)</p>
    </div>
</body>
</html>
EOF

# Create ConfigMap with custom content
kubectl create configmap nginx-static-content \
  --from-file=index.html=custom-index.html

# Update deployment to use the new ConfigMap
kubectl apply -f nginx-static-deployment.yaml

Add More Static Files

Create additional ConfigMaps for CSS, JavaScript, or images:

# Add a stylesheet
cat << EOF > custom.css
body {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}
h1 { text-align: center; margin-top: 100px; }

# Create ConfigMap with multiple files
kubectl create configmap nginx-static-content \
  --from-file=index.html=custom-index.html \
  --from-file=styles.css=custom.css

🚪 Access Methods

Method 1: Port-Forward (Recommended for Mycelium Cloud)

Option 1: Simple (Recommended)

# Keep terminal open, see connection logs (Ctrl+C to stop)
kubectl port-forward service/nginx-static-service 8080:80

# Access via browser or curl
curl http://localhost:8080

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/nginx-static-service 8080:80 > /dev/null 2>&1 &

# Access via browser or curl
curl http://localhost:8080

Why this works in Mycelium Cloud:

LoadBalancer external IPs are internal cluster addresses
Port-forward creates local tunnel to cluster service
Reliable and consistent access method

Method 2: LoadBalancer (For Reference)

Note: In Mycelium Cloud, LoadBalancer external IPs (like 10.20.x.x) are internal cluster IPs and not externally accessible. Use port-forward for external access.

🗑️ Resource Cleanup

# Remove all resources
kubectl delete -f nginx-static-deployment.yaml -f nginx-static-service.yaml

# Remove the ConfigMap
kubectl delete configmap nginx-static-content

# Verify cleanup
kubectl get all -l app=nginx-static  # Should return nothing

🔍 Troubleshooting

Pod Won't Start

# Check pod status
kubectl get pods -l app=nginx-static

# Check pod logs
kubectl logs deployment/nginx-static

# Check pod events
kubectl describe pod -l app=nginx-static

Site Not Loading

# Check service endpoints
kubectl get endpoints nginx-static-service

# Check if port-forward is working
kubectl port-forward service/nginx-static-service 8081:80 &
curl -v http://localhost:8081

Custom Content Not Showing

# Verify ConfigMap content
kubectl get configmap nginx-static-content -o yaml

# Check if files are mounted correctly
kubectl exec -it deployment/nginx-static -- ls -la /usr/share/nginx/html/

# Reload nginx to pick up changes
kubectl exec -it deployment/nginx-static -- nginx -s reload

Port Forward Fails

# Check if port is in use
lsof -i :8080

# Try different port
kubectl port-forward service/nginx-static-service 8082:80
curl http://localhost:8082

📚 More Examples

This is currently one of the complete examples. Future examples will include:

python-flask/ - Python web applications
redis-cache/ - In-memory data caching
postgresql/ - Persistent database services
wordpress/ - Multi-container CMS deployment
nodejs-api/ - Modern JavaScript applications
jenkins-cicd/ - Infrastructure automation
nextcloud/ - Enterprise file sharing

💡 Pro Tips

Start Simple: Begin with foreground port-forward (kubectl port-forward)
Background Optional: Use nohup only when you need persistent port-forwards
Port Management: Use lsof -ti:PORT to find and kill processes
Resource Monitoring: kubectl get pods -o wide shows pod distribution
Quick Testing: curl -s http://localhost:8080 to verify nginx is working
Nginx Logs: kubectl logs deployment/nginx-static for debugging
Config Updates: Update ConfigMap then reload nginx: kubectl exec deployment/nginx-static -- nginx -s reload

🎉 Success Indicators

You'll know everything is working when:

✅ kubectl get pods shows nginx-static pod in "Running" status
✅ kubectl get svc shows nginx-static-service created
✅ curl http://localhost:8080 returns your custom HTML content
✅ kubectl logs deployment/nginx-static shows nginx access logs

🏆 Next Steps

After completing this example, you can:

Customize Content: Replace with your own static site
Add More Examples: Try the Python Flask API example
Scale Up: Learn about load balancing with multiple replicas
Add Persistence: Learn about persistent volumes for file storage

📞 Getting Help

Troubleshooting: Check the troubleshooting section above
Mycelium Cloud Docs: See main repository README
Kubectl Help: kubectl get pods --help for command reference
Support: Contact Mycelium Cloud support team

For more help, visit our documentation or contact support.

8.7 KiB Raw Permalink Blame History