DevContainer Development Environment¶

This document explains FastQTools development environment setup in DevContainer, including VS Code native support and Windsurf/Cursor SSH connection solutions.

Applicable Scenarios¶

Windows 11/10 + Docker Desktop (WSL2 backend)
VS Code + Dev Containers extension
Windsurf / Cursor (via SSH connection)

Environment Preparation¶

1. Repository Must be Opened in WSL2¶

Container bind mounts are more stable and performant under WSL2 Linux filesystem:

# Clone repository in WSL2
mkdir -p ~/lessup
cd ~/lessup
git clone git@github.com:<org>/<repo>.git fastq-tools

In VS Code, open ~/lessup/fastq-tools through Remote - WSL, then execute Reopen in Container.

2. SSH Agent Configuration¶

Container accesses private repositories through SSH Agent forwarding (without copying private keys into container):

# Start agent and load key in WSL
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Verify
ssh-add -l
ssh -T git@github.com

3. Git Identity Configuration¶

Container automatically mounts ~/.gitconfig from host WSL (read-only):

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

VS Code DevContainer¶

Two configuration options available:

Full configuration (.devcontainer/devcontainer.json): Uses docker-compose
Simple configuration (.devcontainer/devcontainer.simple.json): Single Dockerfile

Both provide: Clang/LLVM 21, CMake, Ninja, Conan, VS Code C++ extensions.

Daily Development¶

# Execute inside container
./scripts/core/build
./scripts/core/test
./scripts/core/lint

Windsurf / Cursor SSH Solution¶

Windsurf/Cursor doesn't fully support "Reopen in Container". The solution is to start sshd inside DevContainer and connect directly via SSH.

Implementation¶

Uses DevContainer lifecycle hooks + sshd self-daemonize:

postCreateCommand: Run setup-sshd.sh for one-time configuration
postStartCommand: Run start-sshd.sh to launch sshd on each start

sshd configuration: Port 2222, password login disabled, root login disabled, restricted to user developer.

Connection Steps¶

Local Development¶

Start container with VS Code Dev Containers (or devcontainer CLI)
Confirm postStartCommand has executed (sshd starts automatically)
Test connection:

ssh -p 2222 developer@127.0.0.1

Use Remote-SSH in Windsurf/Cursor:
Host: 127.0.0.1
Port: 2222
User: developer
Working directory: /workspace

Remote Host¶

Start DevContainer on remote host
Set FASTQTOOLS_SSH_BIND=0.0.0.0 (note firewall)
Connect directly from local Windsurf/Cursor to remote-host:2222

Port Configuration¶

Customize via environment variables:

FASTQTOOLS_SSH_BIND (default 127.0.0.1)
FASTQTOOLS_SSH_PORT (default 2222)

Quick Command Reference¶

# Manually start container
docker start fastqtools-dev

# Manually start sshd
docker exec fastqtools-dev bash /workspace/.devcontainer/scripts/start-sshd.sh

# SSH connection
ssh -p 2222 developer@localhost

Frequently Asked Questions¶

SSH Agent Not Detected¶

# Execute in WSL
eval "$(ssh-agent -s)" && ssh-add

# Then in VS Code Rebuild and Reopen in Container

Git Permission denied (publickey)¶

ssh-add -l          # Confirm key is loaded
ssh -T git@github.com  # Test connection

SSH Connection refused¶

Container not started or postStartCommand not executed
Check port mapping: docker port fastqtools-dev

SSH Permission denied (publickey)¶

Check if /home/developer/.ssh_authorized_keys exists in container and permissions are 0600

Slow Performance¶

Confirm repository is located in WSL2 Linux filesystem (not under Windows drive)
Cache uses named volumes or user directory

Security Recommendations¶

sshd only binds to 127.0.0.1 by default
When exposing externally, use with firewall
Password login disabled, public key authentication only