Thinkube Node Setup (tk-node-setup)

Bootstrap script for preparing Ubuntu nodes for remote Thinkube installation via overlay networks (ZeroTier or Tailscale).

Quick Start

Run this command on each Ubuntu node you want to prepare for Thinkube:

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/bootstrap.sh | sudo bash

What This Does

1. Auto-detects network configuration from your Ubuntu setup
2. Installs overlay network (ZeroTier or Tailscale) and joins your private network
3. Configures your existing user for Ansible automation
4. Prepares the node for remote Thinkube installation

Prerequisites

• Fresh Ubuntu 24.04 installation (arm64 or amd64)
• Network connectivity
• For ZeroTier:
  • ZeroTier Network ID (create one at my.zerotier.com)
  • ZeroTier API Token (from Account settings)
• For Tailscale:
  • Tailscale Auth Key (from https://login.tailscale.com/admin/settings/keys)
  • Recommended for DGX Spark environments

Usage

Option A: ZeroTier Setup

Step 1: Prepare Your ZeroTier Network

1. Create a ZeroTier network at my.zerotier.com
2. Note your Network ID (looks like: 1234567890abcdef)
3. Get your API token from Account settings
4. Configure your network:
   • Set IPv4 Auto-Assign to a range like 192.168.191.0/24
   • Or use Manual assignment for specific IPs

Step 2: Run Bootstrap on Each Node

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/bootstrap.sh | sudo bash

When prompted:

• Select 1 for ZeroTier
• Enter your ZeroTier Network ID
• Enter your ZeroTier API Token
• Choose a ZeroTier IP for the node

Option B: Tailscale Setup

Step 1: Prepare Your Tailscale Network

1. Sign up at https://login.tailscale.com/
2. Generate an auth key from Settings → Keys
   • Enable "Reusable" for multiple nodes
   • Set expiration as needed
3. Note your auth key (starts with tskey-auth-)

Step 2: Run Bootstrap on Each Node

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/bootstrap.sh | sudo bash

When prompted:

• Select 2 for Tailscale
• Enter your Tailscale auth key
• Tailscale will auto-assign an IP from the 100.x.x.x range

Option C: Local-Only Mode (No Overlay Network)

For local network installations without overlay networking:

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/bootstrap.sh | sudo bash -s -- --no-overlay

Important: Choose static IPs outside your DHCP range. Common examples:

• If DHCP uses .100-.199, use .10-.99 or .200-.254
• If DHCP uses .1-.100, use .150-.254
• Check your router settings to confirm DHCP range

The script will:

• Check and install OpenSSH if needed
• Auto-detect your current network settings (shows DHCP info)
• Configure a static IP address (you choose one outside DHCP range)
• Use your existing Ubuntu user for automation
• Install and configure your chosen overlay network (or skip overlay)

Step 3: Verify Setup

After bootstrap completes, verify:

For ZeroTier:

# Check ZeroTier status
sudo zerotier-cli status

# Check network membership
sudo zerotier-cli listnetworks

# Test connectivity from another ZeroTier node
ping <zerotier-ip>

For Tailscale:

# Check Tailscale status
tailscale status

# Test connectivity from another Tailscale node
ping <tailscale-ip>

Step 4: Remote Installation

From a machine with overlay network access:

For ZeroTier:

1. Join the same ZeroTier network on your installer machine
2. Run the Thinkube installer
3. Select ZeroTier as overlay provider
4. Use the ZeroTier IPs when discovering nodes
5. Use the same username you configured during bootstrap

For Tailscale:

1. Connect to Tailscale on your installer machine
2. Run the Thinkube installer
3. Select Tailscale as overlay provider
4. Use the Tailscale IPs when discovering nodes
5. Use the same username you configured during bootstrap

Manual Setup

If you prefer to run commands manually, see docs/manual-setup.md

Development: Removing Overlay Networks

For development environments where you want to switch overlay providers or start fresh:

Remove ZeroTier

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/scripts/remove-zerotier.sh | sudo bash

Or if you've cloned the repository:

cd tk-node-setup
sudo ./scripts/remove-zerotier.sh

This will:

• Leave all ZeroTier networks
• Stop and disable the ZeroTier service
• Remove the ZeroTier package
• Clean up all ZeroTier files
• Optionally remove firewall rules
• Update bootstrap configuration

Remove Tailscale

curl -sSL https://raw.githubusercontent.com/thinkube/tk-node-setup/main/scripts/remove-tailscale.sh | sudo bash

Or if you've cloned the repository:

cd tk-node-setup
sudo ./scripts/remove-tailscale.sh

This will:

• Logout from Tailscale
• Stop and disable the Tailscale service
• Remove the Tailscale package
• Clean up all Tailscale files
• Optionally remove firewall rules
• Update bootstrap configuration

After removing an overlay network, you can run bootstrap.sh again to configure a different provider.

Troubleshooting

ZeroTier not connecting?

# Check service status
sudo systemctl status zerotier-one

# Restart service
sudo systemctl restart zerotier-one

# Check if joined network
sudo zerotier-cli listnetworks

Tailscale not connecting?

# Check Tailscale status
tailscale status

# Re-authenticate
sudo tailscale up

# Check logs
sudo journalctl -u tailscaled -f

Can't SSH to node?

# Verify SSH is running
sudo systemctl status ssh

# Check firewall
sudo ufw status

# Verify user exists (it will use your existing Ubuntu user)
id $USER

Security Notes

• The bootstrap script doesn't store any secrets
• Overlay network credentials are only used during setup
• Uses your existing Ubuntu user for Ansible automation
• All overlay network traffic is encrypted
• ZeroTier: Nodes must be explicitly authorized in your network
• Tailscale: Uses WireGuard encryption, nodes authorized via auth key

Support

For issues or questions:

• GitHub Issues
• Thinkube Documentation

License

Apache License 2.0 - See LICENSE file