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).

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

It will remove all Docker containers, images, and volumes associated with this project – excluding the database volume, which is preserved to avoid data loss.

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 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 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

⚠️ Make sure the directory is empty before deleting.
The command will fail if it’s not empty — this is intentional.

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

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.

If problems persist, open an issue and attach the full output of the command.