From 7d1fcb75d76db7a2d30441afa3074681273a45c8 Mon Sep 17 00:00:00 2001
From: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Date: Sat, 25 Nov 2023 22:57:34 +1300
Subject: [PATCH] docs: Debugging - Correctly starting DMS (#3654)

---
 docs/content/config/debugging.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/content/config/debugging.md b/docs/content/config/debugging.md
index a01dbe6a..d1e29376 100644
--- a/docs/content/config/debugging.md
+++ b/docs/content/config/debugging.md
@@ -14,6 +14,27 @@ This page contains valuable information when it comes to resolving issues you en
 
 - Check that all published DMS ports are actually open and not blocked by your ISP / hosting provider.
 - SSL errors are likely the result of a wrong setup on the user side and not caused by DMS itself.
+- Ensure that you have correctly started DMS. Many problems related to configuration are due to this.
+
+!!! danger "Correctly starting DMS"
+
+    Use the [`--force-recreate`][docker-docs::force-recreate] option to avoid configuration mishaps: `docker compose up --force-recreate`
+
+    Alternatively, always use `docker compose down` to stop DMS. **Do not** rely on `CTRL + C`, `docker compose stop`, or `docker compose restart`.
+
+    ---
+
+    DMS setup scripts are run when a container starts, but may fail to work properly if you do the following:
+
+    - Stopping a container with commands like: `docker stop` or `docker compose up` stopped via `CTRL + C` instead of `docker compose down`.
+    - Restarting a container.
+
+    Volumes persist data across container instances, however the same container instance will keep internal changes not stored in a volume until the container is removed.
+
+    Due to this, DMS setup scripts may modify configuration it has already modified in the past.
+
+    - This is brittle as some changes are naive by assuming they are applied to the original configs from the image.
+    - Volumes in `compose.yaml` are expected to persist any important data. Thus it should be safe to throwaway the container created each time, avoiding this config problem.
 
 ### Mail sent from DMS does not arrive at destination
 
@@ -99,3 +120,4 @@ This could be from outdated software, or running a system that isn't able to pro
 
 [docker-rootless-interface]: https://github.com/moby/moby/issues/45742
 [docker-macos-virtiofs]: https://www.docker.com/blog/speed-boost-achievement-unlocked-on-docker-desktop-4-6-for-mac/
+[docker-docs::force-recreate]: https://docs.docker.com/compose/reference/up/