Skip to content

package-management.md

Latest commit

 

History

History
457 lines (328 loc) · 14.2 KB

package-management.md

File metadata and controls

457 lines (328 loc) · 14.2 KB

Package Management Strategy

This document explains the comprehensive package management strategy used across all platforms in the dev-machine-setup project, including the rationale behind package manager selection and best practices.

Philosophy

The package management strategy is built on the principle of "Leverage native and community package managers for reliable installations" - leveraging the most appropriate and well-supported package managers for each platform while maintaining consistency in the user experience.

Package Manager Selection Criteria

When selecting package managers for each platform, we evaluate:

  1. Native Integration: How well the package manager integrates with the OS
  2. Package Availability: Breadth and quality of available packages
  3. Community Support: Size and activity of the maintainer community
  4. Security Model: Package verification and trust mechanisms
  5. Dependency Management: Automatic resolution and conflict handling
  6. Update Mechanisms: How packages are kept current

Platform-Specific Package Management

macOS Package Management

Primary Package Managers

Homebrew serves as the primary package manager for macOS:

  • Homebrew Formulae: Command-line tools and libraries
  • Homebrew Casks: GUI applications and large binaries
  • Homebrew Taps: Third-party package repositories
# CLI tools via Homebrew formulae
homebrew_formulae:
  - git              # Version control system
  - docker           # Container runtime
  - terraform        # Infrastructure as code
  - kubectl          # Kubernetes CLI

# GUI applications via Homebrew casks
homebrew_casks:
  - visual-studio-code    # Code editor
  - docker-desktop        # Container GUI
  - google-chrome         # Web browser
  - slack                 # Communication tool

Specialized Package Managers

Additional package managers handle specific ecosystems:

  • uv: Python applications and CLI tools (via uv tool install)
  • npm: Node.js packages and tools
  • PowerShell Gallery: PowerShell modules
  • .NET CLI: .NET global tools
  • VS Code Marketplace: Editor extensions

Why this approach works:

  • Homebrew provides excellent macOS integration
  • Formulae and casks cover most development needs
  • Specialized managers handle language-specific tools
  • All managers support dependency resolution

Windows Package Management

Primary Package Manager

Chocolatey serves as the unified package manager for Windows:

choco_packages:
  - name: git
  - name: vscode
  - name: docker-desktop
  - name: terraform
  - name: kubernetes-cli

Specialized Package Managers

  • PowerShell Gallery: PowerShell modules (built-in to Windows)
  • npm: Node.js packages (installed via Chocolatey)
  • uv: Python CLI tools (installed via Chocolatey)
  • VS Code Marketplace: Editor extensions

Why Chocolatey:

  • Largest Windows package repository
  • Strong community maintenance
  • Good dependency management
  • PowerShell integration
  • Supports both CLI and GUI applications

Alternative Considerations

We evaluated but chose not to use:

  • winget: Microsoft's official package manager (newer, smaller repository)
  • scoop: Popular but more limited package selection
  • Ninite: Web-based, not scriptable

Ubuntu Package Management

Primary Package Managers

Ubuntu uses a dual approach with complementary package managers:

APT (Advanced Package Tool):

  • System packages and libraries
  • Command-line tools
  • Development dependencies
apt_packages:
  - name: git
  - name: docker-ce
  - name: build-essential
  - name: curl
  - name: google-chrome-stable
    supported_architectures:
      - amd64                    # Skip on ARM64

Snap Packages:

  • GUI applications
  • Self-contained applications
  • Cross-distribution packages
snap_packages:
  - name: drawio
    classic: true
    supported_architectures:
      - amd64
  - name: slack
    classic: true
    supported_architectures:
      - amd64

Specialized Package Managers

  • pipx: Bootstraps uv
  • uv: Python CLI tools (via uv tool install)
  • PowerShell Gallery: PowerShell modules (after PowerShell installation)
  • VS Code Marketplace: Editor extensions

Why the dual approach:

  • APT provides system integration and dependencies
  • Snap provides modern applications with automatic updates
  • Covers the broadest range of software needs

Debian Package Management

Primary Package Managers

Debian uses a dual approach with complementary package managers:

APT (Advanced Package Tool):

  • System packages and libraries
  • Command-line tools
  • Development dependencies
apt_packages:
  - name: git
  - name: docker-ce
  - name: build-essential
  - name: curl
  - name: google-chrome-stable
    supported_architectures:
      - amd64                    # Skip on ARM64

Flatpak Packages:

  • GUI applications
  • Sandboxed applications
  • Cross-distribution packages

Debian uses Flatpak instead of Snap, since snapd is not shipped with Debian by default:

flatpak_packages:
  - name: com.jgraph.drawio.desktop
    supported_architectures:
      - amd64
  - name: com.slack.Slack
    supported_architectures:
      - amd64

Specialized Package Managers

  • pipx: Bootstraps uv
  • uv: Python CLI tools (via uv tool install)
  • PowerShell Gallery: PowerShell modules (after PowerShell installation)
  • VS Code Marketplace: Editor extensions

Why the dual approach:

  • APT provides system integration and dependencies
  • Flatpak provides sandboxed applications from Flathub
  • Covers the broadest range of software needs on Debian

Fedora Package Management

Primary Package Managers

Fedora uses a dual approach with complementary package managers:

DNF (Dandified YUM):

  • System packages and libraries
  • Command-line tools
  • Development dependencies
dnf_packages:
  - name: git
  - name: cmake
  - name: golang
  - name: curl
  - name: wget

Flatpak Packages:

  • GUI applications
  • Sandboxed applications
  • Cross-distribution packages
# Currently empty by default; add Flathub app IDs as needed
flatpak_packages: []

Specialized Package Managers

  • pipx: Bootstraps uv
  • uv: Python CLI tools (via uv tool install)
  • PowerShell Gallery: PowerShell modules (after PowerShell installation)
  • VS Code Marketplace: Editor extensions

Why the dual approach:

  • DNF provides system integration and dependencies
  • Flatpak provides sandboxed applications from Flathub
  • Covers the broadest range of software needs on Fedora

Package Categories and Organization

Category Classification

We organize packages into logical categories across all platforms:

Category Purpose Examples
Version Control Code repository management git, git-lfs, gh
Development Tools Core development utilities docker, terraform, kubectl
Language Runtimes Programming language support python, node, go, dotnet
Editors & IDEs Code editing environments vscode, vim, emacs
Communication Team collaboration slack, teams, discord
Browsers Web development and testing chrome, firefox, edge
Cloud Tools Cloud platform integration awscli, azure-cli, gcloud
Infrastructure DevOps and deployment terraform, ansible, helm

Cross-Platform Package Mapping

Where possible, we use equivalent packages across platforms:

Tool macOS Windows Ubuntu Debian Fedora
Git git (brew) git (choco) git (apt) git (apt) git (dnf)
VS Code visual-studio-code (cask) vscode (choco) code (snap) code (apt) com.visualstudio.code (flatpak)
Docker docker-desktop (cask) docker-desktop (choco) docker.io (apt) docker-ce (apt) docker-ce (dnf)
Node.js node (brew) nodejs (choco) nodejs (apt) nodejs (apt) nodejs (dnf)
Python python (brew) python (choco) python3 (apt) python3 (apt) python3 (dnf)

Package List Management

Configuration Structure

Each platform maintains package lists in YAML format:

# Platform-specific package manager sections
homebrew_formulae: []    # macOS CLI tools
homebrew_casks: []       # macOS GUI applications
choco_packages: []       # Windows packages
apt_packages: []         # Ubuntu/Debian system packages
snap_packages: []        # Ubuntu applications
flatpak_packages: []     # Debian/Fedora applications
dnf_packages: []         # Fedora system packages

# Cross-platform sections (consistent naming)
vscode_extensions: []    # VS Code extensions
powershell_modules: []   # PowerShell modules
pipx_packages: []        # Python applications (bootstraps uv on Linux)
uv_tools: []             # Python CLI tools (via uv tool install)
npm_global_packages: []  # Node.js global packages

Package Selection Principles

Inclusion Criteria:

  • Widely Used: Popular in the development community
  • Well Maintained: Active development and support
  • Cross-Platform When Possible: Available on multiple platforms
  • Stable: Mature software with reliable releases
  • Open Source Preferred: Open source solutions when available

Exclusion Criteria:

  • Platform-Specific Dependencies: Packages requiring special hardware/software
  • Experimental Software: Alpha/beta software without stable releases
  • Duplicate Functionality: Multiple tools serving the same purpose
  • Large Installations: Packages requiring excessive disk space or system resources

Package List Maintenance

Regular Review Process:

  1. Quarterly Reviews: Assess package relevance and updates
  2. Community Feedback: Incorporate user suggestions and requests
  3. Security Audits: Remove packages with known vulnerabilities
  4. Dependency Updates: Update packages based on dependency changes

Version Management:

  • Use Latest Stable: Generally install the latest stable version
  • Pin When Necessary: Pin specific versions only when required for compatibility
  • Document Constraints: Explain any version-specific requirements

Package Installation Strategy

Installation Order

Packages are installed in dependency order:

  1. System Prerequisites: Basic system tools and libraries
  2. Package Managers: Additional package managers (pipx, uv, npm)
  3. Development Runtimes: Language runtimes and frameworks
  4. Development Tools: IDEs, version control, containers
  5. Applications: GUI applications and end-user tools
  6. Extensions and Modules: Editor extensions, shell modules
  7. Custom Packages: User-specified additions

Error Handling and Recovery

Resilient Installation:

  • Continue on Non-Critical Failures: Skip problematic packages but continue installation
  • Detailed Error Logging: Log specific error messages for troubleshooting
  • Retry Logic: Automatic retry for network-related failures
  • Dependency Resolution: Install dependencies before dependent packages

Recovery Mechanisms:

  • Idempotent Operations: Safe to run installation multiple times
  • State Checking: Verify package state before attempting installation
  • Rollback Capability: Ability to uninstall problematic packages

Security Considerations

Package Source Verification

Trusted Repositories Only:

  • Official Repositories: Use official package manager repositories
  • Signed Packages: Prefer cryptographically signed packages
  • Reputation Checking: Verify package maintainer reputation
  • Community Validation: Use packages with community review and testing

Update and Maintenance

Security Updates:

  • Regular Updates: Keep package lists current with security patches
  • Vulnerability Monitoring: Monitor for reported vulnerabilities
  • Rapid Response: Quick updates when security issues are discovered
  • User Notification: Inform users of critical security updates

Package Integrity

Verification Mechanisms:

  • Checksum Validation: Package managers verify package integrity
  • Signature Verification: Cryptographic verification of package signatures
  • Repository Trust: Only use well-established, trusted repositories
  • Audit Trails: Maintain logs of all package installations and updates

Performance Optimization

Installation Performance

Parallel Processing:

  • Concurrent Downloads: Multiple packages downloaded simultaneously
  • Independent Installation: Non-conflicting packages installed in parallel
  • Progress Feedback: Real-time progress indicators for long installations

Caching Strategy:

  • Package Cache: Leverage package manager caching mechanisms
  • Download Optimization: Avoid re-downloading cached packages
  • Mirror Selection: Use geographically optimal package mirrors

Resource Management

Disk Space Management:

  • Cache Cleanup: Regular cleanup of package manager caches
  • Dependency Optimization: Avoid duplicate dependencies
  • Size Monitoring: Track total installation size

Network Optimization:

  • Bandwidth Awareness: Consider network limitations during installation
  • Retry Logic: Intelligent retry for network failures
  • Mirror Failover: Automatic failover to alternative mirrors

Future Considerations

Emerging Package Managers

Monitoring New Solutions:

  • Microsoft winget: Watching for Windows ecosystem adoption
  • Homebrew for Linux: Evaluating cross-platform potential
  • Nix Package Manager: Considering for reproducible environments
  • Container-based Tools: Evaluating container-first package distribution

Technology Evolution

Adaptation Strategy:

  • Gradual Migration: Smooth transitions to newer package managers
  • Backward Compatibility: Maintain support for existing configurations
  • Community Feedback: Incorporate user preferences in technology choices
  • Performance Monitoring: Continuously evaluate package manager performance

This comprehensive package management strategy ensures reliable, secure, and maintainable software installation across all supported platforms while providing flexibility for customization and future evolution.