freealberta/mkdocs/docs/adv/vscode-ssh.md

Remote Development with VSCode over Tailscale

Overview

This guide shows you how to set up Visual Studio Code for remote development on your servers using the Tailscale network. This allows you to develop directly on your remote ThinkCentre units as if they were local machines, with full access to files, terminals, and debugging capabilities.

What You'll Learn

• How to configure VSCode for remote SSH connections
• How to set up remote development environments
• How to manage multiple remote servers efficiently
• How to troubleshoot common remote development issues
• Best practices for remote development workflows

Prerequisites

• Completed the Ansible + Tailscale setup from the previous guide
• VSCode installed on your local machine (master node)
• Working SSH access to remote servers via Tailscale
• Tailscale running on both local and remote machines

Verify Prerequisites

Before starting, ensure your setup is working:

# Check Tailscale connectivity
tailscale status

# Test SSH access
ssh bunker-admin@100.125.148.60

# Check VSCode is installed
code --version

Part 1: Install and Configure Remote-SSH Extension

1. Install the Remote Development Extensions

Option A: Install Remote Development Pack (Recommended)

1. Open VSCode
2. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac)
3. Search for "Remote Development"
4. Install the Remote Development extension pack by Microsoft

This pack includes:

• Remote - SSH
• Remote - SSH: Editing Configuration Files
• Remote - Containers
• Remote - WSL (Windows only)

Option B: Install Individual Extension

1. Search for "Remote - SSH"
2. Install Remote - SSH by Microsoft

2. Verify Installation

After installation, you should see:

• Remote Explorer icon in the Activity Bar (left sidebar)
• "Remote-SSH" commands in Command Palette (Ctrl+Shift+P)

Part 2: Configure SSH Connections

1. Access SSH Configuration

Method A: Through VSCode

1. Press Ctrl+Shift+P to open Command Palette
2. Type "Remote-SSH: Open SSH Configuration File..."
3. Select your SSH config file (usually the first option)

Method B: Direct File Editing

# Edit SSH config file directly
nano ~/.ssh/config

2. Add Server Configurations

Add your servers to the SSH config file:

# Primary ThinkCentre Node
Host tc-node1
    HostName 100.125.148.60
    User bunker-admin
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

# Additional nodes (add as needed)
Host tc-node2
    HostName 100.x.x.x
    User bunker-admin
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Host tc-node3
    HostName 100.x.x.x
    User bunker-admin
    IdentityFile ~/.ssh/id_rsa
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Configuration Options Explained:

• Host: Friendly name for the connection
• HostName: Tailscale IP address
• User: Username on the remote server
• IdentityFile: Path to your SSH private key
• ForwardAgent: Enables SSH agent forwarding for Git operations
• ServerAliveInterval: Keeps connection alive (prevents timeouts)
• ServerAliveCountMax: Number of keepalive attempts

3. Set Proper SSH Key Permissions

# Ensure SSH config has correct permissions
chmod 600 ~/.ssh/config

# Verify SSH key permissions
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

Part 3: Connect to Remote Servers

1. Connect via Command Palette

1. Press Ctrl+Shift+P
2. Type "Remote-SSH: Connect to Host..."
3. Select your server (e.g., tc-node1)
4. VSCode will open a new window connected to the remote server

2. Connect via Remote Explorer

1. Click the Remote Explorer icon in Activity Bar
2. Expand SSH Targets
3. Click the connect icon next to your server name

3. Connect via Quick Menu

1. Click the remote indicator in bottom-left corner (looks like ><)
2. Select "Connect to Host..."
3. Choose your server from the list

4. First Connection Process

On first connection, VSCode will:

1. Verify the host key (click "Continue" if prompted)
2. Install VSCode Server on the remote machine (automatic)
3. Open a remote window with access to the remote file system

Expected Timeline:

• First connection: 1-3 minutes (installs VSCode Server)
• Subsequent connections: 10-30 seconds

Part 4: Remote Development Environment Setup

1. Open Remote Workspace

Once connected:

# In the VSCode terminal (now running on remote server)
# Navigate to your project
cd /home/bunker-admin/projects

# Open current directory in VSCode
code .

# Or open a specific project
code /opt/myproject

2. Install Extensions on Remote Server

Extensions need to be installed separately on the remote server:

Essential Development Extensions:

1. Python (Microsoft) - Python development
2. GitLens (GitKraken) - Enhanced Git capabilities
3. Docker (Microsoft) - Container development
4. Prettier - Code formatting
5. ESLint - JavaScript linting
6. Auto Rename Tag - HTML/XML tag editing

To Install:

1. Go to Extensions (Ctrl+Shift+X)
2. Find your desired extension
3. Click "Install in SSH: tc-node1" (not local install)

3. Configure Git on Remote Server

# In VSCode terminal (remote)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Test Git connectivity
git clone https://github.com/yourusername/yourrepo.git

Part 5: Remote Development Workflows

1. File Management

File Explorer:

• Shows remote server's file system
• Create, edit, delete files directly
• Drag and drop between local and remote (limited)

File Transfer:

# Upload files to remote (from local terminal)
scp localfile.txt bunker-admin@100.125.148.60:/home/bunker-admin/

# Download files from remote
scp bunker-admin@100.125.148.60:/remote/path/file.txt ./local/path/

2. Terminal Usage

Integrated Terminal:

• Press Ctrl+` to open terminal
• Runs directly on remote server
• Multiple terminals supported
• Full shell access (bash, zsh, etc.)

Common Remote Terminal Commands:

# Check system resources
htop
df -h
free -h

# Install packages
sudo apt update
sudo apt install nodejs npm

# Start services
sudo systemctl start nginx
sudo docker-compose up -d

3. Port Forwarding

Automatic Port Forwarding: VSCode automatically detects and forwards common development ports.

Manual Port Forwarding:

1. Open Ports tab in terminal panel
2. Click "Forward a Port"
3. Enter port number (e.g., 3000, 8080, 5000)
4. Access via http://localhost:port on local machine

Example: Web Development

# Start a web server on remote (port 3000)
npm start

# VSCode automatically suggests forwarding port 3000
# Access at http://localhost:3000 on your local machine

4. Debugging Remote Applications

Python Debugging:

// .vscode/launch.json on remote server
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

Node.js Debugging:

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Program",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/app.js"
        }
    ]
}

Part 6: Advanced Configuration

1. Workspace Settings

Create remote-specific settings:

// .vscode/settings.json (on remote server)
{
    "python.defaultInterpreterPath": "/usr/bin/python3",
    "terminal.integrated.shell.linux": "/bin/bash",
    "files.autoSave": "afterDelay",
    "editor.formatOnSave": true,
    "remote.SSH.remotePlatform": {
        "tc-node1": "linux"
    }
}

2. Multi-Server Management

Switch Between Servers:

1. Click remote indicator (bottom-left)
2. Select "Connect to Host..."
3. Choose different server

Compare Files Across Servers:

1. Open file from server A
2. Connect to server B in new window
3. Open corresponding file
4. Use "Compare with..." command

3. Sync Configuration

Settings Sync:

1. Enable Settings Sync in VSCode
2. Settings, extensions, and keybindings sync to remote
3. Consistent experience across all servers

Part 7: Project-Specific Setups

1. Python Development

# On remote server
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install packages
pip install flask django requests

# VSCode automatically detects Python interpreter

VSCode Python Configuration:

// .vscode/settings.json
{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true
}

2. Node.js Development

# On remote server
# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Create project
mkdir myapp && cd myapp
npm init -y
npm install express

3. Docker Development

# On remote server
# Install Docker (if not already done via Ansible)
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER

# Create Dockerfile
cat > Dockerfile << EOF
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
EOF

VSCode Docker Integration:

• Install Docker extension on remote
• Right-click Dockerfile → "Build Image"
• Manage containers from VSCode interface

Part 8: Troubleshooting Guide

Common Connection Issues

Problem: "Could not establish connection to remote host"

Solutions:

# Check Tailscale connectivity
tailscale status
ping 100.125.148.60

# Test SSH manually
ssh bunker-admin@100.125.148.60

# Check SSH config syntax
ssh -T tc-node1

Problem: "Permission denied (publickey)"

Solutions:

# Check SSH key permissions
chmod 600 ~/.ssh/id_rsa
chmod 600 ~/.ssh/config

# Verify SSH agent
ssh-add ~/.ssh/id_rsa
ssh-add -l

# Test SSH connection verbosely
ssh -v bunker-admin@100.125.148.60

Problem: "Host key verification failed"

Solutions:

# Remove old host key
ssh-keygen -R 100.125.148.60

# Or disable host key checking (less secure)
# Add to SSH config:
# StrictHostKeyChecking no

VSCode-Specific Issues

Problem: Extensions not working on remote

Solutions:

1. Install extensions specifically for remote server
2. Check extension compatibility with remote development
3. Reload VSCode window: Ctrl+Shift+P → "Developer: Reload Window"

Problem: Slow performance

Solutions:

• Use .vscode/settings.json to exclude large directories:

{
    "files.watcherExclude": {
        "**/node_modules/**": true,
        "**/.git/objects/**": true,
        "**/dist/**": true
    }
}

Problem: Terminal not starting

Solutions:

# Check shell path in remote settings
"terminal.integrated.shell.linux": "/bin/bash"

# Or let VSCode auto-detect
"terminal.integrated.defaultProfile.linux": "bash"

Network and Performance Issues

Problem: Connection timeouts

Solutions: Add to SSH config:

ServerAliveInterval 60
ServerAliveCountMax 3
TCPKeepAlive yes

Problem: File transfer slow

Solutions:

• Use .vscodeignore to exclude unnecessary files
• Compress large files before transfer
• Use rsync for large file operations:

rsync -avz --progress localdir/ bunker-admin@100.125.148.60:remotedir/

Part 9: Best Practices

Security Best Practices

1. Use SSH keys, never passwords
2. Keep SSH agent secure
3. Regular security updates on remote servers
4. Use VSCode's secure connection verification

Performance Optimization

1. Exclude unnecessary files:

// .vscode/settings.json
{
    "files.watcherExclude": {
        "**/node_modules/**": true,
        "**/.git/**": true,
        "**/dist/**": true,
        "**/build/**": true
    },
    "search.exclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    }
}

2. Use remote workspace for large projects
3. Close unnecessary windows and extensions
4. Use efficient development workflows

Development Workflow

1. Use version control effectively:

# Always work in Git repositories
git status
git add .
git commit -m "feature: add new functionality"
git push origin main

2. Environment separation:

# Development
ssh tc-node1
cd /home/bunker-admin/dev-projects

# Production
ssh tc-node2
cd /opt/production-apps

3. Backup important work:

# Regular backups via Git
git push origin main

# Or manual backup
scp -r bunker-admin@100.125.148.60:/important/project ./backup/

Part 10: Team Collaboration

Shared Development Servers

SSH Config for Team:

# Shared development server
Host team-dev
    HostName 100.x.x.x
    User dev-user
    IdentityFile ~/.ssh/team_dev_key
    ForwardAgent yes

# Personal development
Host my-dev
    HostName 100.125.148.60
    User bunker-admin
    IdentityFile ~/.ssh/id_rsa

Project Structure

/opt/projects/
├── project-a/
│   ├── dev/          # Development branch
│   ├── staging/      # Staging environment
│   └── docs/         # Documentation
├── project-b/
└── shared-tools/     # Common utilities

Access Management

# Create shared project directory
sudo mkdir -p /opt/projects
sudo chown -R :developers /opt/projects
sudo chmod -R g+w /opt/projects

# Add users to developers group
sudo usermod -a -G developers bunker-admin

Quick Reference

Essential VSCode Remote Commands

# Command Palette shortcuts
Ctrl+Shift+P → "Remote-SSH: Connect to Host..."
Ctrl+Shift+P → "Remote-SSH: Open SSH Configuration File..."
Ctrl+Shift+P → "Remote-SSH: Kill VS Code Server on Host..."

# Terminal
Ctrl+` → Open integrated terminal
Ctrl+Shift+` → Create new terminal

# File operations
Ctrl+O → Open file
Ctrl+S → Save file
Ctrl+Shift+E → Focus file explorer

SSH Connection Quick Test

# Test connectivity
ssh -T tc-node1

# Connect with verbose output
ssh -v bunker-admin@100.125.148.60

# Check SSH config
ssh -F ~/.ssh/config tc-node1

Port Forwarding Commands

# Manual port forwarding
ssh -L 3000:localhost:3000 bunker-admin@100.125.148.60

# Background tunnel
ssh -f -N -L 8080:localhost:80 bunker-admin@100.125.148.60

Conclusion

This remote development setup provides:

• Full development environment on remote servers
• Seamless file access and editing capabilities
• Integrated debugging and terminal access
• Port forwarding for web development
• Extension ecosystem available remotely
• Secure connections through Tailscale network

The combination of VSCode Remote Development with Tailscale networking creates a powerful, flexible development environment that works from anywhere while maintaining security and performance.

Whether you're developing Python applications, Node.js services, or managing Docker containers, this setup provides a professional remote development experience that rivals local development while leveraging the power and resources of your remote servers.