If something goes wrong, make sure that:
Docker is running
If Docker is not running, you’ll see a connection error.
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Check Docker status:
docker info
And check running containers:
docker ps
Your SSH key has access to GitHub
If you have an error like:
Permission denied (publickey).
Or
fatal: Could not read from remote repository.
Verify SSH access to GitHub:
ssh -T [email protected]
You should see a message like:
Hi <username>! You've successfully authenticated...
If you see an error, ensure your SSH key is added to your GitHub account. Follow GitHub’s guide to set it up.
Use SSH config to simplify access:
cat <<EOF >> ~/.ssh/config
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_rsa
EOF
๐ก Tip: If you already have a
~/.ssh/configfile, check it for existing GitHub entries to avoid duplicates.
All required .env.* files are present and valid
Ensure files like .env.main, .env.secret, .env.type.* exist and are correctly filled.
.env.secretwill only be generated if a valid template exists (sh/env/.env.secret.template)- If needed, delete root
.envand rerun:
make env
Required ports are available
Common error when a port is taken:
Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use
Make sure ports 80, 443 are not in use:
Check ports:
sudo lsof -i :80
sudo netstat -tulpn | grep -E '80|443'
If a port is occupied, you will see the process PID. To stop it:
sudo kill <PID>
โ ๏ธ Note: Ensure no other local web server (e.g. Apache, MAMP, or LAMP) is running โ it can block Docker from binding to required ports.
Check nginx logs for TLS or routing issues
make log nginx
Check all docker logs
make log
Or use specific service logs:
make log [service_name]
Where service_name can be name of docker compose service, e.g. nginx, php, mariadb, etc.
Full Reset
If issues persist, you can wipe everything and start clean:
make docker clean
โ ๏ธ This affects every Docker project on your machine, not just this one.
make docker cleanremoves all stopped containers, unused images, volumes, networks and build cache system-wide. Your database is safe:db-data/is a folder on your disk, not a Docker volume, so the prune never touches it.
Then re-run the installation:
make install
Composer install/update fails with Could not delete wp-core/wp-content
Symptom:
Running:
make run composer
composer install/update
fails with an error similar to:
Could not delete /srv/web/wp-core/wp-content:
Install of solidbunch/wordpress-core-no-content failed
Cause:
The php container is running and holds a lock on the web/wp-core/wp-content directory. Composer cannot replace the solidbunch/wordpress-core-no-content package while this directory exists.
Resolution:
Stop all running containers:
make down
Delete the empty web/wp-core/wp-content directory:
rm -r web/wp-core/wp-content
โ ๏ธ
rm -rdeletes everything inside without asking. Before running it, check thatweb/wp-core/wp-contentcontains only files Composer created, and move anything of your own out first.
Run Composer again:
composer update
Stop and remove all running containers
Symptom:
- containers are running but unresponsive,
- source files were deleted or changed outside Docker,
- volumes are out of sync,
makecommands no longer work as expected.
Cause:
The Docker environment may be in an inconsistent state โ for example, containers are still running but no longer match the current project structure.
Resolution:
docker ps -a
docker stop $(docker ps -q)
docker rm $(docker ps -aq)
(Optional) Also remove dangling volumes if necessary:
docker volume prune
Or
make docker prune
GitHub API limit (60 calls/hr) is exhausted
Problem: Composer fails to fetch dependencies because the unauthenticated GitHub API rate limit (60 requests/hour) has been exceeded.
Solutions:
Generate a token at https://github.com/settings/tokens (no scopes needed).
Add it to a secret environment file:
In .env.secret:
COMPOSER_AUTH={"github-oauth":{"github.com":"XXXXX"}}
Or Use SSH instead of HTTPS:
If you have SSH access set up:
{
"type": "vcs",
"url": "[email protected]:solidbunch/starter-kit-theme.git"
}
This avoids GitHub API calls entirely and always uses git clone.
๐ ๏ธ Docker Disk Troubleshooting
Quick Checks
docker system df # Overall Docker usage summary
docker ps -s # Container sizes incl. writable layer (logs)
docker images # Image sizes
docker volume ls # List volumes
docker volume prune # Remove unused volumes
docker builder prune # Clean build cache
docker system prune -a # Remove all unused images, containers, networks
Check Log Path (Linux)
docker inspect --format='{{.LogPath}}' <container_id>
ls -lh /var/lib/docker/containers/<container_id>/*-json.log
Check Log Path (Mac)
docker inspect --format='{{.LogPath}}' <container_id>
# Direct file access limited (logs stored inside Docker Desktop VM)
Check log rotation options
/etc/docker/daemon.json should contain log rotation settings:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "10"
}
}
docker inspect <container-name> --format '{{.HostConfig.LogConfig}}'
System Disk Usage
df -h # Overall disk usage
๐ ๏ธ MariaDB Troubleshooting
Run the commands in this section from the root of your project (the folder with the Makefile and
docker-compose.yml). <env> is your environment type (local, dev, stage or prod), the same
value you pass to make up. If you leave it out, make uses APP_DEFAULT_ENV_TYPE from
config/environment/.env.main (local by default).
mariadb keeps restarting with [version-guard] ERROR
Symptom: after changing APP_DATABASE_IMAGE, make recreate <env> fails with dependency failed to start: container ... is unhealthy, docker ps shows mariadb as Restarting, the site is down.
Cause: the mariadb image has a version guard. It refuses to start when the data in ./db-data
belongs to a different major.minor MariaDB version than the image, or has no
mariadb_upgrade_info file. A patch change does not trigger it, except in image builds with an
older guard that compares the full version (their log line says “another version”). Confirm in the
log:
docker compose logs --tail 30 mariadb
[version-guard] ERROR: MariaDB server NOT started.
[version-guard] image version: <version of the image>
[version-guard] data directory: <version recorded in db-data, or "unknown (mariadb_upgrade_info missing)">
Solution: upgrade on purpose โ Database management โ Upgrading MariaDB version.
To undo the change instead, set APP_DATABASE_IMAGE back in config/environment/.env.main and
run make recreate <env>.
If you changed APP_DATABASE_IMAGE to a different major.minor and mariadb starts without any
[version-guard] lines, check three things:
- The running container uses the image you expect (a tag that already exists on the host is not pulled again, see Docker Images):
docker inspect --format '{{.Config.Image}}' $(docker compose ps -q mariadb)
MARIADB_AUTO_UPGRADEis empty or0(any other value turns the guard off). Check your shell (echo "$MARIADB_AUTO_UPGRADE") and.env.secret(grep '^MARIADB_AUTO_UPGRADE' config/environment/.env.secretprints nothing when the line is commented out, which is the template default).db-data/mysqlexists (sudo ls db-data/mysql; on Linux the files belong to the container’smysqluser). An emptydb-datacounts as a fresh install and is never guarded.
Crash recovery failed: Bad magic header in tc log
Error:
[ERROR] Bad magic header in tc log
[ERROR] Crash recovery failed.
[ERROR] Can't init tc log
[ERROR] Aborting
Cause: Corrupted tc.log (Transaction Coordinator Log) file. The error is in the container log
(docker compose logs mariadb).
Solution (safe if you don’t use XA transactions):
make down
sudo rm -f db-data/tc.log
make up <env>
make down removes the containers and named volumes; db-data/ is a folder on your disk and stays.
MariaDB will recreate tc.log on the next start.
If problems persist, open an issue and attach the full output of the command.