From 61c08fb97bd48c167e3ee08dd4fa4f0db3873cc9 Mon Sep 17 00:00:00 2001
From: bunkerity <contact@bunkerity.com>
Date: Fri, 14 May 2021 12:12:33 +0200
Subject: [PATCH] docs - troubleshooting

---
 docs/common_problems.md |  2 --
 docs/index.md           |  2 +-
 docs/troubleshooting.md | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 34 insertions(+), 3 deletions(-)
 delete mode 100644 docs/common_problems.md
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/common_problems.md b/docs/common_problems.md
deleted file mode 100644
index fe9224b..0000000
--- a/docs/common_problems.md
+++ /dev/null
@@ -1,2 +0,0 @@
-Common problems and how to resolve them
-=======================================
diff --git a/docs/index.md b/docs/index.md
index 39d739f..0c17289 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,7 @@
 introduction
 quickstart_guide
 security_tuning
-common_problems
+troubleshooting
 volumes
 environment_variables
 ```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..15b6fcf
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,33 @@
+# Troubleshooting
+
+## Logs
+
+When troubleshooting, the logs are your best friends. We try our best to provide user-friendly logs to help you understand what happened. Please note that we don't store the logs inside the container, they are all displayed on stdout/stderr so Docker can capture them. They can be displayed using the [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) command.
+
+## Permissions
+
+Don't forget that bunkerized-nginx runs as an unprivileged user with UID/GID 101. Double check the permissions of files and folders for each volumes (see the [volumes list](#TODO)).
+
+## ModSecurity
+
+The OWASP Core Rule Set can sometimes leads to false positives. Here is what you can do :
+- Check if your application has exclusions rules (e.g : wordpress, nextcloud, drupal, ...)
+- Edit the matched rules to exclude some parameters, URIs, ...
+- Remove the matched rules if editing it is too much a hassle
+
+Some additional resources : 
+- [Wordpress example](https://github.com/bunkerity/bunkerized-nginx/tree/master/examples/wordpress)
+- [Handling false positive](https://www.netnea.com/cms/apache-tutorial-8_handling-false-positives-modsecurity-core-rule-set/)
+- [Adding exceptions and tuning](https://coreruleset.org/docs/exceptions.html)
+
+## Whitelisting
+
+It's a common case that a bot gets flagged as suspicious and can't access your website. Instead of disabling the corresponding security feature(s) we recommend a whitelist approach. Here is a list of environment variables you can use :
+
+- `WHITELIST_IP_LIST`
+- `WHITELIST_REVERSE_LIST`
+- `WHITELIST_URI`
+- `WHITELIST_USER_AGENT`
+
+More information [here](#).
+