Remote Development — SSH, Codespaces, Dev Containers Guide

# Install Remote-SSH extension
code --install-extension ms-vscode-remote.remote-ssh

# Connect to a remote host
# Ctrl+Shift+P → "Remote-SSH: Connect to Host..."

# Or connect directly from the command line:
code --remote ssh-remote+dev-server /path/to/project

# ~/.ssh/config — SSH host configuration
Host dev-server
    HostName 192.168.1.100
    User developer
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_dev
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 5

Host build-server
    HostName build.internal.company.com
    User ci
    IdentityFile ~/.ssh/id_ed25519_ci
    RemoteForward 9229 localhost:9229
    LocalForward 3000 localhost:3000

// VS Code settings for Remote-SSH:
{
  "remote.SSH.showLoginTerminal": true,
  "remote.SSH.allowLocalForwarding": true,
  "remote.SSH.path": "/usr/bin/ssh",
  "remote.SSH.useLocalServer": true,
  "remote.SSH.connectTimeout": 30,
  "remote.SSH.extensions": [
    "ms-python.python",
    "dbaeumer.vscode-eslint",
    "eamodio.gitlens]
  ]
}

# Extensions can be installed locally (for UI) or remotely (for language support)
# Ctrl+Shift+P → "Extensions: Show Local Extensions"
# Ctrl+Shift+P → "Extensions: Show Remote Extensions"

# Remote extensions run on the server and provide language features:
# - Python, Pylance, Jupyter
# - ESLint, Prettier
# - GitLens, GitHub PRs
# - Docker

// .devcontainer/devcontainer.json — Codespaces configuration
{
  "name": "DodaTech API Development",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.12"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.black-formatter",
        "dbaeumer.vscode-eslint",
        "eamodio.gitlens",
        "github.copilot",
        "ms-azuretools.vscode-docker]
      ],
      "settings": {
        "editor.formatOnSave": true,
        "python.defaultInterpreterPath": "/usr/local/bin/python"
      }
    }
  },
  "forwardPorts": [3000, 8000, 5432],
  "portsAttributes": {
    "3000": { "label": "Frontend", "onAutoForward": "openBrowser" },
    "8000": { "label": "API", "onAutoForward": "notify" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" }
  },
  "postCreateCommand": "pip install -r requirements.txt && npm install",
  "remoteUser": "codespace"
}

# From GitHub repository:
# Code → Codespaces → Create codespace on main

# From CLI (requires gh CLI):
gh codespace create --repo dodatech/api --branch main

# List codespaces:
gh codespace list

# SSH into a codespace:
gh codespace ssh

# Delete a codespace:
gh codespace delete --codespace <name>

# Events that trigger lifecycle hooks:
# 1. prebuild (optional) — runs on repo push
# 2. create — first time codespace starts
# 3. postCreate — after container is ready
# 4. postAttach — every time you connect
# 5. postStart — after stop/start cycle

# Lifecycle scripts in devcontainer.json:
"postCreateCommand": "bash scripts/setup-dev.sh"
"postAttachCommand": "bash scripts/start-dev.sh"
"postStartCommand": "bash scripts/migrate-db.sh"

# Dockerfile — Development container
FROM ubuntu:22.04

# Install system dependencies
RUN apt-get update && apt-get install -y \
    python3.12 \
    python3-pip \
    nodejs \
    npm \
    git \
    curl \
    build-essential \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
COPY requirements.txt /tmp/
RUN pip3 install --no-cache-dir -r /tmp/requirements.txt

# Install Node packages
COPY package.json /tmp/
RUN cd /tmp && npm install

# Set working directory
WORKDIR /workspace

# Create non-root user
RUN useradd -m developer
USER developer

// .devcontainer/devcontainer.json — Dev Container configuration
{
  "name": "DodaTech Full Stack Dev",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",

  "mounts": [
    "source=${env:HOME}${env:USERPROFILE}/.ssh,target=/home/developer/.ssh,type=bind]
  ],

  "containerEnv": {
    "DATABASE_URL": "postgresql://dev:dev@db:5432/dodatech",
    "REDIS_URL": "redis://redis:6379",
    "NODE_ENV": "development"
  },

  "remoteUser": "developer",

  "postCreateCommand": "bash .devcontainer/setup.sh",

  "forwardPorts": [3000, 8000, 5432, 6379]
}

# docker-compose.yml — Multi-service development environment
version: "3.8"
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
      - ~/.ssh:/home/developer/.ssh:ro
    command: sleep infinity
    ports:
      - "3000:3000"
      - "8000:8000"
    depends_on:
      - db
      - redis

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: dodatech
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

volumes:
  postgres-data:

# VS Code Remote-SSH — automatic port forwarding
# When a server starts on port 3000, VS Code prompts to forward it
# Ctrl+Shift+P → "Remote-SSH: Forward Port"

# Manual port forwarding:
# View → Command Palette → "Forward a Port"
# Enter the port number (e.g., 3000)

# Codespaces — ports are forwarded automatically:
# Ports are listed in VS Code's "PORTS" tab
# You can set visibility: private, org, or public

# SSH local port forwarding:
ssh -L 3000:localhost:3000 dev-server

# SSH remote port forwarding:
ssh -R 9229:localhost:9229 dev-server

# 1. Use SSH keys, not passwords
ssh-keygen -t ed25519 -C "dev@dodatech.com"
ssh-copy-id dev-server

# 2. Use SSH config for host aliases
# (see SSH configuration section above)

# 3. Never commit .env or secrets files to repos
# Use Codespaces secrets: https://github.com/settings/codespaces

# 4. Use GitHub secrets for Codespaces:
gh secret set DATABASE_URL --repos dodatech/api

# 5. Restrict Codespace access:
# "codespaces: write" permission in GitHub settings
# IP allow lists for Codespaces in GitHub organization settings