From 09169530186d988bde6a7b9fdc2894ab5244fca7 Mon Sep 17 00:00:00 2001
From: Your Name <j@842.be>
Date: Thu, 18 Sep 2025 00:04:29 +1200
Subject: [PATCH] Update TEMPLATES.md

---
 TEMPLATES.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 77 insertions(+), 8 deletions(-)

diff --git a/TEMPLATES.md b/TEMPLATES.md
index dad73ba..83cb04a 100644
--- a/TEMPLATES.md
+++ b/TEMPLATES.md
@@ -25,6 +25,71 @@ template-name/
 └── README.txt                # OPTIONAL: Template documentation
 ```
 
+## Important Script Requirements
+
+**All template scripts MUST be non-interactive.** Scripts should never prompt for user input or require any manual interaction. This is critical for automated deployments and remote management.
+
+- **install.sh, uninstall.sh**: Must complete without any user prompts
+- **Data preservation**: Use backup.sh/restore.sh for data management instead of prompting during uninstall
+- **Configuration**: All settings must come from environment variables or config files
+- **Confirmations**: Never use `read`, `select`, or any interactive prompts
+- **Errors**: Use `_die` from common.sh to handle errors and exit cleanly
+
+## Critical Data Preservation Rules
+
+**NEVER DESTROY DATA VOLUMES IN UNINSTALL.SH**
+
+This is a fundamental principle of Dropshell templates:
+
+1. **uninstall.sh MUST preserve all data volumes** - Only remove containers, never volumes
+2. **Data volumes contain irreplaceable user data** - Timestamps, logs, databases, configurations
+3. **Only destroy.sh should remove volumes** - And it must be a separate, explicit action
+4. **Volume removal is IRREVERSIBLE** - Once deleted, data cannot be recovered
+
+### Correct Implementation
+
+**uninstall.sh** - Preserves data:
+```bash
+#!/bin/bash
+source "${AGENT_PATH}/common.sh"
+_check_required_env_vars "CONTAINER_NAME"
+
+# Stop and remove container only
+bash ./stop.sh || _die "Failed to stop container"
+_remove_container "$CONTAINER_NAME" || _die "Failed to remove container"
+
+# DO NOT remove volumes here!
+# Data volumes are preserved for potential reinstallation
+
+echo "Uninstallation complete. Data volumes preserved."
+echo "To remove data permanently, run: ./destroy.sh"
+```
+
+**destroy.sh** - Explicitly removes everything:
+```bash
+#!/bin/bash
+source "${AGENT_PATH}/common.sh"
+_check_required_env_vars "CONTAINER_NAME" "DATA_VOLUME"
+
+echo "WARNING: This will PERMANENTLY DELETE all data for ${CONTAINER_NAME}"
+echo "This action cannot be undone!"
+
+# Since scripts must be non-interactive, only proceed if explicitly called
+bash ./stop.sh
+_remove_container "$CONTAINER_NAME"
+_remove_volume "$DATA_VOLUME"  # Only destroy.sh removes volumes
+
+echo "Service and all data destroyed"
+```
+
+### Why This Matters
+
+- **User Trust**: Users expect uninstall to be reversible by reinstalling
+- **Data Safety**: Application data often contains critical business information
+- **Timestamps**: Historical data and audit logs are irreplaceable
+- **Recovery**: Allows users to reinstall without losing their work
+- **Best Practice**: Follows industry standards for application management
+
 ## Essential Files
 
 ### 1. config/.template_info.env
@@ -116,7 +181,7 @@ echo "Installation of ${CONTAINER_NAME} complete"
 
 ### 4. uninstall.sh
 
-Uninstallation script to remove the service:
+Uninstallation script to remove the service (must be non-interactive and MUST preserve data):
 
 ```bash
 #!/bin/bash
@@ -129,10 +194,12 @@ bash ./stop.sh || _die "Failed to stop container"
 # Remove the container
 _remove_container "$CONTAINER_NAME" || _die "Failed to remove container"
 
-# Optionally remove volumes (with confirmation)
-# _remove_volume "$DATA_VOLUME"
+# CRITICAL: Never remove data volumes in uninstall.sh!
+# Data volumes must be preserved for potential reinstallation
+# Only destroy.sh should remove volumes, and it must be explicit
 
 echo "Uninstallation of ${CONTAINER_NAME} complete"
+echo "Note: Data volumes have been preserved. To remove all data, use destroy.sh"
 ```
 
 ## Optional Command Scripts
@@ -271,11 +338,13 @@ Templates must pass these validation checks:
 1. **Always use `_check_required_env_vars`** at the start of scripts to validate inputs
 2. **Handle errors gracefully** with `|| _die "Error message"`
 3. **Use Docker volumes** for persistent data that survives container recreation
-4. **Document configuration** in README.txt for users
-5. **Support idempotency** - scripts should handle being run multiple times
-6. **Clean up properly** in uninstall/destroy scripts
-7. **Use standard naming** - volumes as `${CONTAINER_NAME}_data`, configs as `${CONTAINER_NAME}_config`
-8. **Test thoroughly** - use `dropshell test-template <path>` to validate
+4. **NEVER remove data volumes in uninstall.sh** - Only destroy.sh should remove volumes
+5. **Document configuration** in README.txt for users
+6. **Support idempotency** - scripts should handle being run multiple times
+7. **Separate concerns** - uninstall.sh removes service, destroy.sh removes data
+8. **Use standard naming** - volumes as `${CONTAINER_NAME}_data`, configs as `${CONTAINER_NAME}_config`
+9. **Test thoroughly** - use `dropshell test-template <path>` to validate
+10. **Preserve user data** - Always prioritize data safety over convenience
 
 ## Examples