Add documentation about docker

Benjamin Rühl
1 parent 219e73bf
Showing 2 changed files with 71 additions and 0 deletions
README.md
docu/docker.md
@@ -115,6 +115,7 @@ In addition to this general documentation, the directory `docu/` also contains s
 General
  
 - [infrastructure](docu/infrastructure.md) - The individual modules of the application
+- [docker](docu/docker.md) - Docker tips and tricks
 - [persistence](docu/persistence.md) - DAOs, Entities, Hibernate, PostgreSQL
 - [adminer](docu/adminer.md) - Database management web app
  
+# Docker tips and tricks
+
+[Docker](https://www.docker.com/what-docker) is a container virtualizing tool that hosts the different processes of the chat bot project in a platform independent way without the need to install technologies like JBoss and PostgreSQL directly on a development or production machine.
+Docker compose is an extension that brings simplified possibilities for running and connecting multiple containers together. It cannot manage containers running on different machines though.
+
+## Command overview
+
+Docker compose
+
+- `docker-compose up`: start containers defined in `docker-compose.yml` in the current directoy
+- `docker-compose up --build`: start containers defined in `docker-compose.yml` in the current directoy and make sure the containers are rebuilt from their images
+- `docker-compose down`: shut down containers defined in `docker-compose.yml` in the current directoy
+
+Docker
+
+- `docker ps`: list all containers running on machine
+
+## Known issues and troubleshooting
+
+**Before jumping to the individual issues, the following hint should be read.** When working with docker a lot of problems came up almost all the time. There seem to be still some problems in the core docker engine. Updates for Docker are delivered frequently which sometimes fixes issues but most often does not. The most common solutions to many unresolvable issues are the following:
+
+1. restart the docker service
+2. restart the machine
+3. remove all containers and images
+4. reset docker to factory defaults or reinstall
+
+At least the first two should be given a try if errors seem to make no sense at all.
+
+### Issue: Windows named pipe error
+
+```
+ERROR: Windows named pipe error: The system cannot find the file specified. (code: 2)
+```
+
+The docker service seems to be not running. Do not forget to start Docker before executing commands.
+
+### Issue: Port is already allocated
+
+```
+Error: port is already allocated
+```
+
+Very common. Use `docker ps` to see if containers are running with the same port. Shut down all running containers. Restart Docker service.
+
+### Issue: Name is already in use by container
+
+```
+Error response from daemon: Conflict. The name "{container-name}" is already in use by container {container-hash}. You have to delete (or rename) that container to be able to reuse that name.
+```
+
+Shut down containers. Restart docker. Clear containers, images and maybe volumes. See [Github issue](https://github.com/moby/moby/issues/23371)
+
+### Issue: IOError: Failed to execute script docker-compose
+
+```
+IOError: [Errno 0] Error
+Failed to execute script docker-compose
+```
+
+Seems to be Windows only. Try executing your command directly in the powershell instead of an IDE like IntelliJ or Visual Studio Code. See [Github issue](https://github.com/docker/compose/issues/5019).
+
+### Issue: FileNotFoundException: server.log (Permission denied)
+
+```
+Caused by: java.io.FileNotFoundException: /opt/jboss/wildfly/standalone/log/server.log (Permission denied)
+    at java.io.FileOutputStream.open0(Native Method)
+    at ...
+```
+
+Common and nasty. Most often restarting the Docker service hepls. Sometimes multiple restarts are required.
 \ No newline at end of file