@fredlackey/devutils 0.0.1 → 0.0.3

package/src/installs/software-properties-common.md

@@ -0,0 +1,805 @@
+# Installing software-properties-common
+
+## Overview
+
+`software-properties-common` is a package for Debian-based Linux distributions (Ubuntu, Debian, Raspberry Pi OS) that provides utilities for managing software repositories. The most important utility provided by this package is `add-apt-repository`, a command-line tool that simplifies adding Personal Package Archives (PPAs) and third-party repositories to your system.
+
+Key functionality provided by `software-properties-common`:
+
+- **`add-apt-repository`**: Command to add PPAs and custom APT repositories
+- **D-Bus backend**: System service for managing software sources programmatically
+- **Repository management scripts**: Python utilities for modifying `/etc/apt/sources.list` and `/etc/apt/sources.list.d/`
+
+Common use cases:
+
+- Adding Ubuntu PPAs: `sudo add-apt-repository ppa:user/ppa-name`
+- Adding custom repositories: `sudo add-apt-repository "deb [arch=amd64] https://example.com/repo distro main"`
+- Removing repositories: `sudo add-apt-repository --remove ppa:user/ppa-name`
+- Enabling Ubuntu Cloud Archive: `sudo add-apt-repository cloud-archive:caracal`
+
+**Platform Availability Note**: `software-properties-common` is a Debian/Ubuntu-specific package. It is not available on macOS, Windows, Amazon Linux, or other non-Debian-based systems. For those platforms, this document explains the equivalent functionality using native package management tools.
+
+## Dependencies
+
+### macOS (Homebrew)
+
+**Not Applicable** - `software-properties-common` is a Debian/Ubuntu-specific package. macOS uses Homebrew for package management, which has its own repository system called "taps."
+
+- **Equivalent functionality**: `brew tap` command (built into Homebrew)
+- **Required:** Homebrew - Install via `dev install homebrew` or visit https://brew.sh
+
+### Ubuntu (APT/Snap)
+
+- **Required:**
+  - `sudo` - Pre-installed on Ubuntu for privilege escalation
+  - `apt-get` - Pre-installed APT package manager (part of `apt` package)
+- **Optional:** None
+- **Auto-installed:**
+  - `python3-software-properties` - Python bindings for software-properties
+  - `ca-certificates` - Common CA certificates
+  - `python3` - Python 3 interpreter
+
+**Note**: All required dependencies are pre-installed on Ubuntu. No additional packages need to be installed before running this installer.
+
+### Raspberry Pi OS (APT/Snap)
+
+- **Required:**
+  - `sudo` - Pre-installed on Raspberry Pi OS for privilege escalation
+  - `apt-get` - Pre-installed APT package manager (part of `apt` package)
+- **Optional:** None
+- **Auto-installed:**
+  - `python3-software-properties` - Python bindings for software-properties
+  - `ca-certificates` - Common CA certificates
+  - `python3` - Python 3 interpreter
+
+**Note**: All required dependencies are pre-installed on Raspberry Pi OS (Debian-based). No additional packages need to be installed before running this installer.
+
+### Amazon Linux (DNF/YUM)
+
+**Not Applicable** - `software-properties-common` is a Debian/Ubuntu-specific package. Amazon Linux uses DNF/YUM for package management.
+
+- **Equivalent functionality**: `dnf config-manager` command (provided by `dnf-plugins-core`)
+- **Required:** `dnf-plugins-core` - Install via `sudo dnf install -y dnf-plugins-core`
+
+### Windows (Chocolatey/winget)
+
+**Not Applicable** - `software-properties-common` is a Debian/Ubuntu-specific package. Windows uses Chocolatey or winget for package management.
+
+- **Equivalent functionality**:
+  - Chocolatey: `choco source add` command
+  - winget: `winget source add` command
+- **Required:** Chocolatey or winget (built into Windows 10/11)
+
+### Git Bash (Manual/Portable)
+
+**Not Applicable** - Git Bash is a terminal emulator on Windows and does not support Debian package management.
+
+- **Alternative**: Use WSL (Windows Subsystem for Linux) with Ubuntu to access `software-properties-common` functionality on Windows.
+
+## Prerequisites
+
+Before installing `software-properties-common` on Debian-based systems, ensure:
+
+1. **Administrative privileges** - Root or sudo access required
+2. **Internet connectivity** - Required to download packages
+3. **Updated package lists** - Run `apt-get update` before installation
+
+## Platform-Specific Installation
+
+### macOS (Homebrew)
+
+#### Prerequisites
+
+- macOS 10.15 (Catalina) or later
+- Homebrew package manager installed
+- Terminal access
+
+The `software-properties-common` package does not exist on macOS. However, Homebrew provides equivalent functionality through its "tap" system.
+
+#### Equivalent Functionality
+
+On macOS, use `brew tap` to add third-party repositories:
+
+```bash
+# Add a third-party tap (equivalent to add-apt-repository)
+brew tap user/repo
+
+# List all currently configured taps
+brew tap
+
+# Remove a tap
+brew untap user/repo
+```
+
+#### Installation Steps
+
+No installation required - `brew tap` is built into Homebrew. If Homebrew is not installed:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+#### Verification
+
+Verify Homebrew and tap functionality:
+
+```bash
+brew tap
+```
+
+Expected output: List of currently configured taps (may be empty or show default taps like `homebrew/core`).
+
+#### Troubleshooting
+
+**Problem**: `brew: command not found`
+
+**Solution**: Install Homebrew or add it to your PATH:
+
+```bash
+# Apple Silicon Macs
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Intel Macs
+eval "$(/usr/local/bin/brew shellenv)"
+```
+
+**Problem**: Cannot find a formula after adding a tap
+
+**Solution**: Update Homebrew and the tap:
+
+```bash
+brew update
+```
+
+---
+
+### Ubuntu/Debian (APT)
+
+#### Prerequisites
+
+- Ubuntu 18.04 LTS or later, or Debian 10 (Buster) or later
+- sudo privileges
+- Internet connectivity
+
+The `software-properties-common` package provides the `add-apt-repository` command, which is essential for adding PPAs and third-party repositories on Ubuntu.
+
+#### Installation Steps
+
+Run the following commands to update the package index and install `software-properties-common`:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common
+```
+
+The `DEBIAN_FRONTEND=noninteractive` environment variable prevents any interactive prompts. The `-y` flag automatically confirms the installation.
+
+#### Verification
+
+Confirm the installation succeeded by checking for the `add-apt-repository` command:
+
+```bash
+which add-apt-repository
+```
+
+Expected output:
+
+```
+/usr/bin/add-apt-repository
+```
+
+Verify the package is installed:
+
+```bash
+dpkg -l software-properties-common | grep -E "^ii"
+```
+
+Expected output (version numbers may vary):
+
+```
+ii  software-properties-common 0.99.35 all  manage the repositories that you install software from (common)
+```
+
+Test the command:
+
+```bash
+add-apt-repository --help
+```
+
+#### Troubleshooting
+
+**Problem**: `E: Unable to locate package software-properties-common`
+
+**Solution**: Update the package list first:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+**Problem**: `add-apt-repository: command not found` after installation
+
+**Solution**: The package may not have installed correctly. Reinstall:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --reinstall software-properties-common
+```
+
+**Problem**: `E: Could not get lock /var/lib/dpkg/lock`
+
+**Solution**: Another process is using APT. Wait for it to finish or resolve the lock:
+
+```bash
+sudo killall apt apt-get 2>/dev/null
+sudo rm -f /var/lib/dpkg/lock-frontend /var/lib/dpkg/lock /var/cache/apt/archives/lock
+sudo dpkg --configure -a
+```
+
+**Problem**: GPG key errors when adding a PPA
+
+**Solution**: Modern Ubuntu versions handle GPG keys automatically. For older systems or manual key management:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y gnupg
+```
+
+---
+
+### Raspberry Pi OS (APT)
+
+#### Prerequisites
+
+- Raspberry Pi OS (32-bit or 64-bit)
+- Raspberry Pi 3, 4, 5, or Zero 2 W recommended
+- sudo privileges
+- Internet connectivity
+
+Raspberry Pi OS is based on Debian, so `software-properties-common` installs identically. However, note that Ubuntu PPAs may not work on Raspberry Pi OS since PPAs are specifically for Ubuntu.
+
+#### Installation Steps
+
+Run the following commands to update the package index and install `software-properties-common`:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common
+```
+
+**Note**: Installation may take longer on Raspberry Pi compared to desktop systems due to slower I/O and processor speeds. Allow 2-5 minutes on older Pi models.
+
+#### Verification
+
+Confirm the installation succeeded:
+
+```bash
+which add-apt-repository
+```
+
+Expected output:
+
+```
+/usr/bin/add-apt-repository
+```
+
+Verify your architecture:
+
+```bash
+uname -m
+```
+
+Expected output: `aarch64` (64-bit) or `armv7l` (32-bit).
+
+#### Troubleshooting
+
+**Problem**: `E: Unable to locate package software-properties-common`
+
+**Solution**: Update the package list first:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+**Problem**: PPA does not support ARM architecture
+
+**Solution**: Ubuntu PPAs are built for x86_64 and may not have ARM packages. Check if the PPA provides ARM builds, or use Raspberry Pi OS-specific repositories instead:
+
+```bash
+# Check PPA for ARM support before adding
+# Many PPAs only provide amd64 packages
+```
+
+**Problem**: Installation is extremely slow
+
+**Solution**: Raspberry Pi SD cards have limited I/O speed. Ensure you are using a Class 10 or UHS-I SD card. Consider using a USB 3.0 SSD on Pi 4/5.
+
+**Problem**: Out of disk space during installation
+
+**Solution**: Check available space and clean up:
+
+```bash
+df -h
+sudo DEBIAN_FRONTEND=noninteractive apt-get autoremove -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get clean
+```
+
+---
+
+### Amazon Linux (DNF/YUM)
+
+#### Prerequisites
+
+- Amazon Linux 2023 (AL2023) or Amazon Linux 2 (AL2)
+- sudo privileges
+- Internet connectivity
+
+The `software-properties-common` package does not exist on Amazon Linux. Instead, use `dnf config-manager` (provided by `dnf-plugins-core`) for equivalent repository management functionality.
+
+#### Equivalent Functionality
+
+On Amazon Linux 2023, use `dnf config-manager` to add repositories:
+
+```bash
+# Add a repository (equivalent to add-apt-repository)
+sudo dnf config-manager --add-repo https://example.com/repo.repo
+
+# Enable a repository
+sudo dnf config-manager --set-enabled repo-name
+
+# Disable a repository
+sudo dnf config-manager --set-disabled repo-name
+
+# List all repositories
+dnf repolist all
+```
+
+On Amazon Linux 2, use `yum-config-manager`:
+
+```bash
+# Add a repository
+sudo yum-config-manager --add-repo https://example.com/repo.repo
+
+# Enable a repository
+sudo yum-config-manager --enable repo-name
+
+# Disable a repository
+sudo yum-config-manager --disable repo-name
+```
+
+#### Installation Steps
+
+**For Amazon Linux 2023:**
+
+```bash
+sudo dnf install -y dnf-plugins-core
+```
+
+**For Amazon Linux 2:**
+
+```bash
+sudo yum install -y yum-utils
+```
+
+The `-y` flag automatically confirms the installation, enabling non-interactive execution.
+
+#### Verification
+
+Confirm the installation succeeded:
+
+**For Amazon Linux 2023:**
+
+```bash
+dnf config-manager --help
+```
+
+**For Amazon Linux 2:**
+
+```bash
+yum-config-manager --help
+```
+
+Expected output: Help text showing available options for the config-manager command.
+
+List available repositories:
+
+```bash
+dnf repolist all
+```
+
+#### Troubleshooting
+
+**Problem**: `dnf config-manager: command not found`
+
+**Solution**: Install the dnf-plugins-core package:
+
+```bash
+sudo dnf install -y dnf-plugins-core
+```
+
+**Problem**: `yum-config-manager: command not found` on Amazon Linux 2
+
+**Solution**: Install yum-utils:
+
+```bash
+sudo yum install -y yum-utils
+```
+
+**Problem**: Repository URL format errors
+
+**Solution**: Ensure the repository URL points to a valid `.repo` file or use the proper format:
+
+```bash
+# Create a repo file manually if needed
+sudo tee /etc/yum.repos.d/custom.repo > /dev/null << 'EOF'
+[custom]
+name=Custom Repository
+baseurl=https://example.com/repo/
+enabled=1
+gpgcheck=0
+EOF
+```
+
+---
+
+### Windows (Chocolatey/winget)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11
+- Administrator PowerShell or Command Prompt
+- Chocolatey or winget installed
+
+The `software-properties-common` package does not exist on Windows. Both Chocolatey and winget have their own source/repository management systems.
+
+#### Equivalent Functionality
+
+**Using Chocolatey:**
+
+```powershell
+# List configured sources
+choco source list
+
+# Add a custom source
+choco source add --name=custom --source="https://example.com/chocolatey/"
+
+# Remove a source
+choco source remove --name=custom
+```
+
+**Using winget:**
+
+```powershell
+# List configured sources
+winget source list
+
+# Add a custom source
+winget source add --name custom https://example.com/winget/
+
+# Remove a source
+winget source remove --name custom
+
+# Update all sources
+winget source update
+```
+
+#### Installation Steps
+
+**For Chocolatey** (if not already installed):
+
+Run in Administrator PowerShell:
+
+```powershell
+Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+```
+
+**For winget:**
+
+winget is pre-installed on Windows 10 (version 1809+) and Windows 11. No installation needed.
+
+#### Verification
+
+**For Chocolatey:**
+
+```powershell
+choco source list
+```
+
+Expected output:
+
+```
+Chocolatey v2.x.x
+chocolatey - https://community.chocolatey.org/api/v2/ | Priority 0|Bypass Proxy - False|Self-Service - False|Admin Only - False.
+```
+
+**For winget:**
+
+```powershell
+winget source list
+```
+
+Expected output:
+
+```
+Name    Argument
+--------------------------------------------------------------
+winget  https://cdn.winget.microsoft.com/cache
+msstore https://storeedgefd.dsx.mp.microsoft.com/v9.0
+```
+
+#### Troubleshooting
+
+**Problem**: `choco: command not found`
+
+**Solution**: Chocolatey is not installed or not in PATH. Install Chocolatey using the command above, then open a new PowerShell window.
+
+**Problem**: `winget: command not found`
+
+**Solution**: winget may need to be installed from the Microsoft Store (App Installer). Open Microsoft Store and search for "App Installer".
+
+**Problem**: Access denied when adding sources
+
+**Solution**: Run PowerShell as Administrator.
+
+---
+
+### WSL (Ubuntu)
+
+#### Prerequisites
+
+- Windows 10 version 2004+ or Windows 11
+- Windows Subsystem for Linux (WSL) with Ubuntu installed
+- WSL 2 recommended for best performance
+- sudo privileges within WSL
+
+WSL running Ubuntu follows the exact same process as native Ubuntu since it is a full Ubuntu environment.
+
+#### Installation Steps
+
+Open your WSL Ubuntu terminal and run:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common
+```
+
+#### Verification
+
+Confirm the installation succeeded:
+
+```bash
+which add-apt-repository
+```
+
+Expected output:
+
+```
+/usr/bin/add-apt-repository
+```
+
+Test adding a PPA (example - do not actually add unless needed):
+
+```bash
+# Dry run - shows what would happen without making changes
+add-apt-repository --help
+```
+
+#### Troubleshooting
+
+**Problem**: `sudo: unable to resolve host` warnings
+
+**Solution**: Add your hostname to `/etc/hosts`:
+
+```bash
+echo "127.0.0.1 $(hostname)" | sudo tee -a /etc/hosts
+```
+
+**Problem**: Extremely slow `apt-get update`
+
+**Solution**: WSL 1 has slower file system performance. Upgrade to WSL 2:
+
+```powershell
+# In Windows PowerShell (Administrator)
+wsl --set-version Ubuntu 2
+```
+
+**Problem**: Cannot install packages, permission denied
+
+**Solution**: Ensure you are using `sudo` and your user is in the sudo group:
+
+```bash
+groups
+# Should include: sudo
+```
+
+---
+
+### Git Bash (Manual/Portable)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11
+- Git for Windows installed (includes Git Bash)
+
+Git Bash is a terminal emulator that provides Unix-like commands on Windows. It does not include a Linux package management system and cannot run `apt-get` or `software-properties-common`.
+
+#### Equivalent Functionality
+
+Git Bash users who need `add-apt-repository` functionality have two options:
+
+**Option 1: Use WSL (Recommended)**
+
+Install Windows Subsystem for Linux to get a full Ubuntu environment:
+
+```powershell
+# In Windows PowerShell (Administrator)
+wsl --install
+```
+
+After installation, follow the WSL (Ubuntu) section above.
+
+**Option 2: Use Windows Package Managers**
+
+Use Chocolatey or winget from PowerShell (see Windows section above) for Windows repository management.
+
+#### Installation Steps
+
+No direct installation is possible. This package is not compatible with Git Bash.
+
+For Windows users who need the equivalent of `add-apt-repository`:
+
+1. **Open PowerShell as Administrator** (not Git Bash)
+2. Use Chocolatey or winget commands as described in the Windows section
+
+#### Verification
+
+Verify that Git Bash is installed:
+
+```bash
+git --version
+```
+
+For APT functionality, verify WSL is available:
+
+```powershell
+# In PowerShell
+wsl --list --verbose
+```
+
+#### Troubleshooting
+
+**Problem**: Attempting to run `apt-get` or `add-apt-repository` in Git Bash
+
+**Solution**: These commands are not available in Git Bash. Use WSL for Linux package management, or use Chocolatey/winget for Windows package management.
+
+**Problem**: Need to add software repositories on Windows
+
+**Solution**: Use the Windows native tools:
+- Chocolatey: `choco source add --name=name --source=url`
+- winget: `winget source add --name name url`
+
+---
+
+## Post-Installation Configuration
+
+After installing `software-properties-common` on Debian-based systems, you can configure additional settings.
+
+### Adding a PPA (Ubuntu Only)
+
+PPAs (Personal Package Archives) are Ubuntu-specific repositories hosted on Launchpad. Add a PPA using:
+
+```bash
+sudo add-apt-repository -y ppa:user/ppa-name
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+The `-y` flag on `add-apt-repository` automatically confirms adding the PPA without prompting.
+
+### Adding a Custom Repository
+
+Add third-party repositories with custom URLs:
+
+```bash
+sudo add-apt-repository -y "deb [arch=amd64] https://example.com/repo stable main"
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+### Removing a Repository
+
+Remove a previously added repository:
+
+```bash
+sudo add-apt-repository -y --remove ppa:user/ppa-name
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+### Managing Repository Keys (GPG)
+
+Modern `add-apt-repository` handles GPG keys automatically. For manual key management:
+
+```bash
+# Download and add a GPG key
+curl -fsSL https://example.com/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/example-archive-keyring.gpg
+
+# Reference the key in your sources.list entry
+echo "deb [signed-by=/usr/share/keyrings/example-archive-keyring.gpg] https://example.com/repo stable main" | sudo tee /etc/apt/sources.list.d/example.list
+```
+
+---
+
+## Common Issues
+
+### Issue: `add-apt-repository: command not found`
+
+**Symptoms**: Running `add-apt-repository` returns "command not found".
+
+**Solution**: Install `software-properties-common`:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y software-properties-common
+```
+
+### Issue: PPA Does Not Support Your Ubuntu Version
+
+**Symptoms**: `add-apt-repository` warns that the PPA does not have packages for your Ubuntu release.
+
+**Solution**: Check the PPA page on Launchpad to see which Ubuntu versions are supported. You may need to find an alternative PPA or build from source.
+
+### Issue: GPG Key Errors When Adding Repository
+
+**Symptoms**: `NO_PUBKEY` errors when running `apt-get update` after adding a repository.
+
+**Solution**: Import the missing GPG key:
+
+```bash
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys MISSING_KEY_ID
+```
+
+Or use the modern signed-by approach:
+
+```bash
+curl -fsSL https://example.com/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/example.gpg
+```
+
+### Issue: Cannot Find Package After Adding PPA
+
+**Symptoms**: Package not found even after adding PPA and running `apt-get update`.
+
+**Solution**:
+1. Verify the PPA was added correctly: `cat /etc/apt/sources.list.d/*.list`
+2. Update package lists: `sudo DEBIAN_FRONTEND=noninteractive apt-get update -y`
+3. Search for the package: `apt-cache search package-name`
+4. Check if the PPA has packages for your architecture: `apt-cache policy package-name`
+
+### Issue: Proxy or Firewall Blocking Repository Access
+
+**Symptoms**: Timeouts or connection refused errors when adding repositories.
+
+**Solution**: Configure APT to use a proxy:
+
+```bash
+echo 'Acquire::http::Proxy "http://proxy.example.com:8080";' | sudo tee /etc/apt/apt.conf.d/proxy.conf
+echo 'Acquire::https::Proxy "http://proxy.example.com:8080";' | sudo tee -a /etc/apt/apt.conf.d/proxy.conf
+```
+
+### Issue: PPA Works on Ubuntu But Not Raspberry Pi OS
+
+**Symptoms**: Adding a PPA fails or packages are not available on Raspberry Pi OS.
+
+**Solution**: PPAs are designed for Ubuntu and may not work on Debian-based distributions like Raspberry Pi OS. Instead:
+1. Look for official Debian packages
+2. Use the project's official repository if available
+3. Build from source
+
+---
+
+## References
+
+- [Ubuntu software-properties-common Package](https://packages.ubuntu.com/software-properties-common)
+- [Debian software-properties-common Package](https://packages.debian.org/software-properties-common)
+- [add-apt-repository Man Page](https://manpages.debian.org/unstable/software-properties-common/add-apt-repository.1.en.html)
+- [Ubuntu Community - Repositories/CommandLine](https://help.ubuntu.com/community/Repositories/CommandLine)
+- [Debian Wiki - SourcesList](https://wiki.debian.org/SourcesList)
+- [Homebrew Taps Documentation](https://docs.brew.sh/Taps)
+- [Amazon Linux 2023 Package Management](https://docs.aws.amazon.com/linux/al2023/ug/package-management.html)
+- [DNF config-manager Documentation](https://dnf-plugins-core.readthedocs.io/en/latest/config_manager.html)
+- [Chocolatey Source Commands](https://docs.chocolatey.org/en-us/choco/commands/source)
+- [winget Source Commands](https://learn.microsoft.com/en-us/windows/package-manager/winget/source)