@fredlackey/devutils 0.0.1 → 0.0.3

package/src/installs/chrome-canary.md

@@ -0,0 +1,641 @@
+# Installing Google Chrome Canary
+
+## Overview
+
+Google Chrome Canary is the experimental, bleeding-edge version of the Chrome web browser. It receives nightly updates and contains the latest features, APIs, and experimental web technologies before they reach the stable Chrome release. Chrome Canary is designed for developers and early adopters who want to test upcoming browser features, experiment with new web APIs, and identify potential compatibility issues early in the development cycle.
+
+**Important**: Chrome Canary is not intended for daily browsing. It may contain bugs, crash unexpectedly, and exhibit unstable behavior. Install it alongside your stable Chrome installation for testing purposes only.
+
+## Prerequisites
+
+Before installing Chrome Canary on any platform, ensure:
+
+1. **Internet connectivity** - Required to download the installer
+2. **64-bit operating system** - Chrome Canary requires a 64-bit system on all supported platforms
+3. **Sufficient disk space** - Approximately 500 MB for installation
+4. **Administrative privileges** - Required on most platforms for system-wide installation
+
+**Note**: Chrome Canary can run alongside Google Chrome stable. Both browsers maintain separate user profiles and do not interfere with each other.
+
+## Dependencies
+
+### macOS (Homebrew)
+- **Required:**
+  - `Homebrew` - Install via `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+- **Optional:** None
+- **Auto-installed:** None (Homebrew handles any system-level dependencies transparently)
+
+### Ubuntu (APT/Snap)
+- **Required:**
+  - `wget` - Install via `sudo apt install wget` (usually pre-installed)
+  - `gnupg` - Install via `sudo apt install gnupg` (usually pre-installed)
+- **Optional:** None
+- **Auto-installed:** Chrome runtime dependencies (fonts, libraries, etc.) are automatically resolved by APT during installation
+
+### Raspberry Pi OS (APT/Snap)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** Installation not supported on this platform. Google does not provide ARM builds of Chrome Canary.
+
+### Amazon Linux (DNF/YUM)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** Installation not supported on this platform. Google does not provide RPM packages for Chrome Canary.
+
+### Windows (Chocolatey/winget)
+- **Required:**
+  - `Chocolatey` - Install via PowerShell (Administrator): `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'))`
+- **Optional:** None
+- **Auto-installed:** .NET Framework and other Windows runtime dependencies are handled automatically by Chocolatey
+
+### Git Bash (Manual/Portable)
+- **Required:**
+  - `Chocolatey` - Uses Windows installation method (see Windows section above)
+- **Optional:** None
+- **Auto-installed:** Same as Windows platform
+
+## Platform-Specific Installation
+
+### macOS (Homebrew)
+
+#### Prerequisites
+
+- macOS 12 (Monterey) or later
+- Homebrew package manager installed
+- Terminal access
+
+If Homebrew is not installed, install it first:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+#### Installation Steps
+
+Run the following command to install Chrome Canary:
+
+```bash
+brew install --cask --quiet google-chrome@canary
+```
+
+The `--quiet` flag suppresses non-essential output, making the command suitable for automation scripts. The `--cask` flag specifies that this is a macOS application (as opposed to a command-line tool).
+
+#### Verification
+
+Confirm the installation succeeded by launching Chrome Canary:
+
+```bash
+open -a "Google Chrome Canary"
+```
+
+Alternatively, verify the application exists:
+
+```bash
+ls -la /Applications/Google\ Chrome\ Canary.app
+```
+
+Expected output shows the application directory with its contents.
+
+To check the installed version, run Chrome Canary and navigate to `chrome://version` in the address bar, or use:
+
+```bash
+/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary --version
+```
+
+#### Troubleshooting
+
+**Problem**: `Error: Cask 'google-chrome@canary' is unavailable`
+
+**Solution**: Update Homebrew to get the latest cask definitions:
+
+```bash
+brew update
+```
+
+**Problem**: Installation fails with "macOS version not supported"
+
+**Solution**: Chrome Canary requires macOS 12 or later. Upgrade your operating system or use an older version of Chrome stable for older macOS versions.
+
+**Problem**: `brew: command not found`
+
+**Solution**: Homebrew is not in your PATH. Add it by running:
+
+```bash
+eval "$(/opt/homebrew/bin/brew shellenv)"
+```
+
+For permanent fix, add the above line to your `~/.zshrc` or `~/.bash_profile`.
+
+**Problem**: Quarantine warning when first launching
+
+**Solution**: macOS may quarantine downloaded applications. Remove the quarantine attribute:
+
+```bash
+xattr -dr com.apple.quarantine /Applications/Google\ Chrome\ Canary.app
+```
+
+---
+
+### Ubuntu/Debian (APT)
+
+#### Prerequisites
+
+- Ubuntu 18.04 or later, or Debian 10 or later (64-bit only)
+- x86_64 architecture (Intel/AMD processors)
+- sudo privileges
+- `wget` and `gnupg` packages installed
+
+Chrome Canary is available through Google's official APT repository. This method provides automatic updates through the standard APT update mechanism.
+
+#### Installation Steps
+
+**Step 1**: Install required dependencies:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y wget gnupg
+```
+
+**Step 2**: Download and install Google's signing key:
+
+```bash
+wget -qO - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg
+```
+
+**Step 3**: Add the Google Chrome repository:
+
+```bash
+echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list > /dev/null
+```
+
+**Step 4**: Update the package list and install Chrome Canary:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y google-chrome-canary
+```
+
+#### Verification
+
+Confirm the installation succeeded:
+
+```bash
+google-chrome-canary --version
+```
+
+Expected output (version numbers may vary):
+
+```
+Google Chrome 145.0.7614.0 canary
+```
+
+To launch Chrome Canary:
+
+```bash
+google-chrome-canary
+```
+
+#### Troubleshooting
+
+**Problem**: `E: Unable to locate package google-chrome-canary`
+
+**Solution**: The repository may not have been added correctly. Verify the repository file exists:
+
+```bash
+cat /etc/apt/sources.list.d/google-chrome.list
+```
+
+If empty or missing, repeat Step 3 from the installation steps.
+
+**Problem**: GPG key error during `apt-get update`
+
+**Solution**: Re-download and install the signing key:
+
+```bash
+sudo rm -f /etc/apt/keyrings/google-chrome.gpg
+wget -qO - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg
+```
+
+**Problem**: `dpkg: error processing package` with dependency issues
+
+**Solution**: Fix broken dependencies:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -f -y
+```
+
+**Problem**: Chrome Canary fails to launch with "no sandbox" error
+
+**Solution**: Chrome requires a proper sandbox environment. If running in a container or VM without proper privileges, launch with:
+
+```bash
+google-chrome-canary --no-sandbox
+```
+
+**Warning**: Running without a sandbox reduces security and should only be done in isolated testing environments.
+
+---
+
+### Raspberry Pi OS (APT)
+
+#### Platform Limitation
+
+**Google Chrome Canary is NOT available for Raspberry Pi OS.**
+
+Google does not provide ARM builds of Chrome Canary. The Chrome team only releases Canary builds for x86_64 (Intel/AMD) architectures on Linux. Raspberry Pi devices use ARM processors, which are incompatible with the available Chrome Canary packages.
+
+#### Recommended Alternative
+
+Use Chromium, the open-source project that Chrome is based on. Chromium is pre-installed on Raspberry Pi OS and provides similar functionality:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y chromium-browser
+```
+
+Verify installation:
+
+```bash
+chromium-browser --version
+```
+
+**Note**: Chromium does not have a "Canary" equivalent channel. The standard Chromium package tracks stable releases. For newer features, you can build Chromium from source, though this is time-consuming and resource-intensive on Raspberry Pi hardware.
+
+#### Why This Limitation Exists
+
+Google prioritizes Canary builds for platforms where most developers work (x86_64 desktops). ARM Linux devices represent a small fraction of the developer market, so Google has not allocated resources to produce and test ARM Canary builds. The unstable nature of Canary would also compound the challenges of supporting a less common architecture.
+
+---
+
+### Amazon Linux/RHEL (DNF/YUM)
+
+#### Platform Limitation
+
+**Google Chrome Canary is NOT available for Amazon Linux, RHEL, CentOS, or Fedora.**
+
+Google does not release Chrome Canary packages for RPM-based Linux distributions. The Chrome Canary channel is only available for Debian/Ubuntu-based systems on Linux.
+
+#### Recommended Alternative
+
+Use the Chrome Unstable (Dev) channel, which is the closest available alternative. It receives updates approximately weekly and includes experimental features before they reach the Beta or Stable channels.
+
+**For Amazon Linux 2023 / Fedora:**
+
+**Step 1**: Enable the Google Chrome repository:
+
+```bash
+sudo tee /etc/yum.repos.d/google-chrome.repo > /dev/null << 'EOF'
+[google-chrome]
+name=google-chrome
+baseurl=https://dl.google.com/linux/chrome/rpm/stable/$basearch
+enabled=1
+gpgcheck=1
+gpgkey=https://dl.google.com/linux/linux_signing_key.pub
+EOF
+```
+
+**Step 2**: Install Chrome Unstable (Dev channel):
+
+```bash
+sudo dnf install -y google-chrome-unstable
+```
+
+**For Amazon Linux 2 / CentOS 7:**
+
+```bash
+sudo yum install -y google-chrome-unstable
+```
+
+Verify installation:
+
+```bash
+google-chrome-unstable --version
+```
+
+#### Why This Limitation Exists
+
+Google has historically focused Canary releases on platforms with the largest developer populations. The Debian/Ubuntu ecosystem dominates Linux desktop usage among developers, so Google prioritizes APT-based Canary packages. The Unstable (Dev) channel provides a similar "early access" experience with weekly updates.
+
+---
+
+### Windows (Chocolatey)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11 (64-bit)
+- Chocolatey package manager installed
+- Administrator PowerShell or Command Prompt
+
+If Chocolatey is not installed, install it first by running this command in an 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'))
+```
+
+#### Installation Steps
+
+Run the following command in an Administrator PowerShell or Command Prompt:
+
+```powershell
+choco install googlechromecanary -y --pre
+```
+
+The `-y` flag automatically confirms all prompts, enabling fully non-interactive installation. The `--pre` flag allows installation of prerelease packages (Chrome Canary is marked as prerelease in Chocolatey).
+
+**Important Note**: The Chocolatey package always installs the latest version of Chrome Canary, regardless of any version specified. Google does not offer archived Canary builds for download.
+
+#### Verification
+
+Open a new Command Prompt or PowerShell window (required for PATH to update), then verify installation:
+
+```powershell
+where "Google Chrome Canary"
+```
+
+Or launch Chrome Canary directly:
+
+```powershell
+Start-Process "chrome-canary"
+```
+
+Chrome Canary installs to: `C:\Users\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe`
+
+#### Troubleshooting
+
+**Problem**: `googlechromecanary not found` or package not available
+
+**Solution**: Ensure you include the `--pre` flag, as Chrome Canary is marked as a prerelease package:
+
+```powershell
+choco install googlechromecanary -y --pre
+```
+
+**Problem**: Checksum mismatch error during installation
+
+**Solution**: Google frequently updates Canary (daily), which can cause checksum mismatches. Ignore the checksum and install anyway:
+
+```powershell
+choco install googlechromecanary -y --pre --ignore-checksums
+```
+
+**Problem**: Installation fails with access denied
+
+**Solution**: Ensure you are running PowerShell or Command Prompt as Administrator. Right-click and select "Run as administrator".
+
+**Problem**: Chrome Canary not found after installation
+
+**Solution**: Chrome Canary installs per-user, not system-wide. Check the user's local application data:
+
+```powershell
+dir "$env:LOCALAPPDATA\Google\Chrome SxS\Application\chrome.exe"
+```
+
+---
+
+### WSL (Ubuntu)
+
+#### Prerequisites
+
+- Windows Subsystem for Linux with Ubuntu installed
+- WSL 2 recommended for best performance
+- sudo privileges within WSL
+- X server or WSLg for GUI applications (Windows 11 includes WSLg by default)
+
+WSL Ubuntu installations follow the same process as native Ubuntu, using Google's APT repository.
+
+#### Installation Steps
+
+**Step 1**: Install required dependencies:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y wget gnupg
+```
+
+**Step 2**: Download and install Google's signing key:
+
+```bash
+wget -qO - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg
+```
+
+**Step 3**: Add the Google Chrome repository:
+
+```bash
+echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list > /dev/null
+```
+
+**Step 4**: Update the package list and install Chrome Canary:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y google-chrome-canary
+```
+
+#### Verification
+
+Confirm the installation succeeded:
+
+```bash
+google-chrome-canary --version
+```
+
+To launch Chrome Canary with GUI (requires WSLg or X server):
+
+```bash
+google-chrome-canary &
+```
+
+#### Troubleshooting
+
+**Problem**: Chrome Canary fails to launch with display errors
+
+**Solution**: On Windows 11 with WSLg, ensure WSLg is enabled. On Windows 10, install and configure an X server like VcXsrv:
+
+```bash
+export DISPLAY=:0
+google-chrome-canary
+```
+
+**Problem**: Chrome crashes immediately on launch in WSL
+
+**Solution**: WSL may have issues with Chrome's sandbox. Launch with sandbox disabled (testing environments only):
+
+```bash
+google-chrome-canary --no-sandbox --disable-gpu
+```
+
+**Problem**: Slow performance or rendering issues
+
+**Solution**: Disable GPU acceleration if running through X11 forwarding:
+
+```bash
+google-chrome-canary --disable-gpu
+```
+
+**Problem**: `E: Unable to locate package google-chrome-canary`
+
+**Solution**: Follow the complete installation steps to set up the Google Chrome repository. The default Ubuntu repositories in WSL do not include Google Chrome packages.
+
+---
+
+### Git Bash (Windows Installation)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11 (64-bit)
+- Git Bash installed (comes with Git for Windows)
+- Chrome Canary installed on Windows (see Windows section above)
+
+**Note**: Git Bash on Windows does not require a separate Chrome Canary installation. Git Bash inherits the Windows PATH and can access Windows applications directly. Once Chrome Canary is installed on Windows, it is automatically available in Git Bash.
+
+#### Installation Steps
+
+Install Chrome Canary on Windows using the Windows installer. From Git Bash, you can trigger the installation using Chocolatey (if installed on Windows):
+
+```bash
+/c/ProgramData/chocolatey/bin/choco.exe install googlechromecanary -y --pre
+```
+
+Alternatively, download and run the official installer silently:
+
+```bash
+# Download the installer
+curl -L -o /tmp/ChromeCanarySetup.exe "https://dl.google.com/tag/s/appguid%3D%7B4EA16AC7-FD5A-47C3-875B-DBF4A2008C20%7D%26iid%3D%7B00000000-0000-0000-0000-000000000000%7D%26lang%3Den%26browser%3D4%26usagestats%3D0%26appname%3DChrome%2520Canary%26needsadmin%3Dprefers%26ap%3Dx64-canary-statsdef_0%26brand%3DGGLS/dl/chrome/install/ChromeSetup.exe"
+
+# Run silent installation (opens Windows installer)
+/tmp/ChromeCanarySetup.exe /silent /install
+```
+
+After installation, close and reopen Git Bash for PATH changes to take effect.
+
+#### Verification
+
+Confirm Chrome Canary is accessible from Git Bash:
+
+```bash
+"/c/Users/$USER/AppData/Local/Google/Chrome SxS/Application/chrome.exe" --version
+```
+
+Or if Chrome Canary is in your PATH:
+
+```bash
+chrome-canary --version
+```
+
+#### Troubleshooting
+
+**Problem**: Chrome Canary executable not found
+
+**Solution**: Chrome Canary installs to the user's AppData directory. Access it directly:
+
+```bash
+"/c/Users/$USER/AppData/Local/Google/Chrome SxS/Application/chrome.exe"
+```
+
+Create an alias for convenience in `~/.bashrc`:
+
+```bash
+alias chrome-canary='"/c/Users/$USER/AppData/Local/Google/Chrome SxS/Application/chrome.exe"'
+```
+
+**Problem**: Chrome opens but Git Bash terminal hangs
+
+**Solution**: Launch Chrome in the background:
+
+```bash
+"/c/Users/$USER/AppData/Local/Google/Chrome SxS/Application/chrome.exe" &
+```
+
+**Problem**: Cannot download installer with curl
+
+**Solution**: Ensure curl is configured to follow redirects and use the Windows temp directory:
+
+```bash
+curl -L -o "$TEMP/ChromeCanarySetup.exe" "https://www.google.com/chrome/canary/thank-you.html?installdataindex=empty&statcb=0&defaultbrowser=0"
+```
+
+---
+
+## Post-Installation Configuration
+
+Chrome Canary runs with a separate user profile from Chrome stable. This allows you to test experimental features without affecting your primary browsing data.
+
+### Enable Experimental Features
+
+Access Chrome's experimental flags:
+
+1. Open Chrome Canary
+2. Navigate to `chrome://flags` in the address bar
+3. Search for specific features or browse categories
+4. Enable desired experiments and relaunch
+
+### Command-Line Flags for Testing
+
+Launch Chrome Canary with specific testing configurations:
+
+```bash
+# Enable all experimental web platform features
+google-chrome-canary --enable-experimental-web-platform-features
+
+# Disable web security for local development (use with caution)
+google-chrome-canary --disable-web-security --user-data-dir=/tmp/chrome-dev
+
+# Enable verbose logging for debugging
+google-chrome-canary --enable-logging --v=1
+```
+
+### Sync Settings (Optional)
+
+Chrome Canary supports Google account sync, but consider keeping it disabled to maintain isolation between your stable and experimental browser environments.
+
+---
+
+## Common Issues
+
+### Issue: Chrome Canary Crashes Frequently
+
+**Symptoms**: Browser crashes on startup or while browsing.
+
+**Solution**: Chrome Canary is inherently unstable. If crashes are severe:
+
+1. Reset Chrome Canary by deleting its profile directory
+2. Disable recently enabled flags at `chrome://flags`
+3. Wait for the next nightly update, which may include a fix
+
+Profile locations:
+- **macOS**: `~/Library/Application Support/Google/Chrome Canary/`
+- **Linux**: `~/.config/google-chrome-canary/`
+- **Windows**: `%LOCALAPPDATA%\Google\Chrome SxS\User Data\`
+
+### Issue: Extensions Not Working
+
+**Symptoms**: Certain extensions fail to load or function correctly.
+
+**Solution**: Extensions may not be compatible with bleeding-edge Chrome APIs. Check the extension's compatibility or use Chrome stable for extensions requiring stability.
+
+### Issue: Website Rendering Incorrectly
+
+**Symptoms**: Websites appear broken or differently than in stable Chrome.
+
+**Solution**: This may indicate experimental rendering changes. Test the same site in Chrome stable to confirm it's a Canary-specific issue. Report bugs to the Chromium bug tracker.
+
+### Issue: Multiple Chrome Versions Conflict
+
+**Symptoms**: Wrong version of Chrome opens, or unexpected behavior.
+
+**Solution**: Chrome Canary installs separately from Chrome stable:
+- **macOS**: "Google Chrome Canary.app" vs "Google Chrome.app"
+- **Linux**: `google-chrome-canary` vs `google-chrome-stable`
+- **Windows**: "Chrome SxS" directory vs "Chrome" directory
+
+Ensure you launch the correct executable.
+
+---
+
+## References
+
+- [Google Chrome Canary Official Page](https://www.google.com/chrome/canary/)
+- [Homebrew Cask: google-chrome@canary](https://formulae.brew.sh/cask/google-chrome@canary)
+- [Chocolatey Package: googlechromecanary](https://community.chocolatey.org/packages/googlechromecanary)
+- [Winget Package: Google.Chrome.Canary](https://winget.run/pkg/Google/Chrome.Canary)
+- [Google Chrome APT Repository (Ubuntu Updates)](https://www.ubuntuupdates.org/ppa/google_chrome)
+- [Chromium Project](https://www.chromium.org/)
+- [Chrome Release Channels](https://www.chromium.org/getting-involved/dev-channel/)
+- [Chrome Flags Documentation](https://peter.sh/experiments/chromium-command-line-switches/)