dropshell-templates/DEVELOPMENT.md

# Development Guide

This guide covers the development workflow for dropshell templates, including testing, versioning, and publishing.

## Repository Structure

```
dropshell-templates/
├── .gitea/workflows/       # CI/CD workflows
├── caddy/                  # Web server template
├── gitea-runner-docker/    # CI runner template
├── simple-object-server/   # Object storage template
├── squashkiwi/            # Squashkiwi service template
├── static-website/        # Static site hosting template
├── watchtower/            # Container auto-updater template
├── versions.json          # Template version tracking
├── test.sh                # Template validation script
├── publish.sh             # Template publishing script
├── bump-version.sh        # Version management script
├── detect-changes.sh      # Change detection script
└── test_template.sh       # Integration test script
```

## Template Structure

Each template must have:
- `install.sh` - Installation script
- `uninstall.sh` - Uninstallation script
- `start.sh` - Service start script
- `stop.sh` - Service stop script
- `status.sh` - Service status script
- `config/service.env` - Service configuration

Optional scripts:
- `logs.sh` - View service logs
- `backup.sh` - Backup service data
- `restore.sh` - Restore service data
- `ports.sh` - Display service ports
- `ssh.sh` - SSH into service container
- `destroy.sh` - Completely remove service

## Testing

### Local Testing

Run validation tests for all templates:
```bash
./test.sh
```

This checks:
- Required scripts exist
- Scripts are executable
- Config directory exists
- service.env file exists
- Shell script syntax is valid

### Integration Testing

If you have `ds` (dropshell) installed locally:
```bash
./test_template.sh caddy
```

This performs a full integration test:
- Creates a test service
- Installs the template
- Starts/stops the service
- Backs up and restores
- Destroys the service

## Version Management

Each template has independent semantic versioning tracked in `versions.json`.

### Version Format

Versions follow semantic versioning: `MAJOR.MINOR.PATCH`
- **MAJOR**: Breaking changes
- **MINOR**: New features, backwards compatible
- **PATCH**: Bug fixes, backwards compatible

### Bumping Versions

#### Single Template

```bash
# Bump patch version (1.0.0 -> 1.0.1)
./bump-version.sh caddy patch

# Bump minor version (1.0.0 -> 1.1.0)
./bump-version.sh caddy minor

# Bump major version (1.0.0 -> 2.0.0)
./bump-version.sh caddy major

# Set specific version
./bump-version.sh caddy 2.5.3
```

#### All Templates

```bash
# Bump patch for all templates
./bump-version.sh --all patch

# Set all templates to specific version
./bump-version.sh --all 2.0.0
```

### Version Workflow

1. **Make changes** to template(s)
2. **Test changes** locally:
   ```bash
   ./test.sh
   # Optional: ./test_template.sh <template-name>
   ```
3. **Bump version** for changed templates:
   ```bash
   # For bug fixes
   ./bump-version.sh caddy patch
   
   # For new features
   ./bump-version.sh caddy minor
   
   # For breaking changes
   ./bump-version.sh caddy major
   ```
4. **Commit changes** including `versions.json`:
   ```bash
   git add .
   git commit -m "feat(caddy): add custom domain support"
   ```
5. **Push to main** - CI automatically publishes changed templates

## Publishing

### Automatic Publishing (CI/CD)

When you push to the main branch:
1. CI runs tests on all templates
2. Detects which templates changed since last version update
3. Publishes only changed templates to templates.dropshell.app
4. Each template is tagged with:
   - `:latest` - Always points to newest version
   - `:1.0.0` - Specific version
   - `:v1` - Major version only

### Manual Publishing

```bash
# Set environment variable
export SOS_WRITE_TOKEN=your-token-here

# Publish only changed templates (default)
./publish.sh

# Publish all templates
./publish.sh --all

# Publish specific templates
./publish.sh caddy watchtower

# Explicitly publish only changed
./publish.sh --changed-only
```

## Change Detection

The system automatically detects which templates have changed:

```bash
# List changed templates since last version update
./detect-changes.sh

# Output as JSON
./detect-changes.sh --json
```

Changes are detected by comparing against the last git tag that modified `versions.json`.

## CI/CD Configuration

The GitHub Actions workflow (`.gitea/workflows/test-and-publish.yaml`):
- Triggers on pushes to main and pull requests
- Runs tests for all templates
- Publishes only changed templates (main branch only)
- Requires `SOS_WRITE_TOKEN` secret in repository settings

### Setting up CI/CD

1. Go to your Gitea repository settings
2. Add a new secret named `SOS_WRITE_TOKEN`
3. Set the value to your Simple Object Server write token
4. Push to main branch to trigger the workflow

## Development Workflow Example

Here's a complete example of updating the caddy template:

```bash
# 1. Make changes to caddy template
vim caddy/config/Caddyfile

# 2. Test your changes
./test.sh

# 3. Run integration test (if ds is installed)
./test_template.sh caddy

# 4. Bump version (patch for bug fix)
./bump-version.sh caddy patch

# 5. Review version change
cat versions.json

# 6. Commit your changes
git add .
git commit -m "fix(caddy): correct reverse proxy configuration"

# 7. Push to trigger automatic publishing
git push origin main
```

The CI will:
- Run tests
- Detect that only caddy changed
- Publish caddy with new version (e.g., caddy:1.0.1, caddy:latest, caddy:v1)

## Best Practices

1. **Always test locally** before pushing
2. **Use semantic versioning** appropriately:
   - Breaking changes = major bump
   - New features = minor bump
   - Bug fixes = patch bump
3. **Write clear commit messages** that explain the changes
4. **Update version before pushing** to main
5. **Document breaking changes** in commit messages
6. **Keep templates simple** and focused on single services
7. **Use environment variables** in service.env for configuration
8. **Test both install and uninstall** procedures

## Troubleshooting

### Tests failing locally
- Ensure all scripts are executable: `chmod +x template-name/*.sh`
- Check script syntax: `bash -n template-name/script.sh`
- Verify config directory exists
- Ensure service.env is present

### Publishing fails
- Verify `SOS_WRITE_TOKEN` is set
- Check that `sos` tool is installed
- Ensure versions.json is valid JSON
- Verify network connectivity to templates.dropshell.app

### Change detection not working
- Ensure git history is available: `git fetch --all`
- Check that versions.json was committed
- Verify detect-changes.sh is executable

## Template Guidelines

### Required Files
Every template must include:
- Core scripts: install.sh, uninstall.sh, start.sh, stop.sh, status.sh
- Configuration: config/service.env

### Script Requirements
- Use `#!/bin/bash` shebang
- Set `set -e` for error handling
- Use absolute paths where possible
- Handle missing dependencies gracefully
- Provide meaningful error messages
- Clean up resources on uninstall

### Environment Variables
Define in config/service.env:
- Service-specific configuration
- Port mappings
- Volume mounts
- Resource limits
- Feature flags

### Docker Integration
Most templates use Docker:
- Use official images when possible
- Pin specific versions (avoid :latest in production)
- Map configuration via volumes
- Use docker-compose for complex setups
- Handle container lifecycle properly

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add/update tests if needed
5. Bump versions appropriately
6. Submit a pull request

Pull requests should:
- Pass all tests
- Include version bumps for changed templates
- Have clear descriptions
- Follow existing code style
- Include any necessary documentation updates