How does it work?

DevContainer

The tool extends the abilities of DevContainers, so a good start would be looking at the (DevContainer specifications)[https://containers.dev/implementors/spec/] to get an idea of the underlying mechanism.

{
  "name": "Testcontainer",
  "dockerComposeFile": ["docker-compose.yml", "docker-compose.proxy.yml"],
  "initializeCommand": "WEBDEV_DISABLE_HEADER=1 webdev workspaces-on-init && WEBDEV_DISABLE_HEADER=1 webdev tasks init",
  "postStartCommand": "cd /var/www/html && WEBDEV_DISABLE_HEADER=1 sudo webdev workspaces-post-start && WEBDEV_DISABLE_HEADER=1 webdev tasks start",
  "postCreateCommand": "sudo ln -sf ~/webdev/webdev.sh /usr/local/bin/webdev && cd /var/www/html && WEBDEV_DISABLE_HEADER=1 webdev tasks create"
}

This is a shortended version of the devcontainer.json file that is being used within our environments.

Docker Compose

We want to be flexible, so we use a docker compose file to define the services we want to have available in our development environment. Some systems need for example redis, others mongodb or elasticsearch. These services would be added, if they don´t exist already, and we would tell webdev that we want to start them but more about it later.

Note

You may noticed also the docker-compose.proxy.yml file, that is autogenerated by the tool and should not be edited manually. It adds labels to our services, so that traefik knows on how to route incoming requests

initializeCommand

When we open our development environment via the IDE or with the command “webdev project start”, these commands will be executed first. “webdev workspaces-on-init” will take care of the init process and generate SSL certificates or the routing information for traefik. It also will start the services that are defined in the webdev.yml. The next command will then execute the user defined tasks within the webdev.yml file.

postStartCommand

Once our development environment has been started, webdev will create the vhost entries for the defined workspaces and executes the user defined start tasks.

postCreateCommand

Note

WebDev will create a .createDone.lock file in the devcontainer folder to prevent that create tasks can be run multiple times by accident.

First we want to make sure that the webdev command is also available within the devcontainer and afterwards the user defined create tasks will be executed.

Main container

services:
  devcontainer:
    image: ghcr.io/derroylo/devcontainer-prebuilds/php:latest
    container_name: ${COMPOSE_PROJECT_NAME:-devcontainer}-app
    volumes:
      - ..:/var/www/html:cached
      - ~/webdev-host:/home/webdev/webdev
      - bashhistory:/commandhistory

In this shortened version of the docker-compose.yml we can see the definition of our main container. It contains all the necessary tools and services to run our web application. So when you open the devcontainer env with your IDE then you usually connect to that container and execute all your commands in it.

As base we are using a pre build container with some features installed in it, like composer, php, apache, node etc. If you want to take a look at it, you can find the base image (here)[https://github.com/Derroylo/docker-images/tree/main/devcontainer/php] and the pre builds (here)[https://github.com/Derroylo/devcontainer-prebuilds]. Of course you are not limited to these images, you can build your own that fit your needs.

You may notice that we use three volumes within that container. The first one is the folder that contains our code and which will be mounted then to /var/www/html within the container. The second one mounts the webdev tool into the container and the third one makes sure that we can keep our bash history, even when deleting the container.