Add How-to for troubleshooting slow starting containers

README.md

@@ -22,8 +22,8 @@ If you want more information behind the design of semantic.works, you can read t
 - [Supporting MacOS](docs/discussions/supporting-mac-os.md)
 
 ## How-to
-- [Develop with your local IDE and tools inside a Docker container](docs/how-to/developing-inside-containers.md)
-
+- [Develop with your local IDE and tools inside a Docker container](docs/how-tos/developing-inside-containers.md)
+- [Troubleshooting - Slow starting containers using 100% CPU](docs/how-tos/troubleshooting---slow-starting-containers.md)
 
 ## Writeups
 Our retrospectives on...

docs/how-tos/troubleshooting---slow-starting-containers.md

@@ -0,0 +1,25 @@
+# Troubleshooting - Slow starting containers using 100% CPU
+
+Some docker images used in Semantic Works stacks, notably those based on sbcl (common lisp) and elixir images, are very slow and CPU intensive to start if the limits of open file descriptors are very high for the container. This leads to a process using 100% of a CPU for some time before that container becomes usable. This can be worked around by setting the defaults for new containers in the docker daemon config (/etc/docker/daemon.json (create it if it doesn't exist)):
+
+```json
+{
+  "default-ulimits": {
+    "nofile": {
+      "Hard": 104583,
+      "Name": "nofile",
+      "Soft": 104583
+    }
+  }
+}
+```
+
+Or, if you want these high defaults for some reason, you can set per-container limits in a docker-compose file for each of the mu-project services:
+
+```yml
+    ulimits:
+      nofile:
+        soft: 104583
+        hard: 104583
+```
+