Damp

DevContainers

VS Code DevContainer integration for development

DAMP creates a VS Code DevContainer setup for every project. The development environment runs inside Docker containers.

Project Structure

DAMP generates these files:

devcontainer.json
launch.json
Dockerfile
docker-compose.yml
.dockerignore
public/index.php

DevContainer Configuration

devcontainer.json

{
  "name": "myproject",

  "workspaceMount": "source=damp_project_myproject,target=/var/www/html,type=volume",
  "workspaceFolder": "/var/www/html",

  "build": {
    "dockerfile": "../Dockerfile",
    "context": "..",
    "target": "development",
    "args": {
      "USER_ID": "${localEnv:UID:1000}",
      "GROUP_ID": "${localEnv:GID:1000}"
    }
  },

  "remoteUser": "www-data",

  "runArgs": [
    "--network=damp-network",
    "--label=com.pickleboxer.damp.managed=true",
    "--label=com.pickleboxer.damp.type=project-container"
  ],

  "forwardPorts": [8443],

  "customizations": {
    "vscode": {
      "extensions": [
        "xdebug.php-debug",
        "bmewburn.vscode-intelephense-client",
        "streetsidesoftware.code-spell-checker"
      ]
    }
  },

  "postCreateCommand": "[ -f composer.json ] && composer install || true; [ -f package.json ] && npm install && npm run build || true"
}

Key Settings:

  • Network: damp-network (connects to Caddy reverse proxy and services)
  • Volume: Named Docker volume damp_project_{name}
  • User: Runs as www-data (UID/GID: 1000)
  • Port: Forwards port 8443 (HTTPS)
  • Labels: Docker labels for DAMP management

Docker Configuration

Dockerfile

DAMP uses a multi-stage Dockerfile:

Base Image: serversideup/php:{version}-{variant}

Stages:

  1. base - Base PHP image with required extensions
  2. development - Adds Xdebug, git, zsh, Oh My Zsh
  3. production - Production-optimized build

PHP Variants:

  • fpm-apache - Apache with PHP-FPM
  • fpm-nginx - Nginx with PHP-FPM
  • frankenphp - FrankenPHP server
  • fpm - PHP-FPM only

Development Tools:

  • Git
  • Zsh with Oh My Zsh
  • Xdebug (mode: develop,debug,trace,coverage,profile)
  • Node.js (optional: versions 20, 22, 24, 25, lts, latest)

Xdebug Configuration

xdebug.mode = develop,debug,trace,coverage,profile
xdebug.start_with_request = trigger
xdebug.client_port = 9003

Docker Volumes

DAMP uses named Docker volumes:

Volume Pattern: damp_project_{projectName}

Configuration:

{
  "workspaceMount": "source=damp_project_myproject,target=/var/www/html,type=volume",
  "workspaceFolder": "/var/www/html"
}

Volume Labels:

  • com.pickleboxer.damp.managed=true
  • com.pickleboxer.damp.type=project-volume
  • com.pickleboxer.damp.project-id={UUID}

Named volumes provide faster I/O on Windows compared to bind mounts.

PHP Extensions

Pre-installed Extensions

Always Included:

  • ctype, curl, dom, fileinfo, filter, hash, mbstring, openssl, pcre, session, tokenizer
  • xml, opcache, mysqli, pcntl, pdo_mysql, pdo_pgsql, redis, zip
  • xdebug

User-Selectable Extensions:

  • bcmath, gd, intl, memcached, imagick, soap, xsl, apcu, sodium, exif, ldap, pgsql

Extensions are installed using install-php-extensions script.

Network Architecture

┌────────────────────────────────────────┐
│    Docker Network: damp-network        │
├────────────────────────────────────────┤
│                                        │
│  ┌──────────────────────┐              │
│  │  Caddy Reverse Proxy │              │
│  │  (damp-caddy)        │              │
│  └──────────┬───────────┘              │
│             │                          │
│             │ Routes to containers     │
│             ↓                          │
│  ┌──────────────────────┐              │
│  │ Project Container    │              │
│  │ PHP + Apache/Nginx   │              │
│  │ Port: 8443 (HTTPS)   │              │
│  └──────────┬───────────┘              │
│             │                          │
│             │ Connects to services     │
│             ↓                          │
│  ┌──────────────────────┐              │
│  │  MySQL / PostgreSQL  │              │
│  │  (damp-mysql)        │              │
│  └──────────────────────┘              │
│                                        │
└────────────────────────────────────────┘

Container Discovery: DAMP identifies containers using Docker labels, not container names.

VS Code Integration

Opening in DevContainer

  1. Open project folder in VS Code
  2. Click "Reopen in Container" notification
  3. VS Code builds and attaches to container
  4. Container runs as www-data user

Debugging

Press F5 to start debugging:

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

Set breakpoints in VS Code - Xdebug connects automatically.

Post-Create Command

Runs once after container creation:

[ -f composer.json ] && composer install || true;
[ -f package.json ] && npm install && npm run build || true

Behavior:

  • Installs Composer dependencies if composer.json exists
  • Installs npm dependencies and runs build if package.json exists
  • Non-blocking - failures don't stop container creation

Customization

Add PHP Extensions

Edit Dockerfile to add extensions via install-php-extensions.

Change PHP Version

Edit Dockerfile ARG PHP_VERSION value (7.4, 8.1, 8.2, 8.3, 8.4).

Add VS Code Extensions

Edit devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": ["bmewburn.vscode-intelephense-client", "xdebug.php-debug"]
    }
  }
}

Rebuild Container

After configuration changes:

  1. Press Ctrl+Shift+P in VS Code
  2. Run "Dev Containers: Rebuild Container"

Troubleshooting

Custom Domains

Local domains for every project with automatic hosts file management

System Isolation

Docker isolation for clean system

On this page

Project StructureDevContainer Configurationdevcontainer.jsonDocker ConfigurationDockerfileXdebug ConfigurationDocker VolumesPHP ExtensionsPre-installed ExtensionsNetwork ArchitectureVS Code IntegrationOpening in DevContainerDebuggingPost-Create CommandCustomizationAdd PHP ExtensionsChange PHP VersionAdd VS Code ExtensionsRebuild ContainerTroubleshooting