# VS Code SSH Setup for TrueNAS

## Overview

Configure VS Code to SSH into your TrueNAS server for easy file editing and terminal access.

---

## Prerequisites

1. **VS Code installed** on your local machine
2. **Remote - SSH extension** installed in VS Code
3. **SSH access enabled** on TrueNAS
4. **TrueNAS IP address** or hostname

---

## Step 1: Install VS Code Extension

### Install Remote - SSH Extension

1. Open VS Code
2. Click Extensions icon (or `Ctrl+Shift+X`)
3. Search for: **Remote - SSH**
4. Install the extension by Microsoft
5. Reload VS Code if prompted

**Extension ID:** `ms-vscode-remote.remote-ssh`

---

## Step 2: Enable SSH on TrueNAS (if not already enabled)

### TrueNAS Scale

1. Navigate to **System Settings → Services**
2. Find **SSH** service
3. Click **Edit** (pencil icon)
4. Configure:
   - ☑ **Allow Password Authentication** (initially, we'll use keys later)
   - ☑ **Allow TCP Forwarding**
   - Port: **22** (default)
5. Click **Save**
6. **Start** the SSH service
7. ☑ **Start Automatically** (enable)

---

## Step 3: Find Your TrueNAS Connection Details

### Get TrueNAS IP Address

**Option A: From TrueNAS UI**
- Dashboard → Top right shows IP address

**Option B: From Shell**
```bash
ip addr show | grep inet
```

### Get Your Username

**Default admin user:** `admin`

Or check: **Credentials → Local Users**

---

## Step 4: Generate SSH Key (Recommended)

**On your local Windows machine (WSL or PowerShell):**

### Using WSL (Recommended)

```bash
# Generate SSH key
ssh-keygen -t ed25519 -C "truenas-access"

# Default location: ~/.ssh/id_ed25519
# Press Enter to accept
# Enter passphrase (optional but recommended)

# Copy public key to TrueNAS
ssh-copy-id admin@truenas-ip

# Or manually copy:
cat ~/.ssh/id_ed25519.pub
# Then paste into TrueNAS UI
```

### Using PowerShell (Alternative)

```powershell
# Generate SSH key
ssh-keygen -t ed25519 -C "truenas-access"

# Location: C:\Users\Vince\.ssh\id_ed25519
# Copy public key
Get-Content C:\Users\Vince\.ssh\id_ed25519.pub
```

### Add Public Key to TrueNAS

1. TrueNAS UI → **Credentials → Local Users**
2. Click **Edit** on your user (admin)
3. Scroll to **SSH Public Key**
4. Paste your public key
5. Click **Save**

---

## Step 5: Configure SSH Config File

Create/edit SSH config for easy connections.

### Location

**WSL:** `~/.ssh/config`
**Windows:** `C:\Users\Vince\.ssh\config`

### Add TrueNAS Configuration

```bash
Host truenas
    HostName 192.168.1.XXX          # Your TrueNAS IP
    User admin                       # Your TrueNAS username
    Port 22
    IdentityFile ~/.ssh/id_ed25519  # Path to your SSH key
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

# Optional: Shorter alias
Host nas
    HostName 192.168.1.XXX
    User admin
    IdentityFile ~/.ssh/id_ed25519
```

**Replace:** `192.168.1.XXX` with your actual TrueNAS IP

### Test SSH Connection

```bash
ssh truenas
# or
ssh nas
```

Should connect without password!

---

## Step 6: Connect VS Code to TrueNAS

### Method 1: Using Command Palette

1. Open VS Code
2. Press `Ctrl+Shift+P` (or `F1`)
3. Type: **Remote-SSH: Connect to Host**
4. Select **truenas** (or **nas**) from the list
   - Or type: `admin@truenas-ip` manually
5. Select platform: **Linux**
6. VS Code will connect and install VS Code Server on TrueNAS
7. Wait for connection to complete

### Method 2: Using SSH Targets

1. Click **Remote Explorer** icon in sidebar
2. Under **SSH Targets**, you'll see configured hosts
3. Click **→** (Connect) next to **truenas**

### First Connection

- VS Code will install **VS Code Server** on TrueNAS (~100MB)
- This is a one-time setup
- May take 1-2 minutes
- You'll see progress in bottom right

---

## Step 7: Navigate to Your Stacks Directory

Once connected:

1. **File → Open Folder**
2. Type: `/mnt/tank/stacks`
3. Click **OK**
4. VS Code now shows your stacks directory in explorer!

---

## Step 8: Install Helpful Extensions (Remote)

Once connected to TrueNAS, install these extensions **on the remote**:

### Recommended Extensions

1. **Docker** (`ms-azuretools.vscode-docker`)
   - Syntax highlighting for docker-compose files
   - Docker commands integration

2. **YAML** (`redhat.vscode-yaml`)
   - YAML syntax validation
   - Auto-completion

3. **Remote - SSH: Editing Configuration Files** (automatic)
   - Edit SSH config directly from VS Code

### Install Extensions on Remote

1. Click **Extensions** icon
2. Search for extension
3. Click **Install in SSH: truenas**
4. Extensions install on the TrueNAS server

---

## Usage Tips

### Open Terminal in VS Code

- **Terminal → New Terminal** (`` Ctrl+` ``)
- Opens bash terminal directly on TrueNAS
- Already in the folder you have open

### Edit docker-compose Files

1. Navigate to `/mnt/tank/stacks/traefik/`
2. Edit `docker-compose.yml`
3. Syntax highlighting and validation included
4. Save with `Ctrl+S`

### Run Docker Commands

```bash
# In VS Code terminal
cd /mnt/tank/stacks/traefik
docker compose up -d
docker logs traefik -f
```

### Multiple Folders

Open workspace with multiple stack directories:
1. **File → Add Folder to Workspace**
2. Add `/mnt/tank/stacks/traefik`
3. Add `/mnt/tank/stacks/gitea`
4. Add `/mnt/tank/stacks/servarr`
5. **File → Save Workspace As** → `truenas-stacks.code-workspace`

---

## Troubleshooting

### Connection Refused

```bash
# Check SSH service is running on TrueNAS
# TrueNAS UI → System → Services → SSH → Running

# Test from terminal
ssh admin@truenas-ip
```

### Permission Denied (publickey)

```bash
# Verify public key is added to TrueNAS
# TrueNAS UI → Credentials → Local Users → Edit → SSH Public Key

# Or enable password authentication temporarily
# TrueNAS UI → System → Services → SSH → Edit
# ☑ Allow Password Authentication
```

### VS Code Server Installation Fails

```bash
# SSH into TrueNAS manually
ssh truenas

# Check available disk space
df -h

# VS Code Server needs ~100MB in home directory
# Clear space if needed
```

### "Could not establish connection"

```bash
# Check VS Code settings
# Ctrl+, → Search "remote.SSH.path"
# Should point to ssh executable

# Windows: C:\Windows\System32\OpenSSH\ssh.exe
# WSL: /usr/bin/ssh
```

### Wrong Platform Detected

If VS Code thinks TrueNAS is Windows/Mac:
1. `Ctrl+Shift+P`
2. **Remote-SSH: Settings**
3. Add to `settings.json`:
   ```json
   "remote.SSH.remotePlatform": {
       "truenas": "linux"
   }
   ```

---

## Security Best Practices

### Disable Password Authentication (After Key Setup)

Once SSH keys are working:

1. TrueNAS UI → **System → Services → SSH → Edit**
2. ☐ **Allow Password Authentication** (uncheck)
3. ☑ **Login as Root with Password** (uncheck)
4. Click **Save**

Now only SSH key authentication is allowed.

### Use SSH Key Passphrase

When generating keys, add a passphrase:
```bash
ssh-keygen -t ed25519 -C "truenas-access"
# Enter passphrase when prompted
```

Use `ssh-agent` to avoid typing passphrase repeatedly:
```bash
# Start ssh-agent (WSL)
eval "$(ssh-agent -s)"

# Add key
ssh-add ~/.ssh/id_ed25519

# Enter passphrase once
# Key is cached for session
```

### Firewall Considerations

If accessing TrueNAS from outside your network:
- **Don't expose SSH (port 22) directly to internet**
- Use VPN (Tailscale, Wireguard) instead
- Or use SSH tunneling through a bastion host

---

## Quick Reference

### Connect to TrueNAS

```bash
# Command line
ssh truenas

# VS Code
Ctrl+Shift+P → Remote-SSH: Connect to Host → truenas
```

### Common Paths

- **Stacks:** `/mnt/tank/stacks/`
- **Configs:** `/mnt/tank/configs/`
- **Media:** `/mnt/tank/media/`

### Useful VS Code Shortcuts

- **Open Terminal:** `` Ctrl+` ``
- **Command Palette:** `Ctrl+Shift+P`
- **Open Folder:** `Ctrl+K Ctrl+O`
- **Search Files:** `Ctrl+P`
- **Save:** `Ctrl+S`
- **Close Remote:** Click **SSH: truenas** in bottom left → **Close Remote Connection**

---

## Next Steps

- [ ] Install Remote - SSH extension in VS Code
- [ ] Enable SSH service on TrueNAS
- [ ] Generate SSH key on local machine
- [ ] Add public key to TrueNAS
- [ ] Configure ~/.ssh/config with TrueNAS host
- [ ] Test SSH connection from terminal
- [ ] Connect VS Code to TrueNAS
- [ ] Open `/mnt/tank/stacks` folder in VS Code
- [ ] Install Docker and YAML extensions (remote)
- [ ] Disable password authentication (after key setup)
- [ ] Create workspace for multiple stack folders

---

## Resources

- [VS Code Remote - SSH Documentation](https://code.visualstudio.com/docs/remote/ssh)
- [TrueNAS Scale SSH Documentation](https://www.truenas.com/docs/scale/scaletutorials/systemsettings/services/configuringsshservice/)