Adding tutorial on custom actions configuration

docs/tutorial/configure-additional-actions-for-build.md

@@ -0,0 +1,234 @@
+# Configuring Custom Commands During Image Build
+
+## Overview
+
+The OS Image Composer supports executing custom commands during the image build process through the `configurations` section in image template files. These commands are executed in a chroot environment after all packages have been installed, allowing you to customize the system configuration, create files, download resources, or perform any other setup tasks needed for your custom image.
+
+## How It Works
+
+Custom configurations are executed during the rootfs build phase, specifically after customer packages have been installed. The commands run in a chroot environment within the image being built, giving them full access to modify the target system.
+
+## Configuration Structure
+
+The `configurations` section must be placed under `systemConfig` in your image template YAML file, alongside other system configuration options:
+
+```yaml
+systemConfig:
+  name: your-config-name
+  description: "Your system configuration description"
+
+  # Package installation happens first
+  packages:
+    - ubuntu-minimal
+    - systemd
+    - wget              # Required for download commands
+    - curl              # Required for API calls
+    # ... other packages
+
+  # Custom configurations execute after packages are installed
+  configurations:
+    - cmd: "touch /etc/dummy01.txt"
+    - cmd: "echo 'dlstreamer x86_64 ubuntu24 image' > /etc/dummy01.txt"
+    - cmd: "wget --no-check-certificate -O /etc/validate.sh https://example.com/validate.sh"
+```
+
+## Complete Template Structure
+
+Here's how the configurations section fits within a complete image template:
+
+```yaml
+image:
+  name: your-image-name
+  version: "1.0"
+
+target:
+  os: ubuntu
+  dist: ubuntu24
+  arch: x86_64
+  imageType: raw
+
+disk:
+  name: your-disk-config
+  # ... disk configuration
+
+systemConfig:
+  name: your-system-config
+  description: "Custom system configuration"
+
+  packages:
+    - ubuntu-minimal
+    - systemd-boot
+    - openssh-server
+    - wget                    # Essential for download operations
+    - curl                    # For API interactions
+    - systemd                 # For systemctl commands
+    # ... other required packages
+
+  kernel:
+    version: "6.12"
+    # ... kernel configuration
+
+  # Custom configurations - executed after all packages are installed
+  configurations:
+    - cmd: "mkdir -p /opt/myapp"
+    - cmd: "touch /etc/dummy01.txt"
+    - cmd: "echo 'Custom image marker' > /etc/dummy01.txt"
+    - cmd: "wget --no-check-certificate -O /etc/validate.sh https://example.com/validate.sh"
+    - cmd: "chmod +x /etc/validate.sh"
+    - cmd: "systemctl enable ssh"
+```
+
+## Real-World Example
+
+From the [`ubuntu24-mah.yml`](../image-templates/ubuntu24-mah.yml) template:
+
+```yaml
+systemConfig:
+
+  packages:
+    ...
+    - wget                    # Required for wget commands below
+
+  configurations:
+    - cmd: "touch /etc/dummy01.txt"
+    - cmd: "echo 'dlstreamer x86_64 ubuntu24 image' > /etc/dummy01.txt"
+    - cmd: "wget --no-check-certificate -O /etc/validate.sh https://raw.githubusercontent.com/open-edge-platform/os-image-composer/main/validate.sh"
+```
+
+## Configuration Examples
+
+### Basic File Operations
+
+```yaml
+systemConfig:
+  ...    
+  configurations:
+    - cmd: "mkdir -p /opt/myapp/config"
+    - cmd: "touch /etc/myconfig.conf"
+    - cmd: "echo 'CustomApp=enabled' > /etc/myconfig.conf"
+    - cmd: "chmod 644 /etc/myconfig.conf"
+```
+
+### Download and Install Resources
+
+```yaml
+systemConfig:
+  packages:
+    ....
+    - wget                 # Required for wget commands
+    - curl                 # Required for curl commands
+
+  configurations:
+    - cmd: "wget --no-check-certificate -O /tmp/setup.sh https://example.com/setup.sh"
+    - cmd: "chmod +x /tmp/setup.sh"
+    - cmd: "bash /tmp/setup.sh"
+    - cmd: "curl -o /etc/app.json https://api.example.com/config"
+```
+
+## Execution Environment
+
+### Chroot Context
+
+All commands are executed using `chroot` to the image root filesystem. This means:
+
+- Commands run as if the target system is the root filesystem
+- All paths are relative to the image being built
+- Standard system tools and shell are available
+- Network access is available (if needed for downloads)
+
+### Execution Order
+
+The build process follows this sequence:
+
+1. **Package Installation**: All packages listed in `packages` are installed
+2. **Custom Configurations**: Commands in `configurations` are executed sequentially
+
+
+## Best Practices
+
+### 1. Include Required Tools in Packages
+
+Always include the tools your commands need in the `packages` section:
+
+```yaml
+systemConfig:
+  packages:
+    - wget              # For wget commands
+    - curl              # For curl commands  
+    - systemd           # For systemctl commands
+    - coreutils         # For basic file operations
+    - util-linux        # For system utilities
+
+  configurations:
+    - cmd: "wget -O /opt/file.txt https://example.com/file.txt"
+    - cmd: "systemctl enable myservice"
+```
+
+### 2. Use Absolute Paths
+
+Always use absolute paths since commands execute in the chroot environment:
+
+```yaml
+configurations:
+  # Good - absolute paths
+  - cmd: "echo 'config' > /etc/myapp.conf"
+  - cmd: "mkdir -p /opt/myapp"
+
+  # Avoid - relative paths may not work as expected
+  - cmd: "echo 'config' > myapp.conf"
+```
+
+### 3. Make Commands Robust
+
+Add error checking and make commands idempotent:
+
+```yaml
+configurations:
+  - cmd: "mkdir -p /opt/myapp || true"
+  - cmd: "test -f /etc/config || echo 'default' > /etc/config"
+  - cmd: "systemctl is-enabled ssh || systemctl enable ssh"
+```
+
+### 4. Secure Downloads
+
+Be cautious with downloaded content and verify integrity when possible:
+
+```yaml
+systemConfig:
+  packages:
+    - wget
+    - coreutils         # For sha256sum
+
+  configurations:
+    - cmd: "wget --no-check-certificate -O /tmp/script.sh https://example.com/script.sh"
+    - cmd: "echo 'expected-sha256 /tmp/script.sh' | sha256sum -c"
+    - cmd: "chmod +x /tmp/script.sh && mv /tmp/script.sh /opt/script.sh"
+```
+
+## Error Handling
+
+- If any configuration command fails, the entire build process stops
+- Error messages are logged with details about which command failed
+- Commands should be designed to be idempotent when possible
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Command Not Found**: Ensure required packages are installed in the `packages` section
+2. **Permission Denied**: Some operations may require specific user contexts
+3. **Network Failures**: Download commands may fail due to network issues
+4. **Path Issues**: Use absolute paths for all file operations
+
+## Security Considerations
+
+- Downloaded scripts and files should be from trusted sources
+- Avoid hardcoding sensitive information in commands
+- Consider using checksums to verify downloaded content
+- Be cautious with commands that modify system security settings
+
+## Related Documentation
+
+- [Image Template Format](../architecture/image-template-format.md)
+- [Understanding the OS Image Build Process](../architecture/os-image-composer-build-process.md)
+- [Command-Line Reference](../architecture/os-image-composer-cli-specification.md)