myceliumcloud-examples/README.md

# Mycelium Cloud Examples

Comprehensive guide and examples for deploying applications on Mycelium Cloud Kubernetes clusters.

🌐 **Website**: [https://myceliumcloud.tf](https://myceliumcloud.tf)

## Overview

Mycelium Cloud is a comprehensive platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. This repository contains step-by-step guides, working examples, and best practices for deploying applications on your Mycelium Cloud cluster.

## What is Mycelium Cloud?

Mycelium Cloud provides a complete solution for cloud-native applications with:

- **Decentralized Infrastructure**: Deploy on ThreeFold Grid's distributed network
- **Kubernetes Management**: Full K3s cluster deployment and management
- **IPv6 Networking**: Mycelium peer-to-peer networking
- **High Availability**: Multi-master cluster support
- **Secure Communication**: All traffic is encrypted through the Mycelium network
- **No Public IPs Required**: Services accessible via Mycelium IPs

## Architecture

Mycelium Cloud uses peer-to-peer networking that enables:

- **Direct Node Access**: Each node gets a unique Mycelium IP address
- **Cross-Node Communication**: Services communicate across nodes using Mycelium networking
- **Secure Communication**: All traffic is encrypted through the Mycelium network
- **No Public IPs Required**: Services accessible via Mycelium IPs

**Network Flow**: `User Machine → Mycelium Network → Cluster Node → Service`

## Quick Start

### 1. Account Setup

1. **Sign Up**: Create your account from [myceliumcloud.tf](https://myceliumcloud.tf) signup page
2. **Verify Email**: Check your email and verify your account
3. **Add Funds**: Navigate to your dashboard and add credits to your account
4. **Add SSH Key**: Navigate to Add SSH card and upload your public SSH key

### 2. Deploy Your First Cluster

1. **Access Deploy**: Click "Deploy Cluster" from your dashboard
2. **Configure VMs**: Define your virtual machines:
   - Choose CPU, memory, and storage requirements
   - Select the number of master and worker nodes
3. **Select Nodes**: Choose ThreeFold Grid nodes for deployment
4. **Review & Deploy**: Confirm your configuration and deploy

### 3. Access Your Cluster

#### Download and Configure Kubeconfig

**Method 1: Direct to Default Location (Recommended)**
```bash
# 1. Download kubeconfig from dashboard → Clusters → Click download (⬇️)
# 2. Copy to kubectl's default location
mkdir -p ~/.kube
cp ~/Downloads/kubeconfig.yaml ~/.kube/config

# 3. Verify connection
kubectl get nodes
```

**Method 2: Environment Variable (Multi-cluster)**
```bash
# 1. Download kubeconfig and save to a specific location
# 2. Set environment variable (temporary)
export KUBECONFIG=/path/to/your/kubeconfig.yaml

# 3. Verify connection
kubectl get nodes
```

**Method 3: Merge with Existing Config (Advanced)**
```bash
# 1. Download kubeconfig
# 2. Merge with existing kubeconfig (preserves other clusters)
KUBECONFIG=~/.kube/config:/path/to/downloaded/config.yaml kubectl config view --flatten > ~/.kube/config-temp
mv ~/.kube/config-temp ~/.kube/config

# 3. Switch between clusters
kubectl config use-context mycelium-cluster
```

**Method 4: Named Context (Best Practice)**
```bash
# 1. Download kubeconfig
# 2. Add as named context
kubectl config --kubeconfig=/path/to/downloaded/config.yaml set-context mycelium-cloud --cluster=my-cluster --user=default

# 3. Use specific context
kubectl config use-context mycelium-cloud
kubectl get nodes
```

**Test your setup:**
```bash
# Verify cluster connectivity
kubectl cluster-info

# Check nodes
kubectl get nodes

# View current context
kubectl config current-context
```

**Troubleshooting Kubeconfig:**

```bash
# Check kubectl version and config location
kubectl version --client
echo $KUBECONFIG

# View current config
kubectl config view

# List all contexts
kubectl config get-contexts

# Check if nodes are accessible
kubectl get nodes --v=6  # Verbose output for debugging

# Test API server connectivity
curl -k https://<cluster-api-server>:6443/version
```

**Common Issues:**
- **Permission denied**: `chmod 600 ~/.kube/config`
- **Context not found**: `kubectl config use-context <context-name>`
- **Multiple kubeconfig files**: `KUBECONFIG=path1:path2 kubectl get nodes`
- **Expired certificates**: Re-download kubeconfig from dashboard

#### SSH Access

1. **Find Mycelium IPs**: Check cluster details page for node IPs
2. **Download Mycelium Binary**:

   ```bash
   wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-private-x86_64-unknown-linux-musl.tar.gz
   tar -xzf mycelium-private-x86_64-unknown-linux-musl.tar.gz
   sudo chmod +x mycelium-private
   sudo mv mycelium-private /usr/local/bin/mycelium
   ```

3. **Start Mycelium**:

   ```bash
   sudo mycelium --peers tcp://188.40.132.242:9651 tcp://136.243.47.186:9651 tcp://185.69.166.7:9651 tcp://185.69.166.8:9651 tcp://65.21.231.58:9651 tcp://65.109.18.113:9651 tcp://209.159.146.190:9651 tcp://5.78.122.16:9651 tcp://5.223.43.251:9651 tcp://142.93.217.194:9651
   ```

4. **SSH to nodes**: `ssh root@<mycelium-ip>`

## Repository Structure

```
📁 myceliumcloud-examples/
├── 📄 README.md                    ← This file (complete guide)
├── 📄 LICENSE
├── 📄 .gitignore
└── 📁 examples/                    ← Standalone examples
    └── 📁 hello-world/             ← Start here for your first app
        ├── 📄 hello-world.md
        ├── 📄 hello-world-deployment.yaml
        └── 📄 hello-world-service.yaml
```

## Getting Started with Examples

Each example in the `examples/` directory is **standalone and self-contained**. Just copy the directory and follow the README inside.

### 🚀 Start Here: Hello World

**The easiest way to get started:**

```bash
# Copy the hello-world example
cp -r examples/hello-world ./my-first-app
cd my-first-app

# Deploy the application
kubectl apply -f *.yaml

# Start port-forward (keep terminal open)
kubectl port-forward service/hello-world-service 8080:8080

# Access your app in another terminal
curl http://localhost:8080
```

**What you'll learn:**
- Basic Kubernetes deployment patterns
- Service creation and networking
- Port-forwarding for external access
- Troubleshooting common issues
- Resource management and cleanup

## Key Concepts for Mycelium Cloud

### Port-Forwarding (Essential!)

In Mycelium Cloud, LoadBalancer external IPs are internal cluster addresses that aren't accessible from outside. **Use port-forward for reliable external access:**

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

**Option 2: Multiple Terminals (Advanced)**
```bash
# Terminal 1: Start port-forward
kubectl port-forward service/your-service 8080:8080

# Terminal 2: Access your app
curl http://localhost:8080
```

**Note**: Port-forwarding requires keeping the terminal open. For background operation, consider using a terminal multiplexer or running in a separate terminal session.
```

**Access your app:**
```bash
# Works for both options
curl http://localhost:8080
```

### File Organization Pattern

Mycelium Cloud examples follow a **two-file approach** for clean separation:

1. **app.yaml** - Contains the Deployment (application logic)
2. **service.yaml** - Contains the Service (networking configuration)

```bash
# Deploy application
kubectl apply -f app.yaml

# Create networking
kubectl apply -f service.yaml

# Access via port-forward
kubectl port-forward service/your-service 8080:8080
```

## Examples Overview

### Current Examples

Currently, we have one complete example:

| Example | Description | Difficulty | Key Learning |
|---------|-------------|------------|--------------|
| **hello-world** | Basic web app deployment | ⭐ Easy | Kubernetes basics, port-forwarding |

### Planned Examples

Future examples may include:
- **python-server** - Multiple Python servers with load balancing
- **wordpress** - WordPress deployment with database
- **nextcloud** - File sharing application
- **prometheus** - Monitoring and metrics

### Example Pattern

Each example follows the same pattern:

```
📁 example-name/
├── 📄 example-name.md             ← Complete guide + troubleshooting
├── 📄 example-deployment.yaml    ← Application logic
├── 📄 example-service.yaml       ← Networking
└── 📁 src/ (optional)           ← Source files for customization
```

## Troubleshooting

### Common Commands

```bash
# Check cluster health
kubectl get nodes
kubectl get pods --all-namespaces

# Check specific app
kubectl get all -l app=your-app-label
kubectl logs deployment/your-app
kubectl describe service your-service

# Fix port conflicts
lsof -i :8080  # Check what's using port 8080
kill -9 $(lsof -ti:8080)  # Kill the process
```

### Mycelium Cloud Specific

```bash
# Test if your cluster is accessible
kubectl cluster-info

# Check node status (should show 2-3 masters + 2-5 workers)
kubectl get nodes

# Verify Mycelium networking
kubectl get nodes -o wide
```

## Best Practices

### 1. Always Use Standalone Examples
Each example is self-contained. Don't mix files between examples.

### 2. Port-Forward Management

**Simple Method (Recommended):**
```bash
# Start port-forward (keep terminal open)
kubectl port-forward service/your-service 8080:8080

# Stop with Ctrl+C
```

**Advanced Method (Background):**
```bash
# Start in background
nohup kubectl port-forward service/your-service 8080:8080 > /dev/null 2>&1 &

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

### 3. Resource Cleanup
```bash
# Always clean up when done
kubectl delete -f *.yaml

# IMPORTANT: Also kill the port-forward
lsof -ti:8080 | xargs kill -9  # Replace 8080 with your port
```

### 4. Multiple Environments
```bash
# Use namespaces for different environments
kubectl apply -f *.yaml --namespace=dev
kubectl apply -f *.yaml --namespace=prod
```

## Support & Resources

- **Website**: [https://myceliumcloud.tf](https://myceliumcloud.tf)
- **Documentation**: This README and individual example READMEs
- **Complete Cleanup Example**:

  When you're done with an example, run all these commands:

  ```bash
  # 1. Delete all Kubernetes resources
  kubectl delete -f *.yaml

  # 2. Kill any port-forwards (replace 8080 with your port)
  lsof -ti:8080 | xargs kill -9

  # 3. Verify cleanup
  kubectl get all -l app=your-app-label  # Should return nothing
  ```

- **Getting Help**:
  1. Check the troubleshooting section in your example's README
  2. Verify cluster health: `kubectl get nodes`
  3. Check pod logs: `kubectl logs deployment/your-app`

## Contributing

Want to add an example? Here's the pattern:

1. Create `examples/your-example/`
2. Add `example-name.md` with complete guide
3. Add deployment and service YAML files
4. Test end-to-end functionality
5. Include troubleshooting section

## License

See [LICENSE](LICENSE) file for details.

---

## 🚀 Ready to Deploy?

Start with the [Hello World example](examples/hello-world/hello-world.md) - it's designed to get you up and running in 5 minutes!

**Happy deploying! 🎉**