homelab-optimized/docs/infrastructure/SSH_ACCESS_GUIDE.md

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:

# 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:

# 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:

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

Add your homelab servers:

# ~/.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:

chmod 600 ~/.ssh/config

Step 4: Test Connections

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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

# 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

# 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

# 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

# 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

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

Common Commands

# 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

# 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.