myceliumcloud-examples/examples/hello-world/hello-world.md

Mycelium Cloud - Hello World Example

A complete, standalone example for deploying a Hello World web application on Mycelium Cloud Kubernetes cluster.

📁 What This Contains

This directory contains everything you need to deploy a simple web application:

• hello-world.md - This guide
• hello-world-deployment.yaml - Application deployment
• hello-world-service.yaml - Service configuration

🚀 Quick Start (2 minutes)

# 1. Deploy the application
kubectl apply -f hello-world-deployment.yaml

# 2. Create the service
kubectl apply -f hello-world-service.yaml

# 3. Access your app via port-forward

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

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/hello-world-service 8080:8080 > /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 the Hello Kubernetes webpage with pod information.

## 📋 What You'll Learn

- ✅ Basic Kubernetes deployment patterns
- ✅ Service creation and networking
- ✅ Port-forwarding for external access (Mycelium Cloud method)
- ✅ Troubleshooting common issues
- ✅ Resource management and cleanup

## 🏗️ Architecture

This example uses a **two-file approach** for clean separation:

1. **hello-world-deployment.yaml** - Contains the Pod/Deployment logic
2. **hello-world-service.yaml** - Contains the networking configuration

**Network Flow:** `kubectl port-forward → Service → Pod`

## 🔧 Files Explanation

### hello-world-deployment.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
      - name: hello-world
        image: paulbouwer/hello-kubernetes:1.10
        ports:
        - containerPort: 8080

What it does:

• Creates 1 pod with the Hello Kubernetes web app
• Uses image paulbouwer/hello-kubernetes:1.10
• Exposes port 8080

hello-world-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: hello-world-service
spec:
  selector:
    app: hello-world
  ports:
  - port: 8080
    targetPort: 8080
  type: LoadBalancer

What it does:

• Creates a service to expose the app
• LoadBalancer type (for Mycelium Cloud)
• Routes traffic to pods with label app: hello-world

🌐 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/hello-world-service 8080:8080

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

Option 2: Advanced (Background)

# Start in background
nohup kubectl port-forward service/hello-world-service 8080:8080 > /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 a local tunnel to the cluster
• Most reliable method for external access

Method 2: Local Port (Different Port)

# Forward to a different local port
kubectl port-forward service/hello-world-service 9000:8080

# Access at http://localhost:9000
curl http://localhost:9000

Method 3: Development Mode (Foreground)

# Keep terminal open, shows connection logs
kubectl port-forward service/hello-world-service 8080:8080

🔍 Troubleshooting

Check Deployment Status

# Check if pods are running
kubectl get pods -l app=hello-world

# Check service details
kubectl get svc hello-world-service

# Check what's deployed
kubectl get all -l app=hello-world

Common Issues

Port Already in Use

# Check what's using port 8080
lsof -i :8080

# Kill the process
kill -9 $(lsof -ti:8080)

Pod Not Starting

# Check pod status and events
kubectl describe pod -l app=hello-world

# Check pod logs
kubectl logs -l app=hello-world

Service Not Accessible

# Check service endpoints
kubectl get endpoints hello-world-service

# Test from within cluster
kubectl run test-curl --rm -it --image=curlimages/curl:8.7.1 -- \
  sh -lc 'curl http://hello-world-service:8080'

🛠️ Common Operations

Scaling

# Scale to 3 replicas
kubectl scale deployment hello-world --replicas=3

# Check distribution
kubectl get pods -o wide

Updates

# Update to a new image
kubectl set image deployment/hello-world hello-world=paulbouwer/hello-kubernetes:1.9

# Check rollout status
kubectl rollout status deployment/hello-world

Viewing Logs

# View logs from a specific pod
kubectl logs deployment/hello-world

# Follow logs in real-time
kubectl logs -f deployment/hello-world

🧹 Cleanup

When you're done testing:

# Delete the application and service
kubectl delete -f hello-world-deployment.yaml -f hello-world-service.yaml

# Kill any port-forwards
lsof -ti:8080 | xargs kill -9

# Verify cleanup
kubectl get all -l app=hello-world

🎯 What This Demonstrates

This example shows:

• Basic Kubernetes patterns - deployments and services
• Mycelium Cloud networking - port-forward access method
• Resource management - creating, monitoring, and cleaning up
• Troubleshooting skills - common issues and solutions
• Production readiness - proper separation of concerns

🔗 Next Steps

Once you understand this example, try:

1. Add ConfigMaps - Add configuration to your app
2. Use Secrets - Store sensitive data
3. Add Ingress - Multiple applications, proper routing
4. Resource Limits - CPU and memory constraints
5. Health Checks - Readiness and liveness probes

📚 More Examples

This is currently the only complete example. Future examples will include:

• python-server/ - Python HTTP servers with load balancing
• wordpress/ - WordPress deployment
• nextcloud/ - Nextcloud file sharing
• prometheus/ - Monitoring setup

💡 Pro Tips

1. Start Simple: Begin with foreground port-forward (kubectl port-forward)
2. Background Optional: Use nohup only when you need persistent port-forwards
3. Port Management: Use lsof -ti:PORT to find and kill processes
4. Resource Monitoring: kubectl get pods -o wide shows pod distribution
5. Quick Testing: curl -s http://localhost:8080 to verify app is working
6. Clean State: Always cleanup resources when done

🎉 Success Indicators

You'll know everything is working when:

• ✅ kubectl get pods shows "Running" status
• ✅ kubectl get svc shows service created
• ✅ curl http://localhost:8080 returns Hello Kubernetes webpage
• ✅ No errors in kubectl get events

Congratulations! You've successfully deployed your first application on Mycelium Cloud! 🚀

---

📖 File Contents

For reference, here are the complete file contents:

hello-world-deployment.yaml

[File contents would be here in the actual file]

hello-world-service.yaml

[File contents would be here in the actual file]

🆘 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 the Getting Started Guide

For more help, visit our documentation or contact support.