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

Sign Up: Create your account from myceliumcloud.tf signup page
Verify Email: Check your email and verify your account
Add Funds: Navigate to your dashboard and add credits to your account
Add SSH Key: Navigate to Add SSH card and upload your public SSH key

2. Deploy Your First Cluster

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

3. Access Your Cluster

Download and Configure Kubeconfig

Method 1: Direct to Default Location (Recommended)

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

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

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

# 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:

# Verify cluster connectivity
kubectl cluster-info

# Check nodes
kubectl get nodes

# View current context
kubectl config current-context

Troubleshooting Kubeconfig:

# 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

Find Mycelium IPs: Check cluster details page for node IPs

Download Mycelium Binary:

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

Start Mycelium:

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

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:

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

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

Option 2: Multiple Terminals (Advanced)

# 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:

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

# 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

# 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

# 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):

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

# Stop with Ctrl+C

Advanced Method (Background):

# 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

# 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

# Use namespaces for different environments
kubectl apply -f *.yaml --namespace=dev
kubectl apply -f *.yaml --namespace=prod

Support & Resources

Website: https://myceliumcloud.tf
Documentation: This README and individual example READMEs

Complete Cleanup Example:

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

# 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:

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

License

See LICENSE file for details.

🚀 Ready to Deploy?

Start with the Hello World example - it's designed to get you up and running in 5 minutes!

Happy deploying! 🎉