diff --git a/lib/common.sh b/lib/common.sh
index 34aa245..b8e54d4 100644
--- a/lib/common.sh
+++ b/lib/common.sh
@@ -434,6 +434,49 @@ ensure_docker_dir_ownership() {
     done
 }
 
+# Waits briefly after a container starts, then reports whether it's
+# actually running or stuck restarting/crash-looping — printing recent
+# logs on failure instead of leaving a silent "started" message that
+# doesn't reflect whether it's actually working. Confirmed live:
+# several services' own "Started"-looking `docker compose up -d`
+# success message meant nothing — the container was already
+# crash-looping by the time that message printed, with no indication
+# anything was wrong until someone separately ran `docker ps -a` much
+# later and had to go dig through logs by hand.
+#
+# Usage: check_container_health CONTAINER_NAME [WAIT_SECONDS]
+# Returns 0 if the container is up and hasn't restarted, 1 otherwise.
+check_container_health() {
+    local container="$1" wait_seconds="${2:-8}"
+    [ "$DRY_RUN" = true ] && return 0
+
+    sleep "$wait_seconds"
+
+    local status
+    status="$(docker inspect -f '{{.State.Status}}' "$container" 2>/dev/null)"
+    if [ -z "$status" ]; then
+        log_warning "Container '$container' doesn't exist — something failed before it could even be created."
+        return 1
+    fi
+
+    local restart_count
+    restart_count="$(docker inspect -f '{{.RestartCount}}' "$container" 2>/dev/null || echo 0)"
+
+    if [ "$status" = "running" ] && [ "$restart_count" -eq 0 ]; then
+        return 0
+    fi
+
+    if [ "$status" = "running" ]; then
+        log_warning "Container '$container' is running now but already restarted $restart_count time(s) — check the logs below."
+    else
+        log_warning "Container '$container' is not running (status: $status) — recent logs:"
+    fi
+    echo ""
+    docker logs "$container" --tail 20 2>&1 | sed 's/^/    /'
+    echo ""
+    return 1
+}
+
 # Generate a secure alphanumeric password (no special characters)
 generate_password() {
     local length="${1:-32}"
diff --git a/services/mattermost.sh b/services/mattermost.sh
index 224e887..67363fd 100644
--- a/services/mattermost.sh
+++ b/services/mattermost.sh
@@ -742,9 +742,19 @@ MIGRATE_BODY
     local START=""
     prompt_yn "Start Mattermost now? (y/n):" "y" START
     if [ "$START" = "y" ] || [ "$START" = "Y" ]; then
-        docker compose up -d \
-            && log_success "Mattermost started" \
-            || log_warning "Start failed — check: docker compose logs"
+        if docker compose up -d; then
+            log_success "Mattermost started"
+            # Reference implementation of the shared health check — a
+            # "Started" message alone doesn't mean the app is actually up;
+            # it can still crash-loop (bad DB password, missing required
+            # env var, etc.) with no visible sign until someone separately
+            # runs `docker ps -a` much later. Mattermost's own first DB
+            # connection attempt can take a few seconds, hence the longer
+            # wait than check_container_health's 8s default.
+            declare -F check_container_health >/dev/null 2>&1 && check_container_health "$MM_CONTAINER" 12
+        else
+            log_warning "Start failed — check: docker compose logs"
+        fi
     fi
 
     echo ""