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)

```bash
# 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)**
```bash
# Keep terminal open, see connection logs (Ctrl+C to stop)
kubectl port-forward service/hello-world-service 8080:8080
```

**Option 2: Advanced (Background)**
```bash
# 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
```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)**
```bash
# 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)**
```bash
# 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)

```bash
# 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)

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

## 🔍 Troubleshooting

### Check Deployment Status
```bash
# 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
```bash
# Check what's using port 8080
lsof -i :8080

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

#### Pod Not Starting
```bash
# Check pod status and events
kubectl describe pod -l app=hello-world

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

#### Service Not Accessible
```bash
# 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
```bash
# Scale to 3 replicas
kubectl scale deployment hello-world --replicas=3

# Check distribution
kubectl get pods -o wide
```

### Updates
```bash
# 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
```bash
# 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:

```bash
# 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](../../docs/getting-started.md)

For more help, visit our [documentation](../../README.md) or contact support.