Troubleshooting ๐Ÿž

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/config file, 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.secret will only be generated if a valid template exists (sh/env/.env.secret.template)
  • If needed, delete root .env and 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 clean removes 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 -r deletes everything inside without asking. Before running it, check that web/wp-core/wp-content contains 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,
  • make commands 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_UPGRADE is empty or 0 (any other value turns the guard off). Check your shell (echo "$MARIADB_AUTO_UPGRADE") and .env.secret (grep '^MARIADB_AUTO_UPGRADE' config/environment/.env.secret prints nothing when the line is commented out, which is the template default).
  • db-data/mysql exists (sudo ls db-data/mysql; on Linux the files belong to the container’s mysql user). An empty db-data counts 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.