Troubleshooting Docker

"Couldn't connect to Docker daemon . . ."

$ docker-compose up
ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?

If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.

This usually means you need to run docker with sudo:

• sudo docker [subcommand] . . . or
• sudo docker-compose [subcommand] . . .

If that doesn't solve the error, try restarting your computer. This gives the Docker daemon a chance to be started during your operating system's startup.

If that still doesn't solve the error, try uninstalling Docker completely from your computer and re-installing based on the instructions in CONTRIBUTING.md or this wiki, e.g. Docker CE on Linux.

(This error should only apply to Linux users running Docker CE.)

Can't find a suitable configuration file

$ docker-compose up
ERROR: 
        Can't find a suitable configuration file in this directory or any
        parent. Are you in the right directory?

        Supported filenames: docker-compose.yml, docker-compose.yaml

As the error message helpfully points out, Docker compose needs to be run from a directory (or "folder") where a docker compose configuration file is located. Navigate in the terminal to where you cloned the refugerestrooms project to. Typically in your home folder: cd ~/refugerestrooms. Then try running docker compose again from there.

"An HTTP request took too long to complete."

This is a common error to run into when running docker-compose up.

Sample error text (click to expand, or give keyboard focus and press "Enter" to expand):

$ sudo docker-compose up
Creating network "refugerestrooms_default" with the default driver
Creating refugerestrooms_db_1 ... done
Creating refugerestrooms_web_1 ... 

ERROR: for refugerestrooms_web_1  UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. (read timeout=60)

ERROR: for web  UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. (read timeout=60)
ERROR: An HTTP request took too long to complete. Retry with --verbose to obtain debug information.
If you encounter this issue regularly because of slow network conditions, consider setting COMPOSE_HTTP_TIMEOUT to a higher value (current value: 60).

This error message actually occurs whenever docker-compose up takes more than the default time limit (usually 60 seconds) to make a certain amount of progress. It can be due to a slow/busy hard drive and/or a slow/busy CPU. (Starting the docker compose process causes a lot of reads and writes to the hard drive, and can time out on slow hard drives. Likewise, docker compose can use a large amount of CPU time.)

Technical explanation (click to expand, or give keyboard focus and press "Enter" to expand.)

(This error message can be a bit misleading. It will usually happen due to a slow hard-drive or a slow CPU, not due to a slow network connection. This error message will usually occur after our refugerestrooms_web Docker image is finished building. This error usually occurs when trying to spin up a running container based on the already-built refugerestrooms_web image. The way we use Docker compose, there is no reason for compose to actually use the network to communicate beyond your own local machine during this step. Docker is only technically communicating across a local network bridge that connects your host machine's terminal to the docker container, a sort of virtual network located only on your computer. These local network communications should be almost instantaneous. Therefore, this error usually means your computer's hard drive or CPU are busy, not your network connection.)

The first solution to try here is to wait until your system is less busy, potentially close some other programs, and try again. If docker-compose up times out again, you may want to try with a longer timeout value, like this: COMPOSE_HTTP_TIMEOUT=360 docker-compose up. (This gives 360 seconds, or in other words, six minutes. You can enter any amount of time you are comfortable waiting.)

Relatedly, see this StackOverflow question: https://stackoverflow.com/questions/36488209/how-to-override-the-default-value-of-compose-http-timeout-with-docker-compose-co

"Error: In file ./.env: environment variable name [...] may not contain whitespace."

$ docker-compose up
ERROR: In file ./.env: environment variable name 'export DEVISE_SECRET_KEY' may not contain whitespace.

This error happens with docker-compose 1.24.0 through 1.25.x. Make sure you are using docker-compose <= 1.23.2, or docker-compose >= 1.26.0. For more information, see: https://github.com/docker/compose/issues/6511

"A server is already running . . ."

$ docker-compose up
# ...
# ...
# ...
web_1  | A server is already running. Check /refugerestrooms/tmp/pids/server.pid.

This error happens when the Rails server isn't shut down gracefully.

To solve this error, delete the tmp/pids/server.pid file in the refugerestrooms project folder. Deleting this file may require administrator privileges.

(Example command to delete this file on macOS or Linux: sudo rm tmp/pids/server.pid.)

To avoid this error, shut down your running Docker containers "gracefully," either with docker-compose down (recommended), or by pressing Ctrl + C once. (Pressing Ctrl + C once waits for the server and databse to "gracefully shut down", but pressing Ctrl + C a second time forces an abrupt shutdown that may lead to the "A server is already running" error.)

"LoadError: lib[something].so.[number]: cannot open shared object file: No such file or directory - /usr/local/bundle/gems/[gem name]-[gem version]/lib/[soname].so" . . . "Caused by:" . . . "LoadError: cannot load such file -- [Ruby Major.minor]/[soname]" . . . "Caused by:" . . . "Bootsnap::LoadPathCache::FallbackScan:"

This error happens when you have old cached gems, which have native extensions that were built against an older Ruby version, but the Ruby version in the Dockerfile has been updated since the gems were built. In this situation, the old gems are unloadable, causing an error when starting the container/web app with docker-compose up.

The solution is to delete the old, cached gems. First, shut down the container if it is still running -- for example, by pressing Ctrl + C in the terminal where the Docker container is running. Or opening a new terminal in the refugerestrooms project directory, and running docker-compose down. Or shutting down the running container via the GUI in Docker Desktop for Windows or Mac.

Then do:

$ docker volume rm refugerestrooms_bundle

This deletes the cached gems, and allows them to be reinstalled/rebuilt when you next run docker-compose up.

General-purpose troubleshooting (starting over from scratch)

If the Refuge Restrooms app running in Docker gives you strange error messages, and the errors have to do with technology that should be working -- and the errors seem unrelated to any changes you can recall making, you can try rebuilding the docker image with docker-compose build. (This resets the docker image to more of a "known-working" state, ruling out problems with the image, and narrowing down the troubleshooting process to only the changes you have made.)

(If docker-compose build finishes rebuilding very quickly, then docker is likely using a cached image, built during a previous docker-compose build run. In that case, here are some good-to-know commands for cleaning up docker builds...)

Essential docker cleanup commands:

• docker-compose down in the refugerestrooms project folder will shut down your running Refuge Restrooms Docker containers, the network that connects them, and so on. This frees up the underlying images and volumes to be removed/deleted.
• docker images will list images you have downloaded (ruby, postgres) and built refugerestrooms_web).
  • docker rmi [image-name-here] or docker rmi [image-hexadecimal-id-here] will delete that image.
    • (docker rmi might fail if the image is currently running. If so, open a new terminal (or "docker quickstart terminal" if using Docker Toolbox), navigate to the refugerestrooms project folder, and run docker-compose down to shut down the refugerestrooms images.)
  • You can delete multiple images with one command if you like: docker rmi [image-1] [image-2] [image-3] and so on.

More-advanced stuff:

• docker system df will show you all artifacts/stuff you have on your system from your use of docker, grouped by type, and in terms of how much disk space they are using.
• docker system prune will remove most types of data, other than the latest named/tagged images (For example: refugerestrooms_web, ruby and postgres), and will only remove things if they are not currently up and running or in use.
  • docker system prune --volumes will additionally remove temporary overlay "volumes," including the database (postgres) volume that spins up when you run docker-compose up for this project... As long as they are not currently in use.
  • For more information about pruning old artifacts from Docker usage over time, see: https://docs.docker.com/config/pruning/