DevContainer Integration

DAMP provides seamless VS Code DevContainer integration, giving you a complete development environment inside Docker containers. All your development tools—PHP, Node.js, Composer, debugging tools—run inside containers while maintaining the familiar VS Code experience.

What are DevContainers?

DevContainers are a VS Code feature that lets you develop inside Docker containers:

Traditional Development

• Local toolchain required on host machine
• Version conflicts between projects
• Environment setup time for new team members
• “Works on my machine” syndrome

DevContainer Development

• Containerized toolchain - everything in Docker
• Consistent environments across team members
• Instant setup - clone and start coding
• Reproducible builds and deployments

Complete Isolation

Your development environment runs entirely in containers:

• PHP runtime with all extensions
• Database connections preconfigured
• Development tools (Composer, npm, etc.)
• Debugging tools (Xdebug) ready to use

VS Code Integration

Seamless VS Code experience:

• IntelliSense works with container runtime
• Extensions run inside container
• Terminal connected to container
• File editing with full container context

Zero Setup

New team members get instant environments:

• One-click startup from VS Code
• All dependencies pre-installed
• Debugging ready immediately
• Consistent configuration across team

How DAMP DevContainers Work

Automatic Configuration

DAMP automatically generates DevContainer configurations for every project:

// .devcontainer/devcontainer.json (auto-generated)
{
    "name": "Php Starter",
    "workspaceMount": "source=damp_site_php-starter,target=/workspace,type=volume",
    "workspaceFolder": "/workspace/php-starter",
    //"image": "mcr.microsoft.com/devcontainers/php:1-8.4",
    "build": {
        "dockerfile": "./Dockerfile",
        "context": ".",
        "args": {
            // Update VARIANT to pick a PHP version: 8, 8.1, 8.0, 7, 7.4
            // Append -bullseye or -buster to pin to an OS version.
            // Use -bullseye variants on local on arm64/Apple Silicon.
            "VARIANT": "8.4"
        }
    },
    // Features to add to the dev container. More info: https://containers.dev/features.
    "features": {
        "ghcr.io/devcontainers/features/node:1": {
            "version": "latest"
        },
        // "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}, // Add Claude AI feature
        "ghcr.io/opencodeco/devcontainers/install-php-extensions:0": {
            "extensions": "bcmath pdo_mysql pcntl mysqli intl zip gd gmagick"
        }
    },
    // Configure tool-specific properties.
    "customizations": {
        // Configure properties specific to VS Code.
        "vscode": {
            "settings": {},
            "extensions": [
                "streetsidesoftware.code-spell-checker"
            ]
        }
    },
    "mounts": [
        "source=damp_site_php-starter,target=/usr/local/etc/php/conf.d/php.ini,type=volume,volume-subpath=scroll/.devcontainer/php.ini",
        "source=damp_site_php-starter,target=/usr/local/etc/php/conf.d/z-xdebug.ini,type=volume,volume-subpath=scroll/.devcontainer/xdebug.ini"
    ],
    // Specify docker network(s) in devcontainer.json
    "runArgs": [
        "--network=devnet",
        "--name", "php-starter_devcontainer"
    ],
    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    "forwardPorts": [8080],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html && sudo service apache2 start"
    // Use 'postStartCommand' to run commands after the container starts.
    "postStartCommand": "php -S 0.0.0.0:8080"
    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
}

Folder structure:

• Directory.devcontainer

  • devcontainer.json
  • Dockerfile
  • php.ini
  • xdebug.ini
• Directory.vscode

  • launch.json
• Directorysrc

  • …
• index.php

Setting Up DevContainers

Automatic Setup (Recommended)

DAMP automatically configures DevContainers for new projects:

1. Create DAMP Project

   Use DAMP to create a new project.

2. Open in VS Code

   Click “Open in VS Code” from the DAMP project card.

3. Install DevContainer Extension

   VS Code will prompt to install the DevContainer extension if not present.

4. Reopen in Container

   VS Code will ask to “Reopen in Container” - click “Reopen in Container”.

5. Container Initialization

   Wait for container to build and initialize:

   • Dependencies installed (Composer, npm)
   • Extensions loaded in container
   • Development server started

Development Experience

Code Intelligence

DevContainers provide full IntelliSense and code intelligence:

PHP Development

• Intelephense language server running in container
• Full Laravel framework intelligence
• Composer packages automatically indexed
• PHP extensions properly recognized

Frontend Development

• Node.js tools available in container
• npm/yarn package management
• Asset compilation (Vite, Webpack)
• TypeScript support with proper Node.js context

Integrated Terminal

The VS Code terminal connects directly to your development container:

# Terminal runs inside PHP container
root@container:/php-starter$ php --version
PHP 8.2.10 (cli) (built: Aug 16 2023 15:20:18) (NTS)

# All development tools available
root@container:/php-starter$ composer install
root@container:/php-starter$ php artisan migrate
root@container:/php-starter$ npm run dev

File System Integration

Seamless file editing with container awareness:

• Source code copied to volume for speed improvements
• Git integration maintains proper file permissions

Debugging with DevContainers

Xdebug Configuration

DAMP pre-configures Xdebug for DevContainer debugging:

; Xdebug configuration (automatically configured)
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=VSCODE

VS Code Debug Setup

Launch configuration automatically created:

// .vscode/launch.json (auto-generated)
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

Read more about debugging with Xdebug Here: Xdebug Guide.

Advanced DevContainer Features

Custom Features

Add additional development tools:

{
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:1": {},
    "ghcr.io/devcontainers/features/aws-cli:1": {}
  }
}

VS Code Extensions

Add recommended extensions for your project:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "bmewburn.vscode-intelephense-client",
        "xdebug.php-debug",
        "onecentlin.laravel-blade",
        "codingyu.laravel-goto-view",
        "bradlc.vscode-tailwindcss"
      ]
    }
  }
}

Performance Optimization

Volume Strategy

DAMP optimizes DevContainer performance by using the named volume strategy. This approach enhances speed and efficiency. On Site creation DAMP copy the codebase to the named volume.

Build Optimization

Faster container builds:

# Multi-stage builds for efficiency
FROM php:8.2-fpm as base
RUN apt-get update && apt-get install -y \
    git unzip curl

FROM base as development
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

Resource Limits

Configure container resources:

{
  "runArgs": [
    "--memory=4g",
    "--cpus=2.0"
  ]
}

Troubleshooting DevContainers

Common Issues

Container Build Fails

Symptoms: DevContainer fails to build or start

Solutions:

1. Check Docker is running and accessible
2. Rebuild container: Ctrl+Shift+P → “DevContainers: Rebuild Container”
3. Clear Docker cache: docker system prune -a
4. Check DAMP project status in main interface

Debugging Not Connecting

Symptoms: Xdebug breakpoints not working

Solutions:

1. Verify Xdebug is enabled: php -m | grep xdebug
2. Check port forwarding in VS Code
3. Ensure path mappings are correct
4. Restart debug listener in VS Code

Best Practices

DevContainer Configuration

• Use official features from devcontainers/features
• Pin specific versions for reproducibility
• Minimize container size by removing unnecessary tools
• Use multi-stage builds for efficiency

VS Code Setup

• Install recommended extensions automatically
• Configure workspace settings for consistency
• Set up debugging configuration in version control
• Document any manual setup steps

DevContainer Pro Tips

• Use the command palette (Ctrl+Shift+P) for all DevContainer operations
• Rebuild regularly to get latest container updates
• Keep container images small for faster startup times

DevContainers with DAMP provide the ultimate development experience - all the benefits of containerization with the familiar VS Code interface you love.