Skip to content
Devilbox

Update the Devilbox

Update the Devilbox

Update Git files, Docker images, and local configuration together. Back up first; updates can change service defaults and volume definitions.

Backup first

From the Devilbox repository root:

Terminal window
mkdir -p ../devilbox-backups
tar -czf ../devilbox-backups/devilbox-data-$(date +%Y%m%d).tgz data/
tar -czf ../devilbox-backups/devilbox-cfg-$(date +%Y%m%d).tgz cfg/
cp .env ../devilbox-backups/env-$(date +%Y%m%d) 2>/dev/null || true

Also back up any local docker-compose.override.yml file:

Terminal window
cp docker-compose.override.yml \
  ../devilbox-backups/docker-compose.override.yml-$(date +%Y%m%d) 2>/dev/null || true

Stop the stack

Terminal window
./dvl.sh down

If containers are stuck, remove stopped containers explicitly:

Terminal window
docker compose rm -f

Update the repository

For the main development branch:

Terminal window
git pull origin master

For a tagged release:

Terminal window
git fetch --tags
git checkout v1.0.1

Compare .env with env-example

New releases can add, remove, or rename variables. Diff your active file against the current template:

Terminal window
diff -u env-example .env

Or use an interactive diff tool:

Terminal window
vimdiff env-example .env

Keep local values such as NEW_UID, NEW_GID, selected service versions, ports, and paths, but add any new required variables from env-example.

Pull Docker images

Pull the images selected by your .env and override files:

Terminal window
docker compose pull

If you changed service versions, force recreation on startup:

Terminal window
docker compose rm -f

Start again

Terminal window
./dvl.sh up

Check status and logs:

Terminal window
docker compose ps
docker compose logs --tail=100 php

Run the health check:

Terminal window
./dvl.sh doctor

Refresh generated project config

If your projects use generated HTTPD or environment config, sync it after updating:

Terminal window
./dvl.sh sync-httpd
./dvl.sh sync-env

Regenerate project YAML only when you intentionally want the current DVL defaults applied:

Terminal window
./dvl.sh generate-yaml

Update checklist

  1. Backed up data/, cfg/, .env, and local overrides.
  2. Stopped Devilbox with ./dvl.sh down.
  3. Ran git pull origin master or checked out the target tag.
  4. Diffed .env against env-example.
  5. Ran docker compose pull.
  6. Restarted with ./dvl.sh up.
  7. Ran ./dvl.sh doctor and checked logs.