diff --git a/docs/tutorial/configure-additional-actions-for-build.md b/docs/tutorial/configure-additional-actions-for-build.md new file mode 100644 index 00000000..61c3a94b --- /dev/null +++ b/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) \ No newline at end of file