@fredlackey/devutils 0.0.18 → 0.1.0

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

@@ -1,805 +0,0 @@
-# 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)