fix template=
This commit is contained in:
30
TEMPLATES.md
30
TEMPLATES.md
@@ -8,9 +8,9 @@ Every template must follow this directory structure:
|
|||||||
|
|
||||||
```
|
```
|
||||||
template-name/
|
template-name/
|
||||||
|
├── template_info.env # REQUIRED: Template metadata (at root level)
|
||||||
├── config/
|
├── config/
|
||||||
│ └── service.env # REQUIRED: Default service configuration
|
│ └── service.env # REQUIRED: Default service configuration
|
||||||
├── template_info.env # REQUIRED: Template metadata
|
|
||||||
├── install.sh # REQUIRED: Installation script
|
├── install.sh # REQUIRED: Installation script
|
||||||
├── uninstall.sh # REQUIRED: Uninstallation script
|
├── uninstall.sh # REQUIRED: Uninstallation script
|
||||||
├── status.sh # REQUIRED: Check service status (needed for 'dropshell list' command)
|
├── 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:
|
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)
|
2. **Then loads** all variables from `config/service.env` (which can override template defaults)
|
||||||
3. **Exports** all these variables to the environment
|
3. **Exports** all these variables to the environment
|
||||||
4. **Executes** the requested script with these variables available
|
4. **Executes** the requested script with these variables available
|
||||||
|
|
||||||
This means:
|
This means:
|
||||||
- Scripts can use any variable defined in either file directly (e.g., `$CONTAINER_NAME`, `$IMAGE_TAG`)
|
- 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
|
- 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`
|
- Users customize deployments by editing `service.env`, never `template_info.env`
|
||||||
|
|
||||||
### 3. install.sh
|
### 3. install.sh
|
||||||
|
|
||||||
@@ -432,17 +432,16 @@ Templates receive these variables at runtime:
|
|||||||
- `AGENT_PATH` - Path to the Dropshell agent directory
|
- `AGENT_PATH` - Path to the Dropshell agent directory
|
||||||
- `CONFIG_PATH` - Path to the service configuration directory
|
- `CONFIG_PATH` - Path to the service configuration directory
|
||||||
- `SCRIPT_DIR` - Directory containing the template scripts
|
- `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
|
## Validation Requirements
|
||||||
|
|
||||||
Templates must pass these validation checks:
|
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
|
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
|
3. **Valid environment files**: Both `.env` files must be parseable
|
||||||
4. **Valid environment files**: Both `.env` files must be parseable
|
4. **SSH_USER defined**: The `SSH_USER` variable MUST be present in `service.env`
|
||||||
5. **SSH_USER defined**: The `SSH_USER` variable MUST be present in `service.env`
|
|
||||||
|
|
||||||
## Best Practices
|
## Best Practices
|
||||||
|
|
||||||
@@ -465,8 +464,8 @@ A minimal template for deploying an Nginx web server:
|
|||||||
|
|
||||||
```
|
```
|
||||||
nginx-server/
|
nginx-server/
|
||||||
|
├── template_info.env
|
||||||
├── config/
|
├── config/
|
||||||
│ ├── .template_info.env
|
|
||||||
│ └── service.env
|
│ └── service.env
|
||||||
├── install.sh
|
├── install.sh
|
||||||
├── uninstall.sh
|
├── uninstall.sh
|
||||||
@@ -475,9 +474,8 @@ nginx-server/
|
|||||||
└── logs.sh
|
└── logs.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
`.template_info.env`:
|
`template_info.env`:
|
||||||
```bash
|
```bash
|
||||||
TEMPLATE=nginx-server
|
|
||||||
REQUIRES_DOCKER=true
|
REQUIRES_DOCKER=true
|
||||||
REQUIRES_DOCKER_ROOT=false
|
REQUIRES_DOCKER_ROOT=false
|
||||||
IMAGE_REGISTRY="docker.io"
|
IMAGE_REGISTRY="docker.io"
|
||||||
@@ -513,8 +511,8 @@ A more complex template for a database or application requiring data persistence
|
|||||||
|
|
||||||
```
|
```
|
||||||
postgres-db/
|
postgres-db/
|
||||||
|
├── template_info.env
|
||||||
├── config/
|
├── config/
|
||||||
│ ├── .template_info.env
|
|
||||||
│ ├── service.env
|
│ ├── service.env
|
||||||
│ └── postgres.conf # Additional config files
|
│ └── postgres.conf # Additional config files
|
||||||
├── install.sh
|
├── install.sh
|
||||||
@@ -529,9 +527,8 @@ postgres-db/
|
|||||||
└── README.txt
|
└── README.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
`.template_info.env`:
|
`template_info.env`:
|
||||||
```bash
|
```bash
|
||||||
TEMPLATE=postgres-db
|
|
||||||
REQUIRES_DOCKER=true
|
REQUIRES_DOCKER=true
|
||||||
REQUIRES_DOCKER_ROOT=true # Needed for volume management
|
REQUIRES_DOCKER_ROOT=true # Needed for volume management
|
||||||
IMAGE_REGISTRY="docker.io"
|
IMAGE_REGISTRY="docker.io"
|
||||||
@@ -676,9 +673,8 @@ Aliases: `ds validate`, `ds lint`
|
|||||||
### What Validate Checks
|
### What Validate Checks
|
||||||
|
|
||||||
1. **Structure Validation**
|
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
|
- Scripts are executable
|
||||||
- `TEMPLATE` variable matches directory name
|
|
||||||
|
|
||||||
2. **Shell Script Linting (via Shellcheck)**
|
2. **Shell Script Linting (via Shellcheck)**
|
||||||
- Runs [shellcheck](https://www.shellcheck.net/) on all `.sh` files
|
- Runs [shellcheck](https://www.shellcheck.net/) on all `.sh` files
|
||||||
|
|||||||
@@ -518,9 +518,9 @@
|
|||||||
|
|
||||||
// 4. Generate template files inline (self-contained, no external dependencies)
|
// 4. Generate template files inline (self-contained, no external dependencies)
|
||||||
|
|
||||||
// config/.template_info.env
|
// template_info.env
|
||||||
std::string template_info_env = R"TMPL(# Template identifier - MUST match the directory name
|
std::string template_info_env = R"TMPL(# Template metadata - DO NOT EDIT
|
||||||
TEMPLATE=)TMPL" + template_name + R"TMPL(
|
# This file is replaced when the template is updated.
|
||||||
|
|
||||||
# Requirements
|
# Requirements
|
||||||
REQUIRES_HOST_ROOT=false
|
REQUIRES_HOST_ROOT=false
|
||||||
@@ -535,7 +535,7 @@ IMAGE_TAG="alpine"
|
|||||||
# Volume definitions
|
# Volume definitions
|
||||||
DATA_VOLUME="${CONTAINER_NAME}_data"
|
DATA_VOLUME="${CONTAINER_NAME}_data"
|
||||||
)TMPL";
|
)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
|
// config/service.env
|
||||||
std::string service_env = R"TMPL(# Service identification (REQUIRED)
|
std::string service_env = R"TMPL(# Service identification (REQUIRED)
|
||||||
@@ -664,13 +664,13 @@ This template was created by 'dropshell create-template'.
|
|||||||
QUICK START
|
QUICK START
|
||||||
-----------
|
-----------
|
||||||
1. Edit config/service.env to customize your deployment
|
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
|
3. Modify the scripts as needed for your use case
|
||||||
4. Run 'dropshell validate <path>' to check for issues
|
4. Run 'dropshell validate <path>' to check for issues
|
||||||
|
|
||||||
REQUIRED FILES
|
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!)
|
- config/service.env : Service configuration (edit this!)
|
||||||
- install.sh : Installation script
|
- install.sh : Installation script
|
||||||
- uninstall.sh : Uninstallation script (preserves data)
|
- 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;
|
ordered_env_vars all_env_vars;
|
||||||
std::vector<std::string> env_files = {
|
std::vector<std::string> env_files = {
|
||||||
"config/" + filenames::service_env,
|
"config/" + filenames::service_env,
|
||||||
|
|||||||
Reference in New Issue
Block a user