dropshell-templates/CLAUDE.md

# Dropshell Template Development Guide

## Overview
Dropshell templates are service deployment configurations that allow users to easily install and manage Docker-based services on remote servers. Each template provides a standardized interface for service lifecycle management.

## Template Architecture

### Directory Structure
```
template-name/
├── config/
│   └── service.env        # Service configuration variables
├── install.sh              # Installation script (REQUIRED)
├── uninstall.sh           # Uninstallation script (REQUIRED)
├── start.sh               # Start service script (REQUIRED)
├── stop.sh                # Stop service script (REQUIRED)
├── status.sh              # Check service status (REQUIRED)
├── logs.sh                # View service logs (optional)
├── backup.sh              # Backup service data (optional)
├── restore.sh             # Restore service data (optional)
├── destroy.sh             # Complete removal including data (optional)
├── ports.sh               # Display exposed ports (optional)
├── ssh.sh                 # SSH into container (optional)
└── _volumes.sh            # Volume helper functions (optional)
```

## Required Scripts

### 1. install.sh
- Pull Docker images
- Create necessary volumes/directories
- Verify configuration files exist
- Stop and remove existing containers (if any)
- Start the service
- Must source `${AGENT_PATH}/common.sh`

### 2. uninstall.sh
- Stop the running container
- Remove the container
- Optionally clean up volumes (usually not)
- Must source `${AGENT_PATH}/common.sh`

### 3. start.sh
- Define Docker run command with all parameters
- Use `_create_and_start_container` helper function
- Verify container is running
- Must source `${AGENT_PATH}/common.sh`

### 4. stop.sh
- Stop the running container gracefully
- Use `_stop_container` helper function
- Must source `${AGENT_PATH}/common.sh`

### 5. status.sh
- Check if container exists and is running
- Display container status information
- Return appropriate exit codes
- Must source `${AGENT_PATH}/common.sh`

## Configuration (service.env)

The `config/service.env` file contains service-specific variables:

```bash
# Service identification
CONTAINER_NAME=service-name
IMAGE_REGISTRY=docker.io
IMAGE_REPO=vendor/image
IMAGE_TAG=latest

# Volumes (if using Docker volumes)
DATA_VOLUME=${CONTAINER_NAME}_data
CONFIG_VOLUME=${CONTAINER_NAME}_config

# Directories (if using host paths)
DATA_PATH=${SERVICE_PATH}/data
CONFIG_PATH=${SERVICE_PATH}/config

# Service-specific settings
PORT=8080
ENABLE_FEATURE=true
```

## Common Functions (from common.sh)

Available helper functions:
- `_die "message"` - Print error and exit
- `_check_docker_installed` - Verify Docker availability
- `_check_required_env_vars "VAR1" "VAR2"` - Validate environment
- `_create_and_start_container "$cmd" "$name"` - Start container
- `_is_container_exists "$name"` - Check if container exists
- `_is_container_running "$name"` - Check if running
- `_stop_container "$name"` - Stop container
- `_remove_container "$name"` - Remove container
- `_create_folder "$path"` - Create directory with permissions

## Best Practices

### 1. User Permissions
- Templates run as the `dropshell` user (non-root)
- User is in the `docker` group
- Avoid using `sudo` in scripts
- Set appropriate file permissions (usually 777 for shared volumes)

### 2. Container Management
- Always use `--restart unless-stopped` for reliability
- Name containers consistently using `$CONTAINER_NAME`
- Use official Docker images when possible
- Pin specific versions rather than using `:latest` in production

### 3. Data Persistence
- Use Docker volumes or host directories for persistent data
- Separate config from data volumes
- Document backup/restore procedures
- Never delete data in uninstall.sh (only in destroy.sh)

### 4. Network Configuration
- Expose ports using `-p HOST:CONTAINER`
- Document all exposed ports
- Consider using Docker networks for multi-container setups

### 5. Error Handling
- Use `set -e` at script start (optional, common.sh handles most)
- Check command success with proper error messages
- Use `_die` for fatal errors
- Provide meaningful feedback to users

### 6. Environment Variables
Available from dropshell:
- `${AGENT_PATH}` - Path to agent scripts (contains common.sh)
- `${SERVICE_PATH}` - Path to service directory on server
- `${CONFIG_PATH}` - Path to service config directory
- All variables from service.env

## Creating a New Template

### Step 1: Create Template Structure
```bash
mkdir template-name
mkdir template-name/config
```

### Step 2: Create service.env
Define all configuration variables with sensible defaults.

### Step 3: Implement Required Scripts
Start with the five required scripts, following the patterns from existing templates.

### Step 4: Test Locally
```bash
./test.sh  # Run validation tests
./test_template.sh template-name  # Integration test if dropshell installed
```

### Step 5: Add to versions.json
```json
{
  "template-name": "1.0.0"
}
```

### Step 6: Document
Create a README.txt explaining:
- What the service does
- Configuration options
- Default ports and paths
- Any special requirements

## Template Examples

### Simple Service (watchtower)
- Single container
- Minimal configuration
- No exposed ports
- Docker socket access

### Web Service (caddy)
- HTTP/HTTPS ports
- Config files and static content
- Multiple volumes
- SSL certificate handling

### Complex Service (gitea-runner)
- Multiple configuration files
- Docker-in-Docker capability
- Registration process
- Cleanup procedures

## Testing Checklist

- [ ] All required scripts present and executable
- [ ] service.env contains necessary variables
- [ ] Scripts source common.sh correctly
- [ ] Container starts and stops properly
- [ ] Status script returns correct information
- [ ] Uninstall removes container but preserves data
- [ ] Install is idempotent (can run multiple times)
- [ ] No hardcoded paths (use environment variables)
- [ ] Error messages are clear and helpful
- [ ] Works without root/sudo access

## Version Management

Follow semantic versioning:
- **MAJOR**: Breaking changes to configuration or behavior
- **MINOR**: New features, backwards compatible
- **PATCH**: Bug fixes, backwards compatible

Update version with:
```bash
./bump-version.sh template-name patch|minor|major
```

## Publishing

Templates are automatically published when pushed to main branch:
1. CI runs tests
2. Detects changed templates
3. Publishes to templates.dropshell.app
4. Tags with version numbers

Manual publishing:
```bash
export SOS_WRITE_TOKEN=your-token
./publish.sh template-name
```