Troubleshooting

Port 80 or 443 already in use

Another service (nginx, Apache on host, etc.) is using the port. Stop it or change the port mapping in docker-compose.yml:

ports:
  - "8080:80"
  - "8443:443"

*.localhost domains not resolving

Make sure dnsmasq is running:

docker compose ps dnsmasq

Test DNS resolution:

dig @127.0.0.1 -p 53535 test.localhost

If dig works but the browser doesn’t resolve, configure your system resolver. See Getting Started.

Permission denied on /var/www

The /var/www directory is bind-mounted from your host. Fix ownership:

sudo chown -R $USER:www-data /var/www

Changes to .env not taking effect

After changing PHP_VERSION, you must rebuild:

docker compose build apache
docker compose up -d

Just restarting (docker compose restart) reuses the existing image.

MariaDB won’t start after version change

If you change MARIADB_VERSION with existing data in /var/lib/local-mysql, MariaDB may fail due to data format differences.

Option 1 — upgrade in place:

docker compose exec mysql mariadb-upgrade -u root -p

Option 2 — fresh start (destroys data):

docker compose down
sudo rm -rf /var/lib/local-mysql/*
docker compose up -d

PHP extension missing

Check what’s installed:

docker compose exec apache php -m

Add the missing extension to apache/Dockerfile and rebuild:

docker compose build apache
docker compose up -d

Build fails for PHP 7.4

PHP 7.4 is EOL but still available in the ondrej/php PPA. If it gets removed in the future, you can pin an older Ubuntu base image by editing the Dockerfile:

FROM ubuntu:22.04