# Headscale Setup & Connection Guide

> Generated: 2025-11-11
> Server: tower-of-joy
> Network Range: 10.99.0.0/16

## Service Status

✅ **Headscale is running**
- Container: `headscale`
- Web/API Port: `8085`
- Metrics Port: `9090`
- Server URL: `http://192.168.86.149:8085`

## User & Authentication

**User Created:** `homelab` (ID: 1)

**Pre-Auth Key (expires in 30 days, reusable):**
```
b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
```

⚠️ **Security Note:** This key allows devices to join your mesh network. Keep it secure and regenerate after use if needed.

---

## Connecting This Server (tower-of-joy)

### Step 1: Install Tailscale Client

```bash
curl -fsSL https://tailscale.com/install.sh | sh
```

### Step 2: Connect to Headscale

```bash
sudo tailscale up --login-server=http://192.168.86.149:8085 \
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634 \
  --accept-routes
```

### Step 3: Verify Connection

```bash
# Check Tailscale status
sudo tailscale status

# Get your mesh IP (should be in 10.99.x.x range)
sudo tailscale ip -4

# Test connectivity
ping $(tailscale ip -4)
```

---

## Connecting Other Devices (Laptop, Phone, etc.)

### On Linux/macOS

```bash
# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Connect to your Headscale server
sudo tailscale up --login-server=http://192.168.86.149:8085 \
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
```

### On Windows

1. Download Tailscale from https://tailscale.com/download/windows
2. Install and open Tailscale
3. Run in PowerShell (as Administrator):
```powershell
tailscale up --login-server=http://192.168.86.149:8085 `
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
```

### On Android/iOS

1. Install Tailscale app from app store
2. Open app settings
3. Set "Control URL" to: `http://192.168.86.149:8085`
4. Use auth key: `b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634`

---

## Testing Remote SSH Access

Once devices are connected to the mesh:

```bash
# From your laptop (after connecting to Headscale)

# Get tower-of-joy's mesh IP
ssh jpmschweitzer@<tower-mesh-ip>

# Example (your actual IP will be something like 10.99.0.1)
ssh jpmschweitzer@10.99.0.1
```

**Benefits:**
- No port forwarding needed
- No exposing SSH to internet
- Encrypted peer-to-peer connections
- Works from anywhere

---

## Headscale Management Commands

### List All Connected Devices
```bash
docker exec headscale headscale nodes list
```

### List Users
```bash
docker exec headscale headscale users list
```

### Generate New Pre-Auth Key
```bash
# 7 days, single-use
docker exec headscale headscale preauthkeys create --user 1 --expiration 168h

# 30 days, reusable
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable
```

### List Pre-Auth Keys
```bash
docker exec headscale headscale preauthkeys list --user 1
```

### Remove a Device
```bash
# First, get the node ID
docker exec headscale headscale nodes list

# Then delete by ID
docker exec headscale headscale nodes delete <node-id>
```

---

## Troubleshooting

### Can't Connect to Headscale Server

1. **Check if Headscale is running:**
```bash
docker ps | grep headscale
```

2. **Check firewall (if connecting from external network):**
```bash
sudo ufw status
# If needed: sudo ufw allow 8085/tcp
```

3. **View Headscale logs:**
```bash
docker logs headscale --tail 50
```

### Devices Can't See Each Other

1. **Check device is registered:**
```bash
docker exec headscale headscale nodes list
```

2. **Verify IPs are in the 10.99.0.0/16 range:**
```bash
sudo tailscale ip -4
```

3. **Test direct ping:**
```bash
ping <other-device-mesh-ip>
```

### Need to Regenerate Keys

```bash
# Create new auth key
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable

# Update this document with the new key
```

---

## Configuration File Location

**Config:** `/home/jpmschweitzer/docker-data/headscale/config/config.yaml`
**Database:** `/home/jpmschweitzer/docker-data/headscale/data/db.sqlite`

To edit configuration:
1. Edit the config file
2. Restart container: `docker restart headscale`
3. Verify: `docker logs headscale --tail 20`

---

## Next Steps After Setup

1. ✅ Connect tower-of-joy to Headscale
2. ✅ Connect your laptop/work devices
3. ✅ Test SSH access from laptop to server
4. ✅ Configure SSH key authentication for security
5. ⚡ Add phone/tablet for remote monitoring
6. ⚡ Set up exit node (optional - route all traffic through home)

---

## Resources

- **Headscale Docs:** https://headscale.net/
- **Tailscale Client Docs:** https://tailscale.com/kb/
- **Container Logs:** `docker logs headscale -f`
- **Portainer:** http://192.168.86.149:8001