# SSH Access Guide for Homelab

This guide helps you set up secure SSH access to your homelab servers for deployment and management.

## 🎯 Overview

SSH access allows you to:
- **Deploy services directly** on servers
- **Troubleshoot issues** in real-time
- **Manage configurations** remotely
- **Transfer files** securely
- **Monitor services** and logs

## 🔑 Setting Up SSH Access

### Step 1: Generate SSH Key Pair

**On your local machine:**

```bash
# Generate a new SSH key (recommended: Ed25519)
ssh-keygen -t ed25519 -f ~/.ssh/homelab_key -C "your-email@example.com"

# Or use RSA if Ed25519 isn't supported
ssh-keygen -t rsa -b 4096 -f ~/.ssh/homelab_key -C "your-email@example.com"

# Set proper permissions
chmod 600 ~/.ssh/homelab_key
chmod 644 ~/.ssh/homelab_key.pub
```

### Step 2: Copy Public Key to Servers

**For each server in your homelab:**

```bash
# Copy public key to server (replace with your server details)
ssh-copy-id -i ~/.ssh/homelab_key.pub username@server-ip

# Or manually copy if ssh-copy-id isn't available
cat ~/.ssh/homelab_key.pub | ssh username@server-ip "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```

### Step 3: Configure SSH Client

Create an SSH config file for easy access:

```bash
# Create/edit SSH config
nano ~/.ssh/config
```

**Add your homelab servers:**

```bash
# ~/.ssh/config

# Main Synology NAS (Atlantis)
Host atlantis
    HostName 192.168.1.100
    User admin
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60

# Secondary Synology NAS (Calypso)
Host calypso
    HostName 192.168.1.101
    User admin
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60

# Primary VM (Homelab VM)
Host homelab-vm
    HostName 192.168.1.110
    User ubuntu
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60

# Physical NUC (Concord)
Host concord-nuc
    HostName 192.168.1.120
    User ubuntu
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60

# Raspberry Pi (Edge device)
Host rpi5-vish
    HostName 192.168.1.130
    User pi
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60
```

**Set proper permissions:**
```bash
chmod 600 ~/.ssh/config
```

### Step 4: Test Connections

```bash
# Test connection to each server
ssh atlantis
ssh calypso
ssh homelab-vm
ssh concord-nuc
ssh rpi5-vish
```

## 🚀 SSH-Based Deployment Workflow

### Method 1: Direct Docker Compose Deployment

```bash
# Connect to target server
ssh atlantis

# Navigate to docker directory
cd /volume1/docker

# Create service directory
mkdir my-new-service
cd my-new-service

# Create docker-compose.yml
nano docker-compose.yml

# Deploy the service
docker compose up -d

# Check status
docker compose ps
```

### Method 2: Git-Based Deployment

```bash
# Connect to server
ssh homelab-vm

# Clone/update repository
git clone https://git.vish.gg/Vish/homelab.git
cd homelab

# Deploy specific service
docker compose -f hosts/vms/homelab-vm/my-service.yml up -d
```

### Method 3: Remote File Transfer

```bash
# Copy compose file to server
scp hosts/synology/atlantis/my-service.yml atlantis:/volume1/docker/

# Connect and deploy
ssh atlantis
cd /volume1/docker
docker compose -f my-service.yml up -d
```

## 🛠️ Common SSH Tasks for Homelab

### Service Management

```bash
# Check running containers
ssh atlantis "docker ps"

# View service logs
ssh atlantis "docker compose -f /volume1/docker/service/docker-compose.yml logs -f"

# Restart a service
ssh atlantis "docker compose -f /volume1/docker/service/docker-compose.yml restart"

# Update and restart service
ssh atlantis "cd /volume1/docker/service && docker compose pull && docker compose up -d"
```

### System Monitoring

```bash
# Check system resources
ssh homelab-vm "htop"
ssh homelab-vm "df -h"
ssh homelab-vm "free -h"

# Check Docker status
ssh atlantis "docker system df"
ssh atlantis "docker system prune -f"
```

### File Management

```bash
# Copy files to server
scp local-file.txt atlantis:/volume1/docker/service/

# Copy files from server
scp atlantis:/volume1/docker/service/config.yml ./

# Sync directories
rsync -avz --progress ./local-dir/ atlantis:/volume1/docker/service/
```

## 🔒 Security Best Practices

### SSH Key Security

```bash
# Use SSH agent for key management
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/homelab_key

# List loaded keys
ssh-add -l

# Remove keys from agent
ssh-add -D
```

### Server Hardening

**On each server, consider:**

```bash
# Disable password authentication (after key setup)
sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
# Set: PubkeyAuthentication yes

# Restart SSH service
sudo systemctl restart sshd

# Change default SSH port (optional)
# Set: Port 2222

# Limit SSH access to specific users
# Set: AllowUsers yourusername
```

### Firewall Configuration

```bash
# Allow SSH through firewall
sudo ufw allow ssh
# Or for custom port:
sudo ufw allow 2222/tcp

# Enable firewall
sudo ufw enable
```

## 🚨 Troubleshooting SSH Issues

### Connection Problems

```bash
# Debug connection with verbose output
ssh -vvv atlantis

# Test specific port
ssh -p 22 atlantis

# Check if SSH service is running
ssh atlantis "sudo systemctl status sshd"
```

### Permission Issues

```bash
# Fix SSH directory permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/authorized_keys
```

### Key Issues

```bash
# Remove old host key (if server changed)
ssh-keygen -R atlantis
ssh-keygen -R 192.168.1.100

# Test key authentication
ssh -i ~/.ssh/homelab_key -o PreferredAuthentications=publickey atlantis
```

## 📋 Quick Reference

### SSH Config Template

```bash
Host HOSTNAME
    HostName IP_ADDRESS
    User USERNAME
    IdentityFile ~/.ssh/homelab_key
    Port 22
    ServerAliveInterval 60
    ServerAliveCountMax 3
    ConnectTimeout 10
```

### Common Commands

```bash
# Connect to server
ssh hostname

# Execute single command
ssh hostname "command"

# Copy files
scp file hostname:/path/
scp hostname:/path/file ./

# Port forwarding (access remote service locally)
ssh -L 8080:localhost:8080 hostname

# Background tunnel
ssh -f -N -L 8080:localhost:8080 hostname
```

### Server-Specific Paths

- **Synology NAS**: `/volume1/docker/`
- **Ubuntu VMs**: `/home/username/docker/` or `/opt/docker/`
- **Raspberry Pi**: `/home/pi/docker/`

## 🔗 Integration with Development Workflow

### Combined Git + SSH Workflow

```bash
# 1. Develop locally with validation
git add hosts/synology/atlantis/my-service.yml
git commit -m "feat: Add my-service"
git push

# 2. Deploy via SSH
ssh atlantis
cd /volume1/docker
git pull
docker compose -f ../homelab/hosts/synology/atlantis/my-service.yml up -d

# 3. Monitor deployment
docker compose ps
docker compose logs -f my-service
```

This gives you the best of both worlds: validated configurations and direct deployment control.

---

*With SSH access configured, you have full control over your homelab infrastructure while maintaining the safety of the GitOps workflow.*