init

2025-11-04 10:39:10 -05:00
commit 0a95c51230
6 changed files with 977 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,317 @@
+# 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 Kubeconfig
+
+1. Go to dashboard → Clusters → Click download icon (⬇️)
+2. Set kubeconfig: `export KUBECONFIG=/path/to/config`
+3. Test: `kubectl get nodes`
+
+#### 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
+        ├── 📄 README.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/
+├── 📄 README.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 `README.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/README.md) - it's designed to get you up and running in 5 minutes!
+
+**Happy deploying! 🎉**