diff --git a/TEMPLATES.md b/TEMPLATES.md index c30ade6..330ffce 100644 --- a/TEMPLATES.md +++ b/TEMPLATES.md @@ -8,9 +8,9 @@ Every template must follow this directory structure: ``` template-name/ +├── template_info.env # REQUIRED: Template metadata (at root level) ├── config/ │ └── service.env # REQUIRED: Default service configuration -├── template_info.env # REQUIRED: Template metadata ├── install.sh # REQUIRED: Installation script ├── uninstall.sh # REQUIRED: Uninstallation script ├── status.sh # REQUIRED: Check service status (needed for 'dropshell list' command) @@ -140,15 +140,15 @@ IMAGE_TAG="latest" When Dropshell runs any template script (install.sh, start.sh, etc.), it: -1. **First loads** all variables from `config/.template_info.env` +1. **First loads** all variables from `template_info.env` (at root level) 2. **Then loads** all variables from `config/service.env` (which can override template defaults) 3. **Exports** all these variables to the environment 4. **Executes** the requested script with these variables available This means: - Scripts can use any variable defined in either file directly (e.g., `$CONTAINER_NAME`, `$IMAGE_TAG`) -- Variables in `service.env` override those in `.template_info.env` if they have the same name -- Users customize deployments by editing `service.env`, never `.template_info.env` +- Variables in `service.env` override those in `template_info.env` if they have the same name +- Users customize deployments by editing `service.env`, never `template_info.env` ### 3. install.sh @@ -432,17 +432,16 @@ Templates receive these variables at runtime: - `AGENT_PATH` - Path to the Dropshell agent directory - `CONFIG_PATH` - Path to the service configuration directory - `SCRIPT_DIR` - Directory containing the template scripts -- All variables from `.template_info.env` and `service.env` +- All variables from `template_info.env` and `service.env` ## Validation Requirements Templates must pass these validation checks: -1. **Required files exist**: `config/.template_info.env`, `config/service.env`, `install.sh`, `uninstall.sh` +1. **Required files exist**: `template_info.env`, `config/service.env`, `install.sh`, `uninstall.sh` 2. **Scripts are executable**: All `.sh` files must have execute permissions -3. **TEMPLATE variable matches**: The `TEMPLATE` variable in `.template_info.env` must match the directory name -4. **Valid environment files**: Both `.env` files must be parseable -5. **SSH_USER defined**: The `SSH_USER` variable MUST be present in `service.env` +3. **Valid environment files**: Both `.env` files must be parseable +4. **SSH_USER defined**: The `SSH_USER` variable MUST be present in `service.env` ## Best Practices @@ -465,8 +464,8 @@ A minimal template for deploying an Nginx web server: ``` nginx-server/ +├── template_info.env ├── config/ -│ ├── .template_info.env │ └── service.env ├── install.sh ├── uninstall.sh @@ -475,9 +474,8 @@ nginx-server/ └── logs.sh ``` -`.template_info.env`: +`template_info.env`: ```bash -TEMPLATE=nginx-server REQUIRES_DOCKER=true REQUIRES_DOCKER_ROOT=false IMAGE_REGISTRY="docker.io" @@ -513,8 +511,8 @@ A more complex template for a database or application requiring data persistence ``` postgres-db/ +├── template_info.env ├── config/ -│ ├── .template_info.env │ ├── service.env │ └── postgres.conf # Additional config files ├── install.sh @@ -529,9 +527,8 @@ postgres-db/ └── README.txt ``` -`.template_info.env`: +`template_info.env`: ```bash -TEMPLATE=postgres-db REQUIRES_DOCKER=true REQUIRES_DOCKER_ROOT=true # Needed for volume management IMAGE_REGISTRY="docker.io" @@ -676,9 +673,8 @@ Aliases: `ds validate`, `ds lint` ### What Validate Checks 1. **Structure Validation** - - Required files exist (`install.sh`, `uninstall.sh`, `config/service.env`, `config/.template_info.env`) + - Required files exist (`install.sh`, `uninstall.sh`, `config/service.env`, `template_info.env`) - Scripts are executable - - `TEMPLATE` variable matches directory name 2. **Shell Script Linting (via Shellcheck)** - Runs [shellcheck](https://www.shellcheck.net/) on all `.sh` files diff --git a/source/src/templates.cpp b/source/src/templates.cpp index dee0091..9df0150 100644 --- a/source/src/templates.cpp +++ b/source/src/templates.cpp @@ -518,9 +518,9 @@ // 4. Generate template files inline (self-contained, no external dependencies) - // config/.template_info.env - std::string template_info_env = R"TMPL(# Template identifier - MUST match the directory name -TEMPLATE=)TMPL" + template_name + R"TMPL( + // template_info.env + std::string template_info_env = R"TMPL(# Template metadata - DO NOT EDIT +# This file is replaced when the template is updated. # Requirements REQUIRES_HOST_ROOT=false @@ -535,7 +535,7 @@ IMAGE_TAG="alpine" # Volume definitions DATA_VOLUME="${CONTAINER_NAME}_data" )TMPL"; - if (!write_template_file(new_template_path + "/config/" + filenames::template_info_env, template_info_env)) return false; + if (!write_template_file(new_template_path + "/" + filenames::template_info_env, template_info_env)) return false; // config/service.env std::string service_env = R"TMPL(# Service identification (REQUIRED) @@ -664,13 +664,13 @@ This template was created by 'dropshell create-template'. QUICK START ----------- 1. Edit config/service.env to customize your deployment -2. Edit config/.template_info.env if you need different Docker settings +2. Edit template_info.env if you need different Docker settings 3. Modify the scripts as needed for your use case 4. Run 'dropshell validate ' to check for issues REQUIRED FILES -------------- -- config/.template_info.env : Template metadata (don't change TEMPLATE=) +- template_info.env : Template metadata (do not edit) - config/service.env : Service configuration (edit this!) - install.sh : Installation script - uninstall.sh : Uninstallation script (preserves data) @@ -796,7 +796,7 @@ For full documentation, see: dropshell help templates } // ------------------------------------------------------------ - // check TEMPLATE= line. + // check required variables in template_info.env ordered_env_vars all_env_vars; std::vector env_files = { "config/" + filenames::service_env,