Easy Way to Create Custom Application Installer

Getting Started

Prerequisites

• Q4OS system with development tools
• Basic knowledge of shell scripting
• Understanding of Linux package management
• Your application ready for distribution

Installing Development Tools

sudo apt update
sudo apt install build-essential
sudo apt install q4os-installer-dev  # Q4OS installer development tools
sudo apt install imagemagick          # For icon processing
sudo apt install desktop-file-utils   # For .desktop file validation

Q4OS Installer Framework Structure

The Q4OS installer framework uses a simple directory structure:

my-app-installer/
├── installer.conf        # Main configuration file
├── install.sh           # Installation script
├── uninstall.sh         # Uninstallation script (optional)
├── icon.png             # Application icon
├── files/               # Application files (if needed)
└── resources/           # Additional resources

Configuration File

Basic installer.conf Structure

Create the main configuration file installer.conf:

[Application]
Name=My Application
Version=1.0.0
Description=A great application for Q4OS users
Category=Office
Author=Your Name
Email=your.email@example.com
Website=https://yourapp.com
License=GPL-3.0

[Installation]
Type=package
Dependencies=libqt5core5a,libqt5gui5,libqt5widgets5
Packages=my-app
PostInstall=configure_app
CreateShortcut=true
RequiresReboot=false

[Interface]
Icon=icon.png
ShowProgress=true
AllowCancel=true
ConfirmInstall=true

[Uninstall]
Supported=true
RemoveConfig=ask
RemoveLogs=true

Configuration Options Explained

[Application] Section

• Name: Application display name
• Version: Application version
• Description: Brief description
• Category: Application category (Office, Graphics, Games, etc.)
• Author: Developer name
• Email: Contact email
• Website: Application website
• License: Software license

[Installation] Section

• Type: package, archive, script, appimage, snap, flatpak
• Dependencies: Required system packages
• Packages: APT packages to install
• PostInstall: Function to call after installation
• CreateShortcut: Create desktop shortcut
• RequiresReboot: Whether system reboot is needed

Installation Script

Basic install.sh Template

#!/bin/bash
# Q4OS Application Installer Script
# Application: My Application
# Version: 1.0.0

# Source Q4OS installer functions
source /usr/lib/q4os-installer/functions.sh

# Initialize installer
installer_init "My Application" "1.0.0"

# Pre-installation checks
pre_install_check() {
    log_info "Performing pre-installation checks..."
    
    # Check available disk space
    if ! check_disk_space "/usr" 100; then
        installer_error "Insufficient disk space. Need at least 100MB."
        return 1
    fi
    
    # Check internet connectivity
    if ! check_internet; then
        installer_error "Internet connection required for installation."
        return 1
    fi
    
    return 0
}

# Main installation function
install_application() {
    log_info "Starting installation..."
    
    # Update package cache
    update_package_cache
    
    # Install dependencies
    log_info "Installing dependencies..."
    install_packages "libqt5core5a libqt5gui5 libqt5widgets5"
    
    # Install main application
    log_info "Installing My Application..."
    install_packages "my-app"
    
    # Post-installation configuration
    configure_app
    
    # Create desktop shortcut
    create_desktop_shortcut
    
    log_info "Installation completed successfully!"
    return 0
}

# Post-installation configuration
configure_app() {
    log_info "Configuring application..."
    
    # Create application directory
    mkdir -p "$HOME/.my-app"
    
    # Copy default configuration
    if [ -f "/etc/my-app/default.conf" ]; then
        cp "/etc/my-app/default.conf" "$HOME/.my-app/config.conf"
    fi
    
    # Set permissions
    chmod 644 "$HOME/.my-app/config.conf"
    
    return 0
}

# Create desktop shortcut
create_desktop_shortcut() {
    log_info "Creating desktop shortcut..."
    
    cat > "$HOME/Desktop/My Application.desktop" << EOF
[Desktop Entry]
Version=1.0
Type=Application
Name=My Application
Comment=A great application for Q4OS users
Exec=/usr/bin/my-app
Icon=/usr/share/pixmaps/my-app.png
Terminal=false
Categories=Office;
StartupNotify=true
EOF
    
    chmod +x "$HOME/Desktop/My Application.desktop"
    return 0
}

# Run pre-installation checks
if ! pre_install_check; then
    installer_exit 1
fi

# Run installation
if install_application; then
    installer_success "My Application installed successfully!"
else
    installer_error "Installation failed!"
    installer_exit 1
fi

installer_exit 0

Available Installer Functions

The Q4OS installer framework provides these utility functions:

Logging Functions

• log_info "message" - Info message
• log_warning "message" - Warning message
• log_error "message" - Error message
• log_debug "message" - Debug message

Package Management

• update_package_cache - Update APT cache
• install_packages "pkg1 pkg2" - Install packages
• remove_packages "pkg1 pkg2" - Remove packages
• check_package_installed "package" - Check if installed

System Checks

• check_disk_space "path" "size_mb" - Check disk space
• check_internet - Check internet connectivity
• check_sudo - Check sudo privileges
• check_architecture - Get system architecture

User Interface

• installer_progress "percent" - Update progress bar
• installer_message "text" - Show message dialog
• installer_confirm "question" - Ask yes/no question
• installer_input "prompt" - Get user input

Installation Types

Package-based Installation

For applications available in APT repositories:

[Installation]
Type=package
Packages=firefox thunderbird
Dependencies=ca-certificates
Repository=universe  # Optional: specify repository

Archive-based Installation

For applications distributed as compressed archives:

[Installation]
Type=archive
ArchiveURL=https://example.com/myapp-1.0.tar.gz
ArchiveHash=sha256:abcdef123456...
InstallPath=/opt/myapp
CreateSymlink=/usr/local/bin/myapp

Script-based Installation

For custom installation procedures:

[Installation]
Type=script
ScriptURL=https://example.com/install.sh
ScriptHash=sha256:123456abcdef...
RunAsRoot=true

AppImage Installation

For portable AppImage applications:

[Installation]
Type=appimage
AppImageURL=https://example.com/MyApp-x86_64.AppImage
InstallPath=/opt/appimages
CreateDesktopFile=true

Snap Package Installation

[Installation]
Type=snap
SnapName=my-app
Channel=stable
Classic=false

Flatpak Installation

[Installation]
Type=flatpak
FlatpakID=org.example.MyApp
Repository=flathub
Branch=stable

Creating Uninstaller

Basic uninstall.sh Template

#!/bin/bash
# Q4OS Application Uninstaller Script
# Application: My Application

source /usr/lib/q4os-installer/functions.sh

# Initialize uninstaller
uninstaller_init "My Application"

# Uninstall function
uninstall_application() {
    log_info "Starting uninstallation..."
    
    # Remove desktop shortcut
    if [ -f "$HOME/Desktop/My Application.desktop" ]; then
        rm -f "$HOME/Desktop/My Application.desktop"
        log_info "Desktop shortcut removed"
    fi
    
    # Ask about configuration removal
    if installer_confirm "Remove application configuration files?"; then
        rm -rf "$HOME/.my-app"
        log_info "Configuration files removed"
    fi
    
    # Remove application packages
    log_info "Removing application packages..."
    remove_packages "my-app"
    
    # Clean up orphaned dependencies
    if installer_confirm "Remove unused dependencies?"; then
        cleanup_packages
        log_info "Unused dependencies removed"
    fi
    
    return 0
}

# Run uninstallation
if uninstall_application; then
    installer_success "My Application uninstalled successfully!"
else
    installer_error "Uninstallation failed!"
    uninstaller_exit 1
fi

uninstaller_exit 0

Testing and Debugging

Testing Your Installer

Test your installer thoroughly before distribution:

# Test installer syntax
bash -n install.sh

# Run installer in test mode
./install.sh --test

# Run installer with debug output
./install.sh --debug

# Test on clean system
# Use virtual machine or container for testing

Debug Mode

Enable debug logging in your installer:

# Add to beginning of install.sh
set -x  # Enable debug mode
export Q4OS_INSTALLER_DEBUG=1

# Use debug logging
log_debug "Debug information here"

Common Issues and Solutions

• Permission errors: Check file permissions and sudo requirements
• Missing dependencies: Verify all dependencies are listed
• Network errors: Implement retry logic for downloads
• Path issues: Use absolute paths when possible

Advanced Features

Multi-architecture Support

# Detect architecture and install appropriate version
ARCH=$(check_architecture)
case $ARCH in
    "amd64")
        PACKAGE_URL="https://example.com/myapp-amd64.deb"
        ;;
    "arm64")
        PACKAGE_URL="https://example.com/myapp-arm64.deb"
        ;;
    "armhf")
        PACKAGE_URL="https://example.com/myapp-armhf.deb"
        ;;
    *)
        installer_error "Unsupported architecture: $ARCH"
        installer_exit 1
        ;;
esac

Version Checking

# Check if newer version is available
check_version() {
    local current_version=$(get_installed_version "my-app")
    local latest_version=$(get_latest_version "my-app")
    
    if version_compare "$current_version" "$latest_version"; then
        installer_message "Newer version available: $latest_version"
        if installer_confirm "Update to latest version?"; then
            return 0
        else
            return 1
        fi
    fi
    return 1
}

Configuration Templates

# Use templates for configuration files
create_config() {
    local username=$(whoami)
    local homedir=$HOME
    
    # Process template with variable substitution
    sed -e "s/{{USERNAME}}/$username/g" \
        -e "s/{{HOMEDIR}}/$homedir/g" \
        /usr/share/my-app/config.template > "$HOME/.my-app/config.conf"
}

Service Installation

# Install and enable systemd service
install_service() {
    log_info "Installing system service..."
    
    # Copy service file
    sudo cp files/my-app.service /etc/systemd/system/
    
    # Reload systemd and enable service
    sudo systemctl daemon-reload
    sudo systemctl enable my-app.service
    
    if installer_confirm "Start service now?"; then
        sudo systemctl start my-app.service
    fi
}

Packaging and Distribution

Creating Installer Package

Package your installer for distribution:

# Create installer archive
tar -czf my-app-installer-1.0.tar.gz my-app-installer/

# Create self-extracting installer
cat > my-app-installer.run << 'EOF'
#!/bin/bash
ARCHIVE=$(awk '/^__ARCHIVE_BELOW__/ {print NR + 1; exit 0; }' $0)
tail -n+$ARCHIVE $0 | tar xzv
cd my-app-installer && ./install.sh
exit 0
__ARCHIVE_BELOW__
EOF
cat my-app-installer-1.0.tar.gz >> my-app-installer.run
chmod +x my-app-installer.run

Installer Verification

Add signature verification for security:

# Sign installer package
gpg --armor --detach-sig my-app-installer.run

# Verify signature in installer
verify_signature() {
    if ! gpg --verify my-app-installer.run.asc my-app-installer.run; then
        installer_error "Installer signature verification failed!"
        return 1
    fi
    return 0
}

Online Distribution

Host your installer online:

• Upload to your website or GitHub releases
• Provide download links and checksums
• Create installation instructions
• Submit to Q4OS software directory (if applicable)

Best Practices

Security

• Validate all user inputs
• Use HTTPS for downloads
• Verify checksums and signatures
• Run with minimal required privileges
• Sanitize file paths and names

User Experience

• Provide clear progress indication
• Show meaningful error messages
• Allow installation cancellation
• Include uninstallation support
• Test on various system configurations

Maintenance

• Keep installers updated with application versions
• Monitor for compatibility issues
• Provide support documentation
• Use version control for installer scripts
• Collect user feedback and improve

Complete Examples

Simple Package Installer

Example for installing a simple APT package:

Archive-based Application

Example for installing from a tar.gz archive:

Complex Application with Services

Example for installing application with system services: