feat: Add Kubernetes basics guide and FAQ for Mycelium Cloud documentation

docs/intro.md

@@ -22,7 +22,7 @@ This guide will help you:
 ### Real Technology, Real Impact
 
 - **7+ years** of development
-- **Open-source** technology you can verify: [threefold.info/tech](https://threefold.info/tech)
+- **Open-source** technology
 - **Working infrastructure** serving real workloads today
 - **Decentralized cloud** that empowers individuals and communities
 
@@ -84,9 +84,8 @@ Choose your path:
 
 Join thousands of ThreeFold farmers and users:
 
-- **👥 Join Telegram**: [t.me/threefold/1](https://t.me/threefold/1)
+- **[👥 Join Telegram](https://t.me/threefold/1)**
-- **💬 Join the Forum**: [forum.threefold.io](https://forum.threefold.io)
+- **[💬 Join the Forum](https://forum.threefold.io)**
-- **📞 Join Community Calls**: [bit.ly/tfcommunitycall](https://bit.ly/tfcommunitycall)
 ---
 
 **With gratitude,**  

docs/mycelium-cloud/faq.md

@@ -0,0 +1,276 @@
+---
+sidebar_position: 5
+---
+
+# Frequently Asked Questions
+
+Common questions about deploying and managing Kubernetes clusters on Mycelium Cloud.
+
+## General
+
+### What is Mycelium Cloud?
+
+Mycelium Cloud is a platform for deploying and managing Kubernetes clusters on the decentralized ThreeFold Grid infrastructure. It provides K3s clusters with Mycelium peer-to-peer networking, making it easy to run containerized applications on distributed, cost-effective infrastructure.
+
+### What makes Mycelium Cloud different?
+
+- **Decentralized Infrastructure**: Runs on ThreeFold Grid's distributed network
+- **IPv6 Networking**: Built-in Mycelium peer-to-peer networking
+- **Cost Effective**: Competitive pricing on decentralized infrastructure
+- **No Vendor Lock-in**: Standard Kubernetes (K3s) - works with all K8s tools
+- **Global Distribution**: Deploy across worldwide node locations
+
+### Is it suitable for production workloads?
+
+Yes! Mycelium Cloud supports production workloads with:
+- High availability cluster configurations (multi-master)
+- Persistent storage options
+- Monitoring and logging capabilities
+- Standard Kubernetes security features
+
+## Getting Started
+
+### How do I create an account?
+
+1. Visit [Mycelium Cloud](https://myceliumcloud.tf)
+2. Fill in your registration details
+3. Verify your email address
+4. Add credits and SSH keys from your dashboard
+
+See the **[Getting Started Guide](/getstarted/mycelium-cloud/getting-started)** for detailed steps.
+
+### What do I need to get started?
+
+- **Mycelium installed** - For network access ([Install guide](/getstarted/mycelium-network/install))
+- **kubectl installed** - For cluster management ([Install kubectl](https://kubernetes.io/docs/tasks/tools/))
+- **SSH key pair** - For node access
+- **Account credits** - To fund your deployments
+
+### What Kubernetes version is supported?
+
+Mycelium Cloud uses **K3s v1.26+**, which provides:
+- Full Kubernetes API compatibility
+- Lightweight resource usage
+- High availability features
+- Dual-stack networking (IPv4/IPv6)
+
+## Cluster Management
+
+### How do I access my cluster?
+
+Two methods:
+
+**1. kubectl (Recommended):**
+```bash
+# Download kubeconfig from dashboard
+export KUBECONFIG=/path/to/mycluster-config.yaml
+kubectl get nodes
+```
+
+**2. SSH:**
+```bash
+# Start Mycelium, then SSH to node IPs
+ssh root@<mycelium-ip>
+```
+
+See **[Getting Started](/getstarted/mycelium-cloud/getting-started#step-4-access-your-cluster)** for details.
+
+### Can I scale my cluster after deployment?
+
+Yes! You can:
+- Add or remove worker nodes through the dashboard
+- Scale applications independently using kubectl
+- Modify cluster configuration
+
+```bash
+# Scale deployment
+kubectl scale deployment myapp --replicas=5
+```
+
+### What happens if a node fails?
+
+- **Worker Node Failure**: Kubernetes automatically reschedules pods to healthy nodes
+- **Master Node Failure**: In HA setups (3+ masters), other masters take over
+- **Self-Healing**: Pods are automatically restarted if they crash
+
+## Networking
+
+### How do I expose applications to the internet?
+
+Options include:
+
+**1. NodePort Services:**
+```yaml
+type: NodePort
+```
+
+**2. Port Forwarding (Development):**
+```bash
+kubectl port-forward service/myapp 8080:80
+```
+
+**3. Ingress Controllers:**
+Set up an ingress controller for HTTP/HTTPS routing with custom domains.
+
+### Do I need public IP addresses?
+
+No! Mycelium Cloud uses **Mycelium networking**:
+- Each node gets a unique Mycelium IPv6 address
+- Access nodes and services via Mycelium network
+- All traffic encrypted end-to-end
+- No need for public IPs or complex firewall configurations
+
+## Troubleshooting
+
+### My cluster deployment failed. What should I do?
+
+1. **Check Logs**: Review deployment logs in the dashboard
+2. **Verify Credits**: Ensure sufficient account balance
+3. **Node Availability**: Confirm selected nodes are available
+4. **Configuration**: Validate cluster configuration settings
+5. **Contact Support**: If issues persist, reach out via Telegram or GitHub
+
+### I can't connect with kubectl. How do I fix this?
+
+```bash
+# 1. Verify kubeconfig is set
+echo $KUBECONFIG
+
+# 2. Check Mycelium is running
+# (Open Mycelium app or run: sudo mycelium --peers ...)
+
+# 3. Test cluster connectivity
+kubectl cluster-info
+
+# 4. Verify cluster is running in dashboard
+```
+
+Common issues:
+- Mycelium not running on your machine
+- Wrong kubeconfig file path
+- Cluster stopped in dashboard
+- Network firewall blocking connections
+
+### My pods are not starting. What's wrong?
+
+```bash
+# Check pod status
+kubectl get pods
+
+# Describe pod for events
+kubectl describe pod <pod-name>
+
+# Check logs
+kubectl logs <pod-name>
+
+# Check node resources
+kubectl top nodes
+```
+
+Common causes:
+- **Resource Limits**: Insufficient CPU/memory on nodes
+- **Image Issues**: Cannot pull container images
+- **Configuration**: Invalid pod specifications
+- **Storage**: Persistent volume issues
+
+### How do I check cluster health?
+
+```bash
+# Check node status
+kubectl get nodes
+
+# Check system pods
+kubectl get pods -n kube-system
+
+# View events
+kubectl get events --sort-by=.metadata.creationTimestamp
+
+# Check resource usage
+kubectl top nodes
+kubectl top pods
+```
+
+## Storage & Data
+
+### How do I persist data?
+
+Use **PersistentVolumeClaims** (PVCs):
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: my-data
+spec:
+  accessModes:
+  - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+See **[Tutorial](/getstarted/mycelium-cloud/tutorial#tutorial-3-stateful-application-with-persistent-storage)** for a complete example.
+
+### How do I backup my cluster?
+
+Backup strategies:
+- **Application Data**: Use PVC snapshots or backup tools
+- **Configurations**: Version control your YAML manifests in Git
+- **etcd Snapshots**: Cluster state backups (advanced)
+
+## Security
+
+### How secure is Mycelium Cloud?
+
+Security features:
+- **Encrypted Communication**: All traffic encrypted via Mycelium network
+- **Network Isolation**: Secure pod-to-pod communication
+- **RBAC**: Kubernetes role-based access control
+- **SSH Key Authentication**: Secure node access
+- **No Public IPs**: Reduced attack surface
+
+### How do I manage secrets?
+
+Use Kubernetes Secrets:
+
+```bash
+# Create secret
+kubectl create secret generic db-password --from-literal=password=mypassword
+
+# Use in pod
+env:
+- name: DB_PASSWORD
+  valueFrom:
+    secretKeyRef:
+      name: db-password
+      key: password
+```
+
+See **[Kubernetes Basics](/getstarted/mycelium-cloud/kubernetes-basics#secrets)** for more details.
+
+## Getting Help
+
+### Where can I get more information and support?
+
+- **Documentation**: [Getting Started](/getstarted/mycelium-cloud/getting-started), [Tutorial](/getstarted/mycelium-cloud/tutorial)
+- **Community**: [ThreeFold Telegram](https://t.me/threefold/1)
+
+### How do I report a bug?
+
+1. Check existing [GitHub Issues](https://github.com/codescalers/kubecloud/issues)
+2. Create a new issue with:
+   - Cluster configuration
+   - Error messages and logs
+   - Steps to reproduce
+   - Expected vs actual behavior
+
+---
+
+## Still Have Questions?
+
+Check out these resources:
+
+- **[Getting Started Guide](/getstarted/mycelium-cloud/getting-started)** - Step-by-step cluster deployment
+- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Practical deployment examples
+- **[Kubernetes Basics](/getstarted/mycelium-cloud/kubernetes-basics)** - Essential K8s concepts
+- **[Kubernetes Documentation](https://kubernetes.io/docs/)** - Official K8s docs

docs/mycelium-cloud/getting-started.md

@@ -27,7 +27,7 @@ Most users can install the Mycelium app from their App Store or download the des
 
 ### Sign Up
 
-1. Go to [vdc.grid.tf/sign-up](https://vdc.grid.tf/sign-up)
+1. Go to [Mycelium Cloud](https://myceliumcloud.tf/)
 2. Fill in your details:
    - Email address
    - Password
@@ -330,20 +330,12 @@ kubectl top nodes
 kubectl get events --sort-by='.lastTimestamp'
 ```
 
-## What's Next?
-
-Now that you have a cluster running, explore more:
-
-- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Deploy real applications
-- **[Kubernetes Concepts](https://codescalers.github.io/www_kubecloud/kubernetes-concepts)** - Learn K8s fundamentals
-- **[FAQ](https://codescalers.github.io/www_kubecloud/faq)** - Common questions
-
 ## Resources
 
-- **Dashboard**: [vdc.grid.tf](https://vdc.grid.tf)
+- **[Mycelium Cloud](https://myceliumcloud.tf/)**
-- **Kubernetes Docs**: [kubernetes.io/docs](https://kubernetes.io/docs/)
+- **[Kubernetes Docs](https://kubernetes.io/docs/)**
-- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
+- **[kubectl Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)**
-- **Community**: [Telegram](https://t.me/threefold/1)
+- **[Community Chat](https://t.me/threefold/1)**
 
 ---
 

docs/mycelium-cloud/kubernetes-basics.md

@@ -0,0 +1,342 @@
+---
+sidebar_position: 4
+---
+
+# Kubernetes Basics
+
+Essential Kubernetes concepts for deploying applications on Mycelium Cloud.
+
+## What is Kubernetes?
+
+Kubernetes (K8s) is a container orchestration platform that automates deploying, scaling, and managing containerized applications. Mycelium Cloud uses **K3s**, a lightweight Kubernetes distribution perfect for edge and cloud environments.
+
+### Why Kubernetes?
+
+- **Automated Deployment** - Deploy containers across multiple nodes
+- **Self-Healing** - Automatically restart failed containers
+- **Horizontal Scaling** - Scale applications up or down based on demand
+- **Service Discovery** - Automatic DNS and load balancing
+- **Rolling Updates** - Update applications with zero downtime
+
+## Core Concepts
+
+### Pods
+
+A **Pod** is the smallest deployable unit in Kubernetes. It represents one or more containers that share:
+- Network namespace (same IP address)
+- Storage volumes
+- Configuration
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx-pod
+spec:
+  containers:
+  - name: nginx
+    image: nginx:1.21
+    ports:
+    - containerPort: 80
+```
+
+```bash
+# View pods
+kubectl get pods
+
+# View pod details
+kubectl describe pod nginx-pod
+
+# View pod logs
+kubectl logs nginx-pod
+```
+
+### Deployments
+
+A **Deployment** manages a replicated set of Pods and provides declarative updates.
+
+Features:
+- **Replica Management** - Maintain desired number of pods
+- **Rolling Updates** - Update pods with zero downtime
+- **Rollback** - Revert to previous versions
+- **Self-Healing** - Replace failed pods automatically
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.21
+        ports:
+        - containerPort: 80
+```
+
+```bash
+# Create deployment
+kubectl apply -f deployment.yaml
+
+# View deployments
+kubectl get deployments
+
+# Scale deployment
+kubectl scale deployment nginx-deployment --replicas=5
+
+# Update image
+kubectl set image deployment/nginx-deployment nginx=nginx:1.22
+```
+
+### Services
+
+**Services** provide stable network endpoints for accessing pods.
+
+#### ClusterIP (Default)
+
+Internal-only service, accessible within the cluster:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  type: ClusterIP
+  selector:
+    app: nginx
+  ports:
+  - port: 80
+    targetPort: 80
+```
+
+#### NodePort
+
+Exposes service on each node's IP at a static port:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  type: NodePort
+  selector:
+    app: nginx
+  ports:
+  - port: 80
+    targetPort: 80
+    nodePort: 30080  # 30000-32767
+```
+
+```bash
+# View services
+kubectl get services
+
+# Describe service
+kubectl describe service my-service
+```
+
+### Namespaces
+
+**Namespaces** provide logical isolation for resources within a cluster.
+
+```bash
+# List namespaces
+kubectl get namespaces
+
+# Create namespace
+kubectl create namespace my-app
+
+# Use namespace
+kubectl get pods -n my-app
+```
+
+## Storage
+
+### Persistent Volumes
+
+**PersistentVolumeClaim (PVC)** - Request for storage:
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-data
+spec:
+  accessModes:
+  - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+Use in pod:
+
+```yaml
+spec:
+  containers:
+  - name: app
+    image: myapp:latest
+    volumeMounts:
+    - name: data
+      mountPath: /data
+  volumes:
+  - name: data
+    persistentVolumeClaim:
+      claimName: pvc-data
+```
+
+## Configuration
+
+### ConfigMaps
+
+Store non-sensitive configuration data:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+data:
+  database_url: "postgres://db:5432/mydb"
+  log_level: "info"
+```
+
+```bash
+# Create from literal
+kubectl create configmap app-config --from-literal=key=value
+
+# View configmaps
+kubectl get configmaps
+```
+
+### Secrets
+
+Store sensitive data (passwords, tokens, keys):
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: app-secret
+type: Opaque
+data:
+  password: cGFzc3dvcmQxMjM=  # base64 encoded
+```
+
+```bash
+# Create secret
+kubectl create secret generic app-secret --from-literal=password=password123
+
+# View secrets
+kubectl get secrets
+```
+
+## Essential kubectl Commands
+
+```bash
+# Cluster info
+kubectl cluster-info
+kubectl get nodes
+
+# Pods
+kubectl get pods
+kubectl get pods -o wide
+kubectl describe pod <pod-name>
+kubectl logs <pod-name>
+kubectl logs -f <pod-name>  # Follow logs
+kubectl exec -it <pod-name> -- /bin/bash
+
+# Deployments
+kubectl get deployments
+kubectl scale deployment <name> --replicas=5
+kubectl rollout status deployment/<name>
+kubectl rollout undo deployment/<name>
+
+# Services
+kubectl get services
+kubectl describe service <service-name>
+
+# Apply/Delete resources
+kubectl apply -f file.yaml
+kubectl delete -f file.yaml
+
+# Port forwarding
+kubectl port-forward pod/<pod-name> 8080:80
+kubectl port-forward service/<service-name> 8080:80
+
+# View all resources
+kubectl get all --all-namespaces
+
+# Check events
+kubectl get events --sort-by=.metadata.creationTimestamp
+```
+
+## Labels and Selectors
+
+**Labels** are key-value pairs attached to objects:
+
+```yaml
+metadata:
+  labels:
+    app: nginx
+    environment: production
+    tier: frontend
+```
+
+**Selectors** query objects by labels:
+
+```bash
+# Get pods with label
+kubectl get pods -l app=nginx
+
+# Get pods with multiple labels
+kubectl get pods -l app=nginx,environment=production
+```
+
+## Best Practices
+
+1. **Use Deployments** - Not bare pods, for self-healing and scaling
+2. **Set Resource Limits** - Prevent resource exhaustion
+   ```yaml
+   resources:
+     requests:
+       memory: "64Mi"
+       cpu: "250m"
+     limits:
+       memory: "128Mi"
+       cpu: "500m"
+   ```
+3. **Use Health Checks** - Implement liveness and readiness probes
+4. **Use Namespaces** - Organize resources logically
+5. **Version Control** - Store manifests in Git
+6. **Use Labels** - Tag resources for organization
+7. **Secrets Management** - Never hardcode sensitive data
+
+## Next Steps
+
+- **[Tutorial](/getstarted/mycelium-cloud/tutorial)** - Deploy real applications
+- **[FAQ](/getstarted/mycelium-cloud/faq)** - Common questions and answers
+
+## Additional Resources
+
+- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/)
+- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
+- **K3s Documentation**: [docs.k3s.io](https://docs.k3s.io/)
+
+---
+
+:::tip Want to Learn More?
+
+This covers the basics to get you started. For advanced topics like StatefulSets, DaemonSets, Ingress, and RBAC, check out the comprehensive Kubernetes documentation linked above.
+:::

docs/mycelium-cloud/overview.md

@@ -75,13 +75,13 @@ Mycelium Cloud uses peer-to-peer networking for direct access:
         │ Mycelium Network
         │ (encrypted P2P)
         │
-┌───────▼────────────────────────────────┐
+┌───────▼──────────────────────────────┐
-│         Kubernetes Cluster             │
+│         Kubernetes Cluster           │
-│  ┌──────────┐  ┌──────────┐           │
+│  ┌──────────┐  ┌──────────┐          │
-│  │  Master  │  │  Worker  │           │
+│  │  Master  │  │  Worker  │          │
-│  │   Node   │  │   Node   │  ...      │
+│  │   Node   │  │   Node   │  ...     │
-│  └──────────┘  └──────────┘           │
+│  └──────────┘  └──────────┘          │
-└────────────────────────────────────────┘
+└──────────────────────────────────────┘
      ThreeFold Grid Infrastructure
 ```
 
@@ -170,11 +170,12 @@ Check the dashboard for current rates. The decentralized infrastructure typicall
 
 ## Resources
 
-- **Dashboard**: [vdc.grid.tf](https://vdc.grid.tf) - Deploy and manage clusters
+- **[Mycelium Cloud](https://myceliumcloud.tf/)**
-- **Documentation**: [Mycelium Cloud Docs](https://codescalers.github.io/www_kubecloud/)
+- **[Kubernetes Basics](/getstarted/mycelium-cloud/kubernetes-basics)**
-- **Kubernetes Docs**: [kubernetes.io](https://kubernetes.io/docs/)
+- **[FAQ](/getstarted/mycelium-cloud/faq)**
-- **Community**: [ThreeFold Telegram](https://t.me/threefold/1)
+- **[Kubernetes Docs](https://kubernetes.io/docs/)**
-- **GitHub**: [kubecloud repository](https://github.com/codescalers/kubecloud)
+- **[Community Chat](https://t.me/threefold/1)**
+- **[GitHub Repository](https://github.com/codescalers/kubecloud)**
 
 ## Comparison to Traditional Cloud
 

docs/mycelium-cloud/tutorial.md

@@ -564,13 +564,6 @@ Now that you've completed these tutorials:
 - Study [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for databases
 - Explore [ConfigMaps and Secrets](https://kubernetes.io/docs/concepts/configuration/) for configuration management
 
-## Resources
-
-- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/)
-- **kubectl Cheat Sheet**: [kubernetes.io/docs/reference/kubectl/cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
-- **Mycelium Cloud FAQ**: [codescalers.github.io/www_kubecloud/faq](https://codescalers.github.io/www_kubecloud/faq)
-- **Community**: [Telegram](https://t.me/threefold/1)
-
 ---
 
 :::tip Keep Learning

sidebars.js

@@ -59,6 +59,8 @@ const sidebars = {
         'mycelium-cloud/overview',
         'mycelium-cloud/getting-started',
         'mycelium-cloud/tutorial',
+        'mycelium-cloud/kubernetes-basics',
+        'mycelium-cloud/faq',
       ],
     },
   ],