Docker Troubleshooting

These are instructions for troubleshooting Docker for Windows or Mac. For old file for troubleshooting Docker Toolbox.

Best practices

• The best command to run containers is docker compose down -v; docker compose up --build. Notice the down command first. This just keeps thinks clean.
• Run docker compose down -v when you're done working on a project. (note: some projects may refresh the database on docker compose down -v)
• Some operating systems cause issues if your containers are running when they go to sleep. Try stop containers if you can before your computer goes to sleep (e.g. hit CTRL C on terminal running container)
• If running Docker Desktop for Mac, make sure that cloud sync is not turned on for the folders where your code lives, cloud sync can cause issues with the link between volumes and the local file system.
• If you you haven't rebuilt the project from scratch in a while, you can do so by deleting all the related images noted in the docker/README.md file.
• We highly recommend cleaning up dangling and old images/containers/volumes from time to time. The commands to do this are below.

Things you'll need

• Container name: called containter_name below
  • See docker-compose.yml file. This can be specified there via containter_name: zzzz in a service
• Volume name: called volume_name below
  • See docker-compose file. The volume name can be specified and then docker adds the folder name to the begining of it for some reason

Trouble Shooting

If a container won't build

• Make sure docker has access to the folder your code is in. (See docker > settings > resources > filesharing)

If container wont start

• Find the entrypoint start.sh file and replace the last command with tail -f /dev/null, this will keep the container running indefinitely and allow you to connect to the container (see helpful commands below) and test the command within the container so you can troubleshoot what may cause it to not start.

Unexplained errors: increase the memory of your docker-machine

• If you've tried everything below and you just can't get it to work, the problem is sometimes that your VM is running out of memory
• Increase your memory in Docker > settings > resources
  1. the increased amount required may vary based on the project, but we recommend giving the VM as many resources as you can spare. That said, I don't know the any negative consequences of giving the VM too much.
• Important: deleting your docker machine may cause you to lose data stored in named volumes. It may also cause your images to re-build
• Note: This should only be needed in very difficult issues. If you find yourself following these steps often, then you ought to look into other ways to solve your problem.

If you see SSL error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

1. try restarting docker

If you see Couldn't connect to Docker daemon

1. make sure docker is started

If you see Temporary failure resolving 'archive.ubuntu.com' OR E: Failed to fetch http://archive.ubuntu.com OR any other network error

These errors pop up for several different reasons so hopefully one of the solutions below will work.

1. Point DNS server to google

• Go to Docker > settings > resources > network and turn on "Manual DNS configuration"
• Then set the DNS to 8.8.8.8

1. Try to re-run the build command, sometimes the servers just let us connect
2. Try restarting docker
3. Try running the command dockerCleanAll found below in helpful commands
4. Try restarting your computer. Sometimes the networks get messed and just need to be restarted.
5. Try again later. Sometimes this is just a mirror online that is temporarily down and you just have to try again later.
6. If nothing works, you may need to increase the memory of your docker-machine (see steps above)

If you see Cannot start service [your_service]: driver failed programming external connectivity on endpoint [container_name] or Bind for 0.0.0.0:8000 failed

1. Make sure you run docker compose down -v; on all other containers that could still be open

If you see IOError: [Errno 13] Permission denied:

The cause of this for me was that a file I had downloaded didn't have the right permissions set for some reason. I had to delete the file in question and re-download it. You could probably change the owner of the file as well.

If you see file not found or directory not found errors

These errors probably mean that a folder is not mounting correctly.

1. make sure that the folder that your files are in is shared with docker

To update your node_modules and/or bower_components folder in docker

1. Run docker compose down -v; docker compose up --build
   • This will only work if the bower.json or package.json has changed. Docker will see the change and update the packages
   • Note: sometimes this doesn't work, so you may have to move on to later steps
2. First try to start the container_name container
   1. Open the Docker Quick Start Terminal
   2. Navigate to where this code is located on your computer
   3. Start container_name by running docker compose up
3. If the container doesn't exit (i.e. if the terminal just stops and doesn't let you type)
   1. Open a new Docker Quickstart Terminal
   2. Connect to the running container docker exec -it container_name bash
   3. Run npm install and/or bower install --allow-root
4. If the docker container doesn't keep running
   1. Delete the volume holding your node_modules
      1. Run docker volume rm [volume_name] e.g. docker volume rm foldername_node_modules
         • Note: to find your volume name, list all volumes on your machine with the docker volume ls
         • Note: if you get this error Unable to remove volume, volume still in use: you may need to run docker compose down
   2. Delete the volume holding your bower_components
      1. See instructions to delete volume for node_modules, just change the [volume name]
   3. Run docker compose up --build

If you run out of space on the device

You'll sometimes see errors like "No space left on device"

1. Clean up all dangling images, containers, and volumes

• docker rmi $(docker images -a --filter=dangling=true -q)
  • Clean up all dangling (unused) docker images
• docker rm $(docker ps --filter=status=exited --filter=status=created -q)
  • Clean up all exited containers
• docker volume rm $(docker volume ls -q -f dangling=true)
  • Clean up all dangling (unused) volumes

To see what is inside a running container

• run docker exec -it [container_name] bash (e.g. docker exec -it container_name bash)

To see what is inside a built docker image

• run docker run -t -i [image_name] bash (e.g. docker run -t -i image_name bash)

Trouble with Docker Desktop for Mac

If when first building from a repo you see errors appearing to stem from missing files e.g.

PHP Fatal error: Uncaught Error: Class 'Illuminate\Foundation\Application' not found

-or-

Module build failed: Error: ENOENT: no such file or directory, open '/var/www/html/node_modules/...

1. Make sure that you do not have cloud sync turned on for the folder containing the code or one of its parent folders. If you did, turn off cloud sync, or relocate the code to a folder not using cloud sync.
2. Restart Docker Desktop and reattempt building by running docker compose down -v followed by docker compose up --build

Helpful Commands

The following can be added to your .bash_profile file or just used as a reference.

alias dockerCleanImages='docker rmi $(docker images -a --filter=dangling=true -q)'
alias dockerCleanPs='docker rm $(docker ps --filter=status=exited --filter=status=created -q)'
alias dockerCleanVolumes='docker volume rm $(docker volume ls -q -f dangling=true)'
alias dockerCleanAll='dockerCleanPs; dockerCleanImages; dockerCleanVolumes'
alias dockerCleanExited='docker rm -v $(docker ps -a -q -f status=exited)'
dockerConnectPs(){
	docker exec -it $1 bash
}
dockerConnectImage(){
	docker run --rm -it $1
}
alias dockerUp="docker compose down -v; docker compose up --build"
alias dockerDown="docker compose down -v;"
alias dockerStop="docker compose down -v; docker-machine stop"