vscode-sftp-config

---
name: vscode-sftp-config
description: This skill should be used when setting up SFTP deployment for static websites to production servers, including converting projects from Docker/Express to static hosting, deploying Vue/React/Angular builds, setting up Slidev presentations, or configuring Hugo/Jekyll/Gatsby sites. Use this when the user asks to "setup SFTP deployment", "deploy static site to server", "configure Nginx for static files", "convert from Docker to static hosting", "deploy Vue build to production", "setup subdomain hosting", or "configure SFTP in VS Code". Provides SFTP configuration templates and production-ready Nginx configurations with security headers and caching.
---

# VSCode SFTP Configuration

Configure VSCode SFTP for deploying static websites to production servers. Provides complete workflow including production-ready Nginx configuration templates with security headers, caching strategies, and performance optimizations.

## Core Workflow

### Step 1: Analyze Project Structure

Identify the static files to deploy:
- **Pure static projects**: HTML, CSS, JS in root directory
- **Build-based projects**: Look for `dist/`, `build/`, or `public/` output directories
- **Static generators**: Check for build commands in `package.json` or documentation

Ask the user for deployment details:
1. Remote server address (IP or hostname)
2. Remote path (e.g., `/var/www/sitename`)
3. SSH authentication method (password or SSH key path)
4. Domain name(s) for Nginx configuration
5. Whether this is a main domain or subdomain

### Step 2: Generate SFTP Configuration

**VSCode Extension**: This skill uses the [code-sftp](https://marketplace.visualstudio.com/items?itemName=satiromarra.code-sftp) extension by Satiro Marra.

#### Step 2A: Configure SSH Config (Recommended Best Practice)

Before creating `sftp.json`, set up SSH host alias in `~/.ssh/config` for better management:

```ssh-config
Host project-prod
    HostName 82.157.29.215
    User root
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

**Benefits of SSH config**:
- ✅ Eliminates SFTP extension warnings (`Section for 'IP' not found`)
- ✅ Use host alias in terminal: `ssh project-prod`
- ✅ Centralized SSH settings (connection keep-alive, compression, etc.)
- ✅ Easier to manage multiple environments (dev, staging, prod)

Check if `~/.ssh/config` already has the server:
```bash
cat ~/.ssh/config | grep -A 5 "82.157.29.215"
```

If found, use that existing host alias. If not, add a new entry.

#### Step 2B: Create SFTP Configuration

Create `.vscode/sftp.json` using the template from `assets/sftp.json.template`.

**Essential configuration fields**:
- `name`: Profile name for easy identification
- `host`: **SSH host alias** (e.g., `"Tencent_Pro"`) or IP address
- `protocol`: "sftp" for SFTP (secure) or "ftp" for FTP
- `port`: 22 for SFTP, 21 for FTP
- `username`: SSH/FTP username
- `privateKeyPath`: Path to SSH private key (e.g., `/Users/username/.ssh/id_rsa`)
- `remotePath`: Remote directory path (e.g., `/var/www/sitename`)
- `uploadOnSave`: `false` recommended (manual sync is safer)

**Optional advanced fields**:
- `ignore`: Array of files/folders to exclude from upload
- `watcher`: File watching configuration for auto-upload
- `syncOption`: Sync behavior (delete, update, skip existing files)
- `useTempFile`: Use temporary files during upload
- `downloadOnOpen`: Auto-download files when opened

Customize for the project:
- Replace `{{HOST_ALIAS}}` with SSH config alias (recommended) or IP address
- Replace other `{{PLACEHOLDERS}}` with actual values
- Add project-specific files to `ignore` array (`.claude`, `nginx.conf`, build artifacts, etc.)
- For build-based projects: Keep `uploadOnSave: false`, sync manually after build
- For pure static projects: Optionally enable `uploadOnSave: true` for instant deployment

### Step 3: Generate Nginx Configuration

Choose the appropriate template:
- **Main domain**: Use `assets/nginx-static.conf.template` for primary website
- **Subdomain**: Use `assets/nginx-subdomain.conf.template` for subdomains like `slides.example.com`

Customize the configuration:
1. Replace `{{DOMAIN}}` with actual domain name
2. Replace `{{DOCUMENT_ROOT}}` with remote path (e.g., `/var/www/aiseed`)
3. Adjust SSL certificate paths if using custom certificates
4. Configure subdomain-specific settings if needed

Include essential features from `references/nginx-best-practices.md`:
- HTTP → HTTPS redirect
- HTTP/2 support
- Gzip compression
- Static resource caching (1 year for JS/CSS/images, 1 hour for HTML)
- Security headers (HSTS, X-Frame-Options, CSP, etc.)
- Access and error logs

### Step 4: Provide Deployment Instructions

Generate a deployment checklist based on `assets/deploy-checklist.md`:

1. **Initial setup** (one-time):
   - Install VSCode extension: [code-sftp by Satiro Marra](https://marketplace.visualstudio.com/items?itemName=satiromarra.code-sftp)
   - Open Command Palette (Cmd/Ctrl+Shift+P) → `SFTP: Config` to create `.vscode/sftp.json`
   - Verify SSH access to server: `ssh user@host`
   - Ensure remote directory exists: `ssh user@host "mkdir -p /var/www/sitename"`
   - Set proper permissions: `ssh user@host "chmod 755 /var/www/sitename"`

2. **File deployment**:
   - For build projects: Run build command first (e.g., `npm run build`)
   - Open VSCode Command Palette → `SFTP: Sync Local → Remote` to upload all files
   - Or right-click folder in Explorer → "Upload Folder"
   - Monitor upload progress in VSCode Output panel (View → Output → SFTP)
   - Verify files uploaded: `ssh user@host "ls -la /var/www/sitename"`

3. **Nginx configuration**:
   - Upload generated config to `/etc/nginx/sites-available/`
   - Create symlink: `ln -s /etc/nginx/sites-available/site.conf /etc/nginx/sites-enabled/`
   - Test config: `sudo nginx -t`
   - Reload: `sudo systemctl reload nginx`

4. **SSL/TLS setup** (if not configured):
   - Refer to `references/ssl-security.md` for certificate setup
   - Use Let's Encrypt for free certificates: `certbot --nginx -d example.com`

5. **Verification**:
   - Test HTTPS: `curl -I https://example.com`
   - Check security headers: Use securityheaders.com
   - Test performance: Use PageSpeed Insights

### Step 5: Document the Setup

Update project documentation (README.md or CLAUDE.md) with:
- Deployment method (SFTP to `/var/www/path`)
- SFTP configuration location (`.vscode/sftp.json`)
- Nginx configuration reference
- Build commands (if applicable)
- Deployment workflow for future updates

## Benefits of This Architecture

Explain to users why static + SFTP deployment is advantageous:

1. **Simplicity**: Edit → Upload → Live (no build pipelines, no containers)
2. **Performance**: Nginx serves static files faster than Node.js/Python backends
3. **Reliability**: No backend processes to crash or hang
4. **Resource efficiency**: Lower server memory and CPU usage
5. **Cost effective**: Can host on minimal VPS or shared hosting
6. **Easy rollback**: Copy previous version from backup directory

## When NOT to Use This Architecture

Static + SFTP deployment is not appropriate when:
- Backend API endpoints are required
- Server-side form processing is needed (unless using external services like n8n, FormSpree)
- User authentication/sessions are required
- Database interactions are needed
- Server-side rendering (SSR) is required

## Resources

### references/
- `ssh-config.md` - SSH config file setup and best practices (host aliases, jump hosts, security)
- `nginx-best-practices.md` - Comprehensive Nginx optimization guide for static sites
- `ssl-security.md` - SSL/TLS certificate setup and security configuration

### assets/
- `sftp.json.template` - VSCode SFTP configuration template (array format, uses SSH host alias)
- `nginx-static.conf.template` - Main domain Nginx configuration template
- `nginx-subdomain.conf.template` - Subdomain Nginx configuration template
- `deploy-checklist.md` - Step-by-step deployment verification checklist