# Docker Compose Command Hooks - Quick Reference

## Overview

Kompose now supports hooks for all Docker Compose commands, similar to the existing database import/export hooks. This allows you to run custom logic before and after any `docker compose` command.

## What Changed

### Core Script (`kompose.sh`)
- Enhanced `execute_stack_command()` to support pre/post hooks
- Hooks automatically execute for supported Docker Compose commands
- Post-hooks only run if the command succeeds

### Documentation
- Completely rewritten hooks guide with comprehensive examples
- Added template file `hooks.sh.template` for easy setup
- Updated help text with complete hook reference

## Available Hooks

### Format
```bash
hook_pre_<command>    # Before docker compose <command>
hook_post_<command>   # After docker compose <command> (only on success)
```

### Supported Commands
- **Lifecycle**: `up`, `down`, `start`, `stop`, `restart`
- **Build**: `build`, `pull`, `create`
- **Monitoring**: `logs`, `ps`, `top`, `port`
- **Execution**: `exec`, `run`
- **Control**: `kill`, `pause`, `unpause`

## Quick Examples

### Example 1: Health Check After Startup

```bash
# In your stack's hooks.sh
hook_post_up() {
    echo "  Verifying services are healthy..."
    sleep 5
    docker compose ps --format json | jq '.[] | select(.Health == "healthy")'
    return 0
}
```

### Example 2: Backup Before Shutdown

```bash
hook_pre_down() {
    echo "  Creating backup before shutdown..."
    ./backup.sh
    return 0
}
```

### Example 3: Clear Cache Before Restart

```bash
hook_pre_restart() {
    echo "  Clearing application caches..."
    docker exec ${COMPOSE_PROJECT_NAME}_redis redis-cli FLUSHALL
    return 0
}
```

### Example 4: Tag Images After Build

```bash
hook_post_build() {
    local tag="$(date +%Y%m%d-%H%M%S)"
    echo "  Tagging image with: $tag"
    docker tag ${COMPOSE_PROJECT_NAME}_app:latest ${COMPOSE_PROJECT_NAME}_app:$tag
    return 0
}
```

## Getting Started

### 1. Copy Template
```bash
cp hooks.sh.template your-stack/hooks.sh
chmod +x your-stack/hooks.sh
```

### 2. Uncomment Hooks You Need
Edit `your-stack/hooks.sh` and uncomment the hooks you want to use.

### 3. Test in Dry-Run Mode
```bash
./kompose.sh your-stack up -d --dry-run
```

### 4. Execute
```bash
./kompose.sh your-stack up -d
```

## Accessing Command Arguments

Hooks receive the full command and arguments:

```bash
hook_pre_up() {
    local -a args=("$@")
    echo "  Command: ${args[0]}"        # "up"
    echo "  Arguments: ${args[*]}"      # "up -d --build"
    
    # Check for specific flags
    if [[ " ${args[*]} " =~ " --build " ]]; then
        echo "  Build flag detected!"
    fi
    
    return 0
}
```

## Environment Variables

Hooks have access to:
- `$SCRIPT_DIR` - Root kompose directory
- `$stack` - Current stack name  
- All variables from root and stack `.env` files
- CLI overrides from `-e` flags

## Best Practices

✅ **DO:**
- Return `0` for success, `1` for failure
- Use indented output: `echo "  Message"`
- Check container status before `docker exec`
- Test with `--dry-run` first
- Make non-critical operations return `0`

❌ **DON'T:**
- Assume containers are running
- Use blocking operations without timeouts
- Hardcode paths or credentials
- Make hooks too complex

## Testing

```bash
# Preview what would happen
./kompose.sh news up -d --dry-run

# Check syntax
bash -n your-stack/hooks.sh

# Debug mode (add to top of hook function)
hook_pre_up() {
    set -x  # Enable debug output
    # your code here
    set +x  # Disable debug output
    return 0
}
```

## Real-World Use Cases

1. **Automated Backups** - Before stopping/rebuilding
2. **Health Monitoring** - After starting services
3. **Cache Management** - Before/after restarts
4. **Image Management** - Tag and push after builds
5. **Notifications** - Alert on lifecycle events
6. **Data Migration** - Run migrations after deployment
7. **Log Rotation** - Before starting new logs
8. **Secret Management** - Pull secrets before startup

## Migration from Old Version

If you already have `hooks.sh` with database hooks:
1. ✅ No changes required - database hooks still work
2. ✅ Just add new command hooks as needed
3. ✅ All hooks can coexist in the same file

## Resources

- **Full Documentation**: `docs/content/3.guide/hooks.md`
- **Template**: `hooks.sh.template`
- **Example**: `sexy/hooks.sh` (Directus schema management)
- **Help**: `./kompose.sh --help`

## Troubleshooting

### Hook not executing?
1. Check file permissions: `chmod +x hooks.sh`
2. Verify function names: `hook_pre_<command>` or `hook_post_<command>`
3. Test with dry-run: `./kompose.sh stack command --dry-run`

### Hook failing?
1. Check return codes: `return 0` for success
2. Add debug output: `set -x` at start of function
3. Verify container names and status
4. Check environment variables are loaded

## Support

For issues or questions:
1. Check the documentation: `docs/content/3.guide/hooks.md`
2. Review the template: `hooks.sh.template`
3. Look at examples: `sexy/hooks.sh`