feat: Add comprehensive documentation structure with farming, mycelium, and cloud guides

2025-10-16 08:35:58 -04:00
parent 4f0a8eec6e
commit 98e904384b
23 changed files with 2980 additions and 0 deletions
--- a/docs/mycelium-network/install.md
+++ b/docs/mycelium-network/install.md
@@ -0,0 +1,229 @@
+---
+sidebar_position: 2
+---
+
+# Install Mycelium
+
+Get Mycelium running on your system in just a few steps.
+
+## Linux Installation
+
+### Using Pre-built Binaries (Recommended)
+
+1. **Download the latest release:**
+   ```bash
+   wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-linux-x64.tar.gz
+   ```
+
+2. **Extract and install:**
+   ```bash
+   tar -xzf mycelium-linux-x64.tar.gz
+   chmod +x mycelium
+   sudo mv mycelium /usr/local/bin/
+   ```
+
+3. **Verify installation:**
+   ```bash
+   mycelium --version
+   ```
+
+### Building from Source
+
+If you prefer to build from source:
+
+```bash
+# Install Rust if you haven't already
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Clone and build
+git clone https://github.com/threefoldtech/mycelium.git
+cd mycelium/myceliumd
+cargo build --release
+
+# Install binary
+sudo mv target/release/myceliumd /usr/local/bin/mycelium
+```
+
+## macOS Installation
+
+### Using Pre-built Binaries
+
+1. **Download the latest release:**
+   ```bash
+   wget https://github.com/threefoldtech/mycelium/releases/latest/download/mycelium-macos-x64.tar.gz
+   ```
+
+2. **Extract and install:**
+   ```bash
+   tar -xzf mycelium-macos-x64.tar.gz
+   chmod +x mycelium
+   sudo mv mycelium /usr/local/bin/
+   ```
+
+3. **Verify installation:**
+   ```bash
+   mycelium --version
+   ```
+
+### Using Homebrew (if available)
+
+```bash
+brew install threefoldtech/mycelium/mycelium
+```
+
+## Windows Installation
+
+### Using the Installer
+
+1. **Download the installer:**
+   - Go to [releases page](https://github.com/threefoldtech/mycelium/releases)
+   - Download `mycelium_installer.msi`
+
+2. **Run the installer:**
+   - Double-click the downloaded `.msi` file
+   - Follow the installation wizard
+
+3. **Verify installation:**
+   Open Command Prompt and run:
+   ```cmd
+   mycelium --version
+   ```
+
+### Manual Installation
+
+1. Download `mycelium-windows-x64.zip` from the releases page
+2. Extract to a folder (e.g., `C:\Program Files\Mycelium\`)
+3. Add the folder to your PATH environment variable
+4. Open a new Command Prompt and verify with `mycelium --version`
+
+## Mobile Installation
+
+### iOS
+
+Mycelium runs as a mobile app on iOS devices:
+
+- Available through the project's mobile directory
+- Requires developer tools for installation
+- Operates in TUN-only mode for overlay networking
+
+**Note:** iOS version may have limitations compared to desktop versions due to platform restrictions.
+
+### Android
+
+Mycelium has full support on Android:
+
+- Build from source using the mobile directory
+- Full TUN interface support
+- Complete overlay networking functionality
+
+Check the [GitHub repository](https://github.com/threefoldtech/mycelium) for the latest mobile installation instructions.
+
+## Docker Installation
+
+Run Mycelium in a container:
+
+```bash
+docker run -d \
+  --name mycelium \
+  --cap-add NET_ADMIN \
+  --device /dev/net/tun \
+  --sysctl net.ipv6.conf.all.disable_ipv6=0 \
+  threefoldtech/mycelium:latest \
+  --peers tcp://188.40.132.242:9651
+```
+
+## Verify Installation
+
+After installing, verify Mycelium is working:
+
+```bash
+mycelium --help
+```
+
+You should see the help output with available commands and options.
+
+## System Requirements
+
+### Minimum Requirements
+
+- **OS**: Linux, macOS, Windows (64-bit)
+- **RAM**: 50MB
+- **Disk**: 20MB
+- **Network**: IPv6 support (enabled by default on most systems)
+
+### Network Requirements
+
+- Internet connection
+- IPv6 capable network stack (standard on modern systems)
+- No special firewall configuration needed (works with NAT)
+
+## Troubleshooting
+
+### "Command not found" Error
+
+If you get a "command not found" error:
+
+**Linux/macOS:**
+- Ensure `/usr/local/bin` is in your PATH
+- Try running with full path: `/usr/local/bin/mycelium`
+- Check file permissions: `ls -l /usr/local/bin/mycelium`
+
+**Windows:**
+- Verify the installation directory is in your PATH
+- Open a new Command Prompt after installation
+- Try full path: `"C:\Program Files\Mycelium\mycelium.exe"`
+
+### Permission Denied
+
+If you get permission errors when running:
+
+**Linux/macOS:**
+```bash
+# Make the binary executable
+chmod +x /usr/local/bin/mycelium
+
+# Run with sudo if needed for network operations
+sudo mycelium --peers tcp://188.40.132.242:9651
+```
+
+**Windows:**
+- Run Command Prompt as Administrator
+- Check Windows Firewall settings
+
+### IPv6 Not Available
+
+Mycelium requires IPv6. If you get IPv6 errors:
+
+**Linux:**
+```bash
+# Check if IPv6 is enabled
+cat /proc/sys/net/ipv6/conf/all/disable_ipv6
+
+# Enable if needed (0 = enabled)
+sudo sysctl -w net.ipv6.conf.all.disable_ipv6=0
+```
+
+**macOS:**
+IPv6 is enabled by default. Check System Preferences > Network.
+
+**Windows:**
+IPv6 is enabled by default. Check Network Adapter properties.
+
+## What's Next?
+
+Now that Mycelium is installed, let's connect to the network:
+
+**[Quick Start Guide](/mycelium-network/quick-start)** - Connect in 5 minutes
+
+## Additional Resources
+
+- **Full User Guide**: [threefoldtech.github.io/www_myceliumguide](https://threefoldtech.github.io/www_myceliumguide/)
+- **GitHub Repository**: [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
+- **Technical Docs**: Available in the repository
+- **Get Help**: [Telegram Community](https://t.me/threefoldfarmers)
+
+---
+
+:::tip Ready to Connect?
+Installation complete! Continue to the **[Quick Start](/mycelium-network/quick-start)** guide to join the network.
+:::
--- a/docs/mycelium-network/overview.md
+++ b/docs/mycelium-network/overview.md
@@ -0,0 +1,165 @@
+---
+sidebar_position: 1
+---
+
+# What is Mycelium Network?
+
+Mycelium is an **IPv6 overlay network** that creates secure, encrypted connections between your devices anywhere in the world.
+
+Think of it as your own private internet layer - but without the complexity of VPNs, port forwarding, or NAT traversal.
+
+## How It Works
+
+Mycelium creates a **peer-to-peer mesh network** where:
+
+- 🌐 Each device gets its own unique IPv6 address
+- 🔐 All traffic is automatically encrypted end-to-end
+- 🚀 Smart routing finds the fastest path between devices
+- 🔄 Network adapts automatically as devices join or leave
+
+No central servers. No configuration complexity. Just secure connectivity.
+
+## Why Use Mycelium?
+
+### 🌍 Global Connectivity
+
+Connect devices across the world as if they were on the same local network:
+- Home server to laptop while traveling
+- Multiple offices without complicated VPN setups
+- IoT devices across different locations
+- Development environments and remote services
+
+### 🔒 Secure by Default
+
+- **End-to-end encryption** - Traffic is encrypted between devices
+- **No trust required** - No central authority can intercept
+- **Automatic security** - No manual key exchange needed
+- **Private by design** - Only you control your network
+
+### 🚀 Smart & Fast
+
+- **Automatic routing** - Finds optimal paths
+- **NAT traversal** - Works behind firewalls
+- **Resilient** - Routes around failures
+- **Low overhead** - Minimal performance impact
+
+### 📱 Cross-Platform
+
+Works everywhere:
+- Linux (all distributions)
+- macOS
+- Windows
+- iOS
+- Android
+
+## Common Use Cases
+
+### Remote Access
+
+Access your home server or services from anywhere without opening ports or configuring complex VPNs.
+
+```bash
+# At home: Run Mycelium on your server
+# Address: 5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
+
+# Traveling: Access your server via its Mycelium address
+ssh user@5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
+```
+
+### Private Networks
+
+Create secure connections between multiple locations:
+- Link office networks
+- Connect distributed teams
+- Secure IoT deployments
+- Private cloud infrastructure
+
+### Development & Testing
+
+Build distributed applications with real-world networking:
+- Test across geographic locations
+- Develop P2P applications
+- Simulate network topologies
+- Remote debugging
+
+### ThreeFold Grid Access
+
+Connect to services on the ThreeFold Grid:
+- Access deployed workloads
+- Manage your infrastructure
+- Use decentralized services
+- Build on the grid
+
+## Key Features
+
+| Feature | Benefit |
+|---------|---------|
+| **Zero Configuration** | Works out of the box |
+| **IPv6 Native** | Future-proof addressing |
+| **P2P Mesh** | No single point of failure |
+| **Automatic Encryption** | Secure without complexity |
+| **NAT Traversal** | Works behind firewalls |
+| **Smart Routing** | Optimal path selection |
+| **Low Latency** | Direct connections when possible |
+| **Cross-Platform** | Run anywhere |
+
+## How Is It Different?
+
+### vs Traditional VPNs
+
+- ✅ **No central server** - Peer-to-peer mesh
+- ✅ **Automatic routing** - No manual configuration
+- ✅ **Lower latency** - Direct connections
+- ✅ **Simpler setup** - Just run and connect
+
+### vs Other Overlay Networks
+
+- ✅ **IPv6 native** - Not limited to IPv4 address space
+- ✅ **Production ready** - Used in ThreeFold infrastructure
+- ✅ **Active development** - Continuous improvements
+- ✅ **Open source** - Transparent and auditable
+
+## Architecture Overview
+
+```
+┌──────────────┐      Encrypted Tunnel      ┌──────────────┐
+│   Device A   │◄────────────────────────────►│   Device B   │
+│ Mycelium IP  │      Over Internet          │ Mycelium IP  │
+└──────────────┘                             └──────────────┘
+       │                                            │
+       └────────────── Mesh Network ───────────────┘
+                   (via Public Peers)
+```
+
+- Devices run Mycelium daemon
+- Connect to public or private peers
+- Build encrypted tunnels automatically
+- Route traffic efficiently
+
+## Getting Started
+
+Ready to try Mycelium? Here's your path:
+
+1. **[Install Mycelium](/mycelium-network/install)** - Set up on your system
+2. **[Quick Start](/mycelium-network/quick-start)** - Connect to the network
+
+<div className="info-box">
+
+### 💡 5-Minute Setup
+
+Most users are connected to the global Mycelium network within 5 minutes of starting installation.
+
+</div>
+
+## Resources
+
+- **Documentation**: [Mycelium Guide](https://threefoldtech.github.io/www_myceliumguide/)
+- **Source Code**: [GitHub Repository](https://github.com/threefoldtech/mycelium)
+- **Community**: [ThreeFold Telegram](https://t.me/threefoldfarmers)
+- **Forum**: [forum.threefold.io](https://forum.threefold.io)
+
+---
+
+:::tip Next Step
+Install Mycelium on your system: **[Installation Guide](/mycelium-network/install)**
+:::
--- a/docs/mycelium-network/quick-start.md
+++ b/docs/mycelium-network/quick-start.md
@@ -0,0 +1,219 @@
+---
+sidebar_position: 3
+---
+
+# Quick Start
+
+Get connected to the Mycelium network in under 5 minutes.
+
+## Step 1: Connect to Public Peers
+
+Start your Mycelium node and connect to the global network:
+
+**Linux/macOS:**
+```bash
+sudo mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651
+```
+
+**Windows (as Administrator):**
+```cmd
+mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651
+```
+
+You should see output indicating Mycelium is starting and connecting to peers.
+
+<div className="info-box">
+
+### 🔐 Why sudo/Administrator?
+
+Mycelium needs elevated privileges to create a network interface. This is standard for networking tools.
+
+</div>
+
+## Step 2: Get Your IPv6 Address
+
+Open a **new terminal** (keep Mycelium running in the first one) and check your node info:
+
+```bash
+mycelium inspect --json
+```
+
+You'll see output like:
+```json
+{
+  "publicKey": "abd16194646defe7ad2318a0f0a69eb2e3fe939c3b0b51cf0bb88bb8028ecd1d",
+  "address": "5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca"
+}
+```
+
+**Save your address** - this is your unique Mycelium IPv6 address that others will use to reach you.
+
+## Step 3: Test Connectivity
+
+Ping one of the public peers to verify connectivity:
+
+```bash
+ping6 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907
+```
+
+If you see responses, congratulations! You're connected to the Mycelium network.
+
+```
+PING 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907(54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907) 56 data bytes
+64 bytes from 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907: icmp_seq=1 ttl=64 time=28.5 ms
+64 bytes from 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907: icmp_seq=2 ttl=64 time=27.8 ms
+```
+
+## Public Peers List
+
+Connect to these stable public peers for reliable connectivity:
+
+| Region | IPv4 | IPv6 | TCP/QUIC Port | Mycelium IP |
+|--------|------|------|---------------|-------------|
+| Germany | 188.40.132.242 | 2a01:4f8:221:1e0b::2 | 9651 | 54b:83ab:6cb5:7b38:44ae:cd14:53f3:a907 |
+| Germany | 136.243.47.186 | 2a01:4f8:212:fa6::2 | 9651 | 40a:152c:b85b:9646:5b71:d03a:eb27:2462 |
+| Belgium | 185.69.166.7 | 2a02:1802:5e:0:ec4:7aff:fe51:e80d | 9651 | 597:a4ef:806:b09:6650:cbbf:1b68:cc94 |
+| Belgium | 185.69.166.8 | 2a02:1802:5e:0:ec4:7aff:fe51:e36b | 9651 | 549:8bce:fa45:e001:cbf8:f2e2:2da6:a67c |
+| Finland | 65.21.231.58 | 2a01:4f9:6a:1dc5::2 | 9651 | 410:2778:53bf:6f41:af28:1b60:d7c0:707a |
+| Finland | 65.109.18.113 | 2a01:4f9:5a:1042::2 | 9651 | 488:74ac:8a31:277b:9683:c8e:e14f:79a7 |
+| US East | 209.159.146.190 | 2604:a00:50:17b:9e6b:ff:fe1f:e054 | 9651 | 4ab:a385:5a4e:ef8f:92e0:1605:7cb6:24b2 |
+| US West | 5.78.122.16 | 2a01:4ff:1f0:8859::1 | 9651 | 4de:b695:3859:8234:d04c:5de6:8097:c27c |
+| Singapore | 5.223.43.251 | 2a01:4ff:2f0:3621::1 | 9651 | 5eb:c711:f9ab:eb24:ff26:e392:a115:1c0e |
+| India | 142.93.217.194 | 2400:6180:100:d0::841:2001 | 9651 | 445:465:fe81:1e2b:5420:a029:6b0:9f61 |
+
+## Connect to Multiple Peers
+
+For better reliability and performance, connect to multiple peers:
+
+```bash
+sudo mycelium --peers \
+  tcp://188.40.132.242:9651 \
+  quic://185.69.166.8:9651 \
+  tcp://185.69.166.7:9651 \
+  quic://65.21.231.58:9651
+```
+
+This creates redundant paths and improves network resilience.
+
+## Keep Mycelium Running
+
+Mycelium needs to stay running to maintain your network connection.
+
+### Run in Background
+
+**Linux/macOS:**
+```bash
+# Using nohup
+nohup sudo mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651 &
+```
+
+**Better: Use systemd (Linux):**
+
+Create `/etc/systemd/system/mycelium.service`:
+```ini
+[Unit]
+Description=Mycelium Network
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/mycelium --peers tcp://188.40.132.242:9651 quic://185.69.166.8:9651
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+```bash
+sudo systemctl enable mycelium
+sudo systemctl start mycelium
+sudo systemctl status mycelium
+```
+
+**Windows:**
+- Use Task Scheduler to run at startup
+- Or run in a Command Prompt window kept open
+
+## Basic Usage Examples
+
+### SSH to Another Device
+
+If you have SSH running on another device with Mycelium:
+
+```bash
+ssh user@5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca
+```
+
+### Access a Web Service
+
+```bash
+curl http://[5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca]:8080
+```
+
+Note: IPv6 addresses must be in brackets for URLs.
+
+### Connect Two Locations
+
+Run Mycelium on devices at both locations:
+- They'll automatically find each other through the mesh
+- Use their Mycelium IPs to communicate
+- All traffic is encrypted end-to-end
+
+## Troubleshooting
+
+### Can't Connect to Peers
+
+1. **Check internet connection** - Verify you're online
+2. **Firewall issues** - Mycelium should work behind NAT, but try temporarily disabling firewall
+3. **IPv6 support** - Ensure IPv6 is enabled on your system
+4. **Try different peers** - Some may be temporarily down
+
+### Can't Ping Other Nodes
+
+1. **Wait a few minutes** - Network discovery takes time
+2. **Check peer connections** - Ensure you're connected to peers
+3. **Verify the address** - Make sure you're pinging a valid Mycelium address
+4. **Check logs** - Look for errors in the Mycelium output
+
+### Permission Errors
+
+- **Linux/macOS**: Must run with `sudo`
+- **Windows**: Must run Command Prompt as Administrator
+- This is required to create the network interface
+
+## What's Next?
+
+Now that you're connected, explore what you can do:
+
+### Use Cases
+
+- **Remote Access**: Access your services from anywhere
+- **Connect Devices**: Link multiple locations securely
+- **ThreeFold Grid**: Access your grid deployments
+- **P2P Applications**: Build distributed systems
+
+### Advanced Configuration
+
+For more advanced setup options:
+- Custom port configuration
+- Private peer networks
+- SOCKS5 proxy setup
+- Advanced routing options
+
+Check the [detailed Mycelium guide](https://threefoldtech.github.io/www_myceliumguide/) for more information.
+
+## Resources
+
+- **Full Documentation**: [Mycelium User Guide](https://threefoldtech.github.io/www_myceliumguide/)
+- **GitHub**: [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
+- **Community**: [Telegram](https://t.me/threefoldfarmers)
+- **Forum**: [forum.threefold.io](https://forum.threefold.io)
+
+---
+
+:::tip Connected Successfully?
+
+Great! You're now part of the global Mycelium network. Try deploying on **[Mycelium Cloud](/mycelium-cloud/overview)** to run workloads on the ThreeFold Grid.
+:::