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/