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:

./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:

./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

# 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

# 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:

   ./test.sh
   # Optional: ./test_template.sh <template-name>
   

3. Bump version for changed templates:

   # 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:

   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

# 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:

# 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:

# 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