Docker Volume Configuration Reference

Last Updated: 2025-10-13 Status: Technical Reference Audience: DevOps, System Administrators, Advanced Developers

---

Overview

This document provides comprehensive technical details for configuring Docker volume mounts for Coditect AI IDE in Volume Mount Mode (local development). This mode enables editing files on your host machine while running the IDE in a Docker container.

See Also:

• User Guide: development-modes.md
• Architecture Decision: docs/07-adr/adr-025-terminal-workspace-connectivity-options.md

---

Table of Contents

1. Quick Reference
2. Windows Configuration
3. macOS Configuration
4. Linux Configuration
5. WSL2 Configuration
6. Advanced Scenarios
7. Troubleshooting
8. Security Considerations

---

Quick Reference

Essential Volume Mounts

Mount	Purpose	Read-Only	Required
/workspace	Project files	No	✅ Yes
/root/.gitconfig	Git user config	Yes	⚠️ Recommended
/root/.ssh	SSH keys for git	Yes	⚠️ For git push/pull
/root/.bash_history	Shell history	No	❌ Optional

Minimal Configuration

docker run -d \
  -p 8080:80 \
  -v /path/to/projects:/workspace \
  --name coditect-dev \
  coditect-combined:test

Recommended Configuration (with Git)

docker run -d \
  -p 8080:80 \
  -v /path/to/projects:/workspace \
  -v /path/to/.gitconfig:/root/.gitconfig:ro \
  -v /path/to/.ssh:/root/.ssh:ro \
  --name coditect-dev \
  coditect-combined:test

---

Windows Configuration

Native Windows (Docker Desktop)

Prerequisites:

• Docker Desktop for Windows installed
• File sharing enabled for the drive (Settings → Resources → File Sharing)

PowerShell Configuration

# Define paths (adjust to your system)
$WORKSPACE = "C:\Users\YourUsername\Projects"
$GITCONFIG = "C:\Users\YourUsername\.gitconfig"
$SSH_DIR = "C:\Users\YourUsername\.ssh"

# Start container with volume mounts
docker run -d `
  -p 8080:80 `
  -p 3001:3000 `
  -v "${WORKSPACE}:/workspace" `
  -v "${GITCONFIG}:/root/.gitconfig:ro" `
  -v "${SSH_DIR}:/root/.ssh:ro" `
  --name coditect-dev `
  coditect-combined:test

Note: PowerShell uses backtick ` for line continuation, not backslash \

Command Prompt (cmd.exe) Configuration

REM Define paths
set WORKSPACE=C:\Users\YourUsername\Projects
set GITCONFIG=C:\Users\YourUsername\.gitconfig
set SSH_DIR=C:\Users\YourUsername\.ssh

REM Start container (single line, no continuation in cmd)
docker run -d -p 8080:80 -p 3001:3000 -v "%WORKSPACE%:/workspace" -v "%GITCONFIG%:/root/.gitconfig:ro" -v "%SSH_DIR%:/root/.ssh:ro" --name coditect-dev coditect-combined:test

Path Format Notes

Windows paths in Docker volumes:

• ✅ C:\Users\Hal\Projects (Windows native)
• ✅ C:/Users/Hal/Projects (Unix-style forward slashes)
• ✅ /c/Users/Hal/Projects (Git Bash style)
• ❌ \Users\Hal\Projects (missing drive letter)

Docker for Windows automatically converts:

C:\Users\Hal\Projects  →  /c/Users/Hal/Projects  →  /workspace

Line Ending Configuration (CRLF vs LF)

Problem: Windows uses CRLF (\r\n), Linux uses LF (\n)

Solution 1: Global Git Configuration (Recommended)

# On Windows host
git config --global core.autocrlf input

# Inside container
docker exec -it coditect-dev bash
git config --global core.autocrlf input
exit

Solution 2: Per-Repository .gitattributes

# In your project root (on host)
echo "* text=auto eol=lf" > .gitattributes
git add .gitattributes
git commit -m "fix: Normalize line endings to LF"

Solution 3: editor Configuration

// .vscode/settings.json (if using VS Code on host)
{
  "files.eol": "\n"
}

SSH Keys on Windows

Generate SSH key (PowerShell):

ssh-keygen -t ed25519 -C "your.email@example.com"
# Save to: C: Users YourUsername .ssh id_ed25519

Fix permissions (not required for Docker mount):

# Windows doesn't need chmod, but ensure file isn't corrupted
Get-Content C:\Users\YourUsername\.ssh\id_ed25519

Add to GitHub:

Get-Content C:\Users\YourUsername\.ssh\id_ed25519.pub
# Copy output and add to: https://github.com/settings/keys

Docker Desktop Settings

Required Settings:

1. Open Docker Desktop
2. Settings → Resources → File Sharing
3. Add C:\Users\YourUsername\Projects to allowed paths
4. Click "Apply & Restart"

Performance Optimization:

1. Settings → Resources → Advanced
2. Increase Memory to 8GB+ (recommended for IDE)
3. Increase CPUs to 4+ (recommended)

---

macOS Configuration

Prerequisites

• Docker Desktop for Mac installed
• File sharing automatically configured (uses osxfs)

Basic Configuration

# Define paths
WORKSPACE=~/Projects
GITCONFIG=~/.gitconfig
SSH_DIR=~/.ssh

# Start container
docker run -d \
  -p 8080:80 \
  -p 3001:3000 \
  -v "${WORKSPACE}:/workspace" \
  -v "${GITCONFIG}:/root/.gitconfig:ro" \
  -v "${SSH_DIR}:/root/.ssh:ro" \
  --name coditect-dev \
  coditect-combined:test

SSH Keys on macOS

Generate SSH key:

ssh-keygen -t ed25519 -C "your.email@example.com"
# Save to: /Users/YourUsername/.ssh/id_ed25519

# Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Add to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy and add to: https://github.com/settings/keys

Case-Sensitive Filesystem (APFS)

macOS default: Case-insensitive but case-preserving Container: Case-sensitive (Linux)

Potential Issues:

# On host (macOS)
MyFile.txt  # Can access as myfile.txt or MyFile.txt

# In container (Linux)
MyFile.txt  # ONLY accessible as MyFile.txt

Solution: Use consistent casing in all file references.

Docker Desktop for Mac Settings

Performance Optimization:

1. Docker Desktop → Preferences → Resources
2. Memory: 8GB+ (recommended for IDE)
3. CPUs: 4+ (recommended)
4. Disk image size: 60GB+ (if storing large projects)

VirtioFS (Faster file sharing):

1. Docker Desktop → Preferences → General
2. Enable "Use the new Virtualization framework"
3. Enable "VirtioFS accelerated directory sharing"

---

Linux Configuration

Prerequisites

• Docker installed (not Docker Desktop)
• User added to docker group

Basic Configuration

# Define paths
WORKSPACE=~/projects
GITCONFIG=~/.gitconfig
SSH_DIR=~/.ssh

# Start container
docker run -d \
  -p 8080:80 \
  -p 3001:3000 \
  -v "${WORKSPACE}:/workspace" \
  -v "${GITCONFIG}:/root/.gitconfig:ro" \
  -v "${SSH_DIR}:/root/.ssh:ro" \
  --name coditect-dev \
  coditect-combined:test

User and Permission Mapping

The Problem:

• Host user: uid=1000, gid=1000 (your user)
• Container process: uid=0, gid=0 (root)
• Files created in container: owned by root
• Files owned by root on host: require sudo to edit

Solution 1: Run container as your user (Recommended)

docker run -d \
  --user $(id -u):$(id -g) \
  -v ~/projects:/workspace \
  coditect-combined:test

Solution 2: Fix ownership after container operations

# After container creates/modifies files
sudo chown -R $USER:$USER ~/projects

Solution 3: Use Docker user namespace remapping

# /etc/docker/daemon.json
{
  "userns-remap": "default"
}

# Restart Docker
sudo systemctl restart docker

SSH Keys on Linux

Generate SSH key:

ssh-keygen -t ed25519 -C "your.email@example.com"
# Save to: /home/youruser/.ssh/id_ed25519

# Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Add to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy and add to: https://github.com/settings/keys

Inside Container (if needed):

docker exec -it coditect-dev bash

# Fix SSH key permissions
chmod 700 /root/.ssh
chmod 600 /root/.ssh/id_ed25519
chmod 644 /root/.ssh/id_ed25519.pub

# Test SSH connection
ssh -T git@github.com

SELinux Considerations (RHEL/CentOS/Fedora)

Problem: SELinux may block volume mounts

Solution: Use :z or :Z flag

# :z - Shared volume (multiple containers)
docker run -v ~/projects:/workspace:z coditect-combined:test

# :Z - Private volume (single container)
docker run -v ~/projects:/workspace:Z coditect-combined:test

Or disable SELinux for testing (NOT recommended for production):

sudo setenforce 0  # Temporary

---

WSL2 Configuration

Prerequisites

• Windows 11 or Windows 10 (version 2004+)
• WSL2 enabled
• Docker Desktop with WSL2 backend enabled

Method 1: Access WSL2 Filesystem from Windows

# From Windows PowerShell (accessing WSL2)
docker run -d `
  -p 8080:80 `
  -v \\wsl$\Ubuntu\home\youruser\projects:/workspace `
  -v \\wsl$\Ubuntu\home\youruser\.gitconfig:/root/.gitconfig:ro `
  -v \\wsl$\Ubuntu\home\youruser\.ssh:/root/.ssh:ro `
  --name coditect-dev `
  coditect-combined:test

Note: Use \\wsl$\<DistroName>\path format

Method 2: Run Docker from WSL2 terminal (Recommended)

# From WSL2 terminal (Ubuntu, Debian, etc.)
docker run -d \
  -p 8080:80 \
  -p 3001:3000 \
  -v ~/projects:/workspace \
  -v ~/.gitconfig:/root/.gitconfig:ro \
  -v ~/.ssh:/root/.ssh:ro \
  --name coditect-dev \
  coditect-combined:test

Advantage: Native Linux paths, better performance

Method 3: Access Windows Filesystem from WSL2

# From WSL2 terminal (accessing Windows C: drive)
docker run -d \
  -p 8080:80 \
  -v /mnt/c/Users/YourUsername/Projects:/workspace \
  coditect-combined:test

Warning: Slower performance due to 9P filesystem translation

WSL2 + Docker Desktop Integration

Docker Desktop Settings:

1. Docker Desktop → Settings → General
2. Enable "Use the WSL 2 based engine"
3. Settings → Resources → WSL Integration
4. Enable integration for your WSL2 distros (Ubuntu, Debian, etc.)

Performance Comparison

Scenario	Performance	Notes
WSL2 files → Docker	⚡ Excellent	Native Linux, best choice
Windows files → Docker	🐢 Slow	9P translation overhead
\wsl$\ mount	⚡ Good	Windows accessing WSL2

Recommendation: Store project files in WSL2 filesystem, not Windows.

---

Advanced Scenarios

Multiple workspace Mounts

Mount different directories to different paths:

docker run -d \
  -v ~/projects/frontend:/workspace/frontend \
  -v ~/projects/backend:/workspace/backend \
  -v ~/projects/shared:/workspace/shared \
  coditect-combined:test

Named Volumes for Persistence

Use Docker named volumes instead of bind mounts:

# Create named volume
docker volume create coditect-data

# Use named volume
docker run -d \
  -v coditect-data:/workspace \
  coditect-combined:test

# Backup volume
docker run --rm \
  -v coditect-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/coditect-backup.tar.gz /data

Read-Only Mounts

Mount configuration files as read-only:

docker run -d \
  -v ~/projects:/workspace \
  -v ~/.gitconfig:/root/.gitconfig:ro \
  -v ~/.ssh:/root/.ssh:ro \
  -v ~/custom-config.json:/app/config.json:ro \
  coditect-combined:test

Tmpfs Mounts (In-Memory)

Use tmpfs for temporary fast storage:

docker run -d \
  -v ~/projects:/workspace \
  --tmpfs /tmp:rw,size=1g,mode=1777 \
  coditect-combined:test

Network File Systems (NFS)

Mount remote NFS share:

# On host, mount NFS
sudo mount -t nfs remote-server:/export/projects /mnt/nfs-projects

# In container
docker run -d \
  -v /mnt/nfs-projects:/workspace \
  coditect-combined:test

Docker Compose Configuration

# docker-compose.yml
version: '3.8'

services:
  coditect-dev:
    image: coditect-combined:test
    ports:
      - "8080:80"
      - "3001:3000"
    volumes:
      - ~/projects:/workspace
      - ~/.gitconfig:/root/.gitconfig:ro
      - ~/.ssh:/root/.ssh:ro
      - bash-history:/root/.bash_history
    environment:
      - SESSION_ID=default
      - TERM=xterm-256color

volumes:
  bash-history:

Start with:

docker-compose up -d

---

Troubleshooting

Permission Denied Errors (Linux)

Error:

Permission denied: '/workspace/myfile.txt'

Solution:

# Run as your user
docker run --user $(id -u):$(id -g) ...

# Or fix ownership
sudo chown -R $USER:$USER ~/projects

---

Line Ending Issues (Windows)

Error:

bash: ./script.sh: /bin/bash^M: bad interpreter

Cause: CRLF line endings from Windows

Solution:

# Convert to LF
docker exec -it coditect-dev bash
dos2unix /workspace/script.sh

# Or configure git
git config --global core.autocrlf input

---

Git Push Authentication Failed

Error:

git push
fatal: Could not read from remote repository

Solution:

# Check SSH keys are mounted
docker exec -it coditect-dev ls -la /root/.ssh/

# Check SSH key permissions
docker exec -it coditect-dev bash
chmod 600 /root/.ssh/id_ed25519

# Test SSH connection
ssh -T git@github.com

---

File Changes Not Appearing

Issue: Edit file on host, but changes don't appear in container

Cause: Filesystem caching or notification issues

Solution:

# Check mount is correct
docker inspect coditect-dev | grep -A 10 Mounts

# Restart container
docker restart coditect-dev

# Or restart Docker Desktop (Windows/Mac)

---

Slow Performance (WSL2 on Windows)

Issue: File operations slow when accessing Windows filesystem from WSL2

Solution: Store files in WSL2 filesystem:

# SLOW (Windows → WSL2 → Docker)
/mnt/c/Users/Hal/Projects

# FAST (WSL2 → Docker)
~/projects  # /home/youruser/projects

---

SELinux Blocking Mount (Linux)

Error:

Error response from daemon: error while creating mount source path

Solution:

# Use :z or :Z flag
docker run -v ~/projects:/workspace:z coditect-combined:test

# Or check SELinux status
getenforce  # Should show "Enforcing" or "Permissive"

# Temporarily disable (testing only)
sudo setenforce 0

---

Docker Desktop File Sharing Not Enabled (Windows/Mac)

Error:

Error response from daemon: Mounts denied

Solution:

1. Open Docker Desktop
2. Settings → Resources → File Sharing (Windows) or File Sharing (Mac)
3. Add your project directory
4. Click "Apply & Restart"

---

Security Considerations

Principle of Least Privilege

Always use read-only mounts for sensitive files:

# ✅ GOOD - Read-only mounts
-v ~/.gitconfig:/root/.gitconfig:ro \
-v ~/.ssh:/root/.ssh:ro \

# ❌ BAD - Read-write access to SSH keys
-v ~/.ssh:/root/.ssh \

Avoid Mounting Entire Home Directory

# ❌ DANGEROUS - Exposes all files
-v ~:/host-home

# ✅ SAFE - Only mount needed directories
-v ~/projects:/workspace \
-v ~/.gitconfig:/root/.gitconfig:ro \
-v ~/.ssh:/root/.ssh:ro

Use Dedicated SSH Keys

Generate container-specific SSH keys:

# On host
ssh-keygen -t ed25519 -C "coditect-dev" -f ~/.ssh/id_ed25519_coditect

# Mount specific key
-v ~/.ssh/id_ed25519_coditect:/root/.ssh/id_ed25519:ro

Named Volumes vs Bind Mounts

Bind Mounts:

• ✅ Direct access to host files
• ✅ Easy backups (files on host)
• ❌ Less isolated
• ❌ Platform-specific paths

Named Volumes:

• ✅ Better isolated
• ✅ Platform-independent
• ✅ Better performance (on Mac/Windows)
• ❌ Harder to access directly

Recommendation: Use bind mounts for development, named volumes for production.

Secrets Management

Never mount secrets directly:

# ❌ BAD - Hardcoded secrets
-v ~/secrets.env:/app/.env

# ✅ GOOD - Use Docker secrets or env vars
docker run -d \
  -e API_KEY="$(cat ~/.secrets/api_key)" \
  coditect-combined:test

---

References

Official Documentation

• Docker Volumes: https://docs.docker.com/storage/volumes/
• Docker Bind Mounts: https://docs.docker.com/storage/bind-mounts/
• Docker on Windows: https://docs.docker.com/desktop/windows/
• Docker on Mac: https://docs.docker.com/desktop/mac/
• WSL2 Docker Integration: https://docs.docker.com/desktop/windows/wsl/

Internal Documentation

• Development Modes Guide: development-modes.md
• ADR-025: docs/07-adr/adr-025-terminal-workspace-connectivity-options.md
• Architecture: docs/DEFINITIVE-V5-architecture.md
• theia Wrapper: docs/V5-THEIA-WRAPPER-architecture.md

---

Last Updated: 2025-10-13 Version: 1.0.0 Status: Technical Reference