Restructured Troubleshooting

docs/debug-logs.md

@@ -0,0 +1,10 @@
+To view the logs of all mailcow: dockerized related containers, you can use `docker-compose logs` inside your mailcow-dockerized folder that contains your `mailcow.conf`. This is usually a bit mutch but you could trim the output with `--tail=100` to the last 100 lines, or add a `-f` to follow the live output of all your services.
+
+To view the logs of a specific service you can use `docker-compose logs [options] $Service_Name`
+
+!!! info
+    The available options for the command **docker-compose logs** are:
+    - **--no-color**: Produce monochrome output.
+    - **-f**: Follow the log output.
+    - **-t**: Show timestamps.
+    - **--tail="all"**: Number of lines to show from the end of the logs for each container.

docs/debug.md

@@ -1,34 +1,9 @@
-## Logs
+When a problem occurs, then always for a reason! :slight_smile: What you want to do in such a case is:
 
-You can use `docker-compose logs $service-name` for all containers.
-
-Run `docker-compose logs` for all logs at once.
-
-Follow the log output by running docker-compose with `logs -f`.
-
-Limit the output by calling logs with `--tail=300` like `docker-compose logs --tail=300 mysql-mailcow`.
-
-## Reset admin password
-Reset mailcow admin to `admin:moohoo`:
-
-```
-cd mailcow_path
-bash mailcow-reset-admin.sh
-```
-
-## What container does what
-
-Here is a brief overview of what container does what:
-
-| Service Name  | Service Descriptions                                                      |
-| --------------- | ------------------------------------------------------------------------- |
-| bind9-mailcow   | Local (DNSSEC) DNS Resolver                                               |
-| mysql-mailcow   | Stores SOGo's and most of mailcow's settings                                         |
-| postfix-mailcow | Receives and sends mails                                                  |
-| dovecot-mailcow | User logins and sieve filter                                              |
-| redis-mailcow   | Storage backend for DKIM keys, Rmilter and Rspamd                         |
-| rspamd-mailcow  | Mail filtering system. Used for av handling, dkim signing, spam handling  |
-| rmilter-mailcow | Integrates Rspamd into postfix                                            |
-| clamd-mailcow   | Scans attachments for viruses                                             |
-| sogo-mailcow    | Webmail client that handles Microsoft ActiveSync and Cal- / CardDav       |
-| nginx-mailcow   | Nginx remote proxy that handles all mailcow related HTTP / HTTPS requests |
+1. Read your logs; follow them to see what the reason for your problem is.
+2. Follow the leads given to you in your logfiles and start investigating.
+3. Restarting the troubled service or the whole stack to see if the problem persists.
+4. Read the documentation of the troubled service and search it's bugtracker for your problem.
+5. Search our [issues](https://github.com/mailcow/mailcow-dockerized/issues) and [forum](https://forum.mailcow.email/) for topics related to your problem.
+6. [Create an issue](https://github.com/mailcow/mailcow-dockerized/issues) over at our GitHub repository if you think your problem might be a bug or a missing feature you badly need. But please make sure, that you include **all the logs** and a full description to your problem.
+7. If you need help with a problem on a configuration or a setup, or got a question please head over to our [forum](https://forum.mailcow.email/) and open a thread.

docs/reset_pw.md

@@ -0,0 +1,18 @@
+## Mailcow Admin Account
+
+Reset mailcow admin to `admin:moohoo`:
+
+```
+cd mailcow_path
+bash mailcow-reset-admin.sh
+```
+
+## Remove Two-Factor Authentication
+
+```
+
+```
+
+## MySQL Passwords
+
+Please refere to our (MySQL section)(mysql/#reset-mysql-passwords) for instructions on resetting your MySQL passwords.

docs/rm_volumes.md

@@ -0,0 +1,13 @@
+You may want to remove a set of persistend data to resolve a conflict or to start over:
+
+```
+docker volume rm mailcowdockerized_${VOLUME_NAME}
+```
+
+- Remove volume `mysql-vol-1` to remove all MySQL data.
+- Remove volume `redis-vol-1` to remove all Redis data.
+- Remove volume `vmail-vol-1` to remove all contents of `/var/vmail` mounted to `dovecot-mailcow`.
+- Remove volume `dkim-vol-1` to remove all DKIM keys.
+- Remove volume `rspamd-vol-1` to remove all Rspamd data.
+
+Running `docker-compose down -v` will **destroy all mailcow: dockerized volumes** and delete any related containers and networks.

docs/service_desc.md

@@ -0,0 +1,14 @@
+Here is a brief overview of what container / service does what:
+
+| Service Name  | Service Descriptions                                                      |
+| --------------- | ------------------------------------------------------------------------- |
+| bind9-mailcow   | Local (DNSSEC) DNS Resolver                                               |
+| mysql-mailcow   | Stores SOGo's and most of mailcow's settings                                         |
+| postfix-mailcow | Receives and sends mails                                                  |
+| dovecot-mailcow | User logins and sieve filter                                              |
+| redis-mailcow   | Storage backend for DKIM keys, Rmilter and Rspamd                         |
+| rspamd-mailcow  | Mail filtering system. Used for av handling, dkim signing, spam handling  |
+| rmilter-mailcow | Integrates Rspamd into postfix                                            |
+| clamd-mailcow   | Scans attachments for viruses                                             |
+| sogo-mailcow    | Webmail client that handles Microsoft ActiveSync and Cal- / CardDav       |
+| nginx-mailcow   | Nginx remote proxy that handles all mailcow related HTTP / HTTPS requests |

mkdocs.yml

@@ -28,8 +28,14 @@ pages:
   - 'Log to Syslog': 'syslog.md'
   - 'Local MTA on Docker host': 'local_mta.md'
   - 'Sender and receiver model': 'sender_rcv.md'
+- 'Debugging & Troubleshooting':
+    - 'Introduction': debug.md
+    - 'Logs': 'debug_logs.md'
+    - 'Reset Passwords': 'reset_pw.md'
+    - 'Service Descriptions': 'service_desc.md'
+    - 'Remove Persistent Data': 'rm_volumes.md'
+    - 'Common Problems': 'troubles.md'
 - 'Usage & Examples':
-  - 'Debugging & Troubleshooting': 'debug.md'
   - 'mailcow UI':
       - 'Configuration': 'mailcow_ui.md'
       - 'Blacklist / Whitelist': 'bl_wl.md'