Merge pull request PelicanPlatform#1649 from jhiemstrawisc/issue-1535

Cleanup MacOS installation instructions

docs/pages/federating-your-data.mdx

@@ -1,7 +1,7 @@
 import ExportedImage from "next-image-export-optimizer";
 import { Key } from '@mui/icons-material';
 
-# Federation Your Data via Pelican Origin
+# Federating Your Data via a Pelican Origin
 
 Pelican users who want to share data within a Pelican federation do so via an [*Origin*](./core-concepts.mdx#origins). Origins are a crucial component of Pelican's architecture for two reasons: they act as an adapter between various storage backends and Pelican federations, and they provide fine-grained access controls for that data. That is, they figure out how to take data from wherever it lives (such as a POSIX filesystem, S3 buckets, HTTPS servers, etc.) and transform it into a format that the federation can utilize while respecting your data access requirements.
 

docs/pages/install.mdx

@@ -2,16 +2,12 @@ import DownloadsComponent from "/components/DownloadsComponent";
 
 # Install Pelican
 
-This document lists the operating system requirements for Pelican and explains how a user can download and install Pelican.
+This document lists Pelican's operating system requirements and explains how you can download and install the correct Pelican executable.
 
 ## Before Starting
 
-Pelican executables can run as a **client** or a **server**.
-
-To use the client for interacting with data, download and install the Pelican package or Pelican Binary [following the instructions below](#install-pelican-binary).
-
-For server usage, such as serving your data to a Pelican data federation or to start a new Pelican data federation, you need to run Pelican using [Pelican Docker images](./install/docker.mdx). It is not recommended to run Pelican server with a binary. Although technically possible, additional software dependencies and configurations are required to make the binary functional for server usage.
-
+Pelican executables can run as a **client** or a **server**, and both are packaged in the same executable. However, if you intend to run a server, some non-RPM installations may require additional package dependencies.
+For this use case (hosting an Origin/Cache, starting your own federation Central Services) we recommend using a containerized version of Pelican from our [Pelican Docker images](./install/docker.mdx).
 
 ## Supported Operating Systems
 
@@ -25,31 +21,35 @@ Pelican supports the following operating systems, when running as a **client**:
 
 > **Note**: Installation of Pelican on other operating systems is possible, but not recommended or supported.
 
-## Download Pelican Binary
+## Determine Which Executable To Download
 
-Download the binary based on your operating system and CPU architecture. For instructions on how to install the binary, refer to [the next section](#install-pelican-binary).
+Each section of the following chart contains a link to a specific Pelican executable based on your operating system and CPU architecture. If you don't know your computer's architecture, refer to any specific instructions for your operating system under [Install Pelican Executable](#install-pelican-executable). The vast majority of non-MacOS operating systems will use an x86_64 architecture.
+
+Once you've determined which executable to use, copy the provided link and continue to [Install Pelican Executable](#install-pelican-executable).
 
 <DownloadsComponent />
 
-### What version should I download?
-Our versions are built like so:
-For example: 7.1.2
-- 7 represents the major version release
-- 1 represents feature releases
-- 2 represents a bug fix/patch release
+### What Version Should I Download?
+In most cases, you should use the highest version of Pelican available because it will contain our latest features and bug fixes. This is the default link provided unless you specify otherwise.
+
+If you need a specific version that isn't the latest, you can select it using the chart's "Version" dropdown.
+Pelican follows the [semantic versioning scheme](https://semver.org/), so, for example, 7.10.5 means:
+- 7 represents the major release (changes in this number represent large changes that may break backwards compatibility)
+- 10 represents feature releases (each increment within the same major release represents new, backward-compatible functionality)
+- 5 represents a bug fix/patch release
 
-The download table above includes Pelican versions as old as `7.6.x` To download older versions, please refer to the [GitHub release page](https://github.com/PelicanPlatform/pelican/releases).
+The download table above includes Pelican versions as old as `v7.6.x` To download older versions, please refer to our [GitHub release archive](https://github.com/PelicanPlatform/pelican/releases).
 
-## Install Pelican Binary
+## Install Pelican Executable
 
 ### Linux
 
 * [Install Pelican on Red Hat Enterprise Linux (CentOS, Fedora, Alma, Rocky, or openSUSE)](./install/rhel.mdx)
 * [Install Pelican on Debian or Ubuntu](./install/debian.mdx)
 * [Install Pelican on Alpine Linux](./install/alpine.mdx)
-* [Install Pelican as a standalone binary](./install/linux-binary.mdx)
+* [Install Pelican as a standalone executable](./install/linux-binary.mdx)
 
-### macOS
+### MacOS
 
 * [Install Pelican on macOS](./install/macos.mdx)
 
@@ -60,7 +60,7 @@ The download table above includes Pelican versions as old as `7.6.x` To download
 
 ### Install OSDF or Server Package
 
-Pelican has two special packaging, `OSDF` and `Server`. The `OSDF` packaging, i.e. `pelican-osdf-compat`, is for running Pelican in Open Science Data Federation (OSDF). The `Server` packaging, i.e. `pelican-server` is for running Pelican services, e.g., an *Origin* or a *Cache*.
+Pelican has two special packaging, `OSDF` and `Server`. The `OSDF` packaging, i.e. `pelican-osdf-compat`, is for running Pelican in the Open Science Data Federation (OSDF). The `Server` packaging, i.e. `pelican-server` is for running Pelican services, e.g., an *Origin* or a *Cache*.
 
 Both of the packages **require Pelican package to be installed first**. You may get the following error message if you only install the special package:
 
@@ -69,13 +69,11 @@ Problem: conflicting requests
   - nothing provides pelican needed by pelican-osdf-compat-7.8.5-1.aarch64 from @commandline
 ```
 
-To fix the issue, install the Pelican package first by following [the instructions](#install-pelican-binary) above.
-
-The server components require `xrootd-server >= 5.6.3` because of some of the patches Pelican needs. For Ubuntu users, it is required to install Pelican server package on `Ubuntu 24.04` ("noble") and above.
+To fix the issue, install the Pelican package first by following [the preceding instructions](#install-pelican-executable).
 
 ## Verify Pelican Is Installed
 
-> If you installed Pelican as a standalone binary, or if you installed Pelican on macOS or Windows operating systems, you need to add Pelican to your `PATH` environment variable before proceeding. Follow the instructions for [Linux](./install/linux_binary.mdx#add-pelican-binary-to-your-path-permanently), [macOS](./install/macos.mdx#add-pelican-binary-to-your-path), and [Windows](./install/windows.mdx#add-pelican-binary-to-your-path).
+> If you installed Pelican as a standalone executable, or if you installed Pelican on MacOS or Windows operating systems, you need to add Pelican to your `PATH` environment variable before proceeding. See instructions for your operating system under the [os-specific installation instructions section](#install-pelican-executable)
 
 1. Run the following command after you installed Pelican
 
@@ -84,23 +82,13 @@ The server components require `xrootd-server >= 5.6.3` because of some of the pa
         which pelican
         ```
 
-        It should output something similar to
-
-        ```console
-        /bin/pelican
-        ```
     * **Windows**:
         ```bash
         where pelican
         ```
+    If this command outputs a filepath, Pelican is installed correctly. If no output is returned, revisit instructions for your operating system.
 
-        It should output something similar to
-
-        ```console
-        C:\Program Files\Pelican\pelican.exe
-        ```
-
-2. Test Pelican client function by running an **object get** command that downloads a test file from [Open Science Data Federation (OSDF)](https://osg-htc.org/services/osdf) to your current directory
+1. Test the Client's functionality by running an **object get** command that downloads a test file from [Open Science Data Federation (OSDF)](https://osg-htc.org/services/osdf) to your current directory
 
     ```bash
     $ pelican object get pelican://osg-htc.org/ospool/uc-shared/public/OSG-Staff/validation/test.txt .

docs/pages/install/macos.mdx

@@ -1,71 +1,69 @@
-# Install Pelican on macOS
+# Install Pelican on MacOS
 
-This document explains how to install Pelican on macOS.
+This document explains how to install Pelican on MacOS.
 
-## Install Pelican as a standalone binary
+## Install Pelican as a Standalone Executable
 
-Pelican provides a binary file instead of a `DMG` installer for macOS. You need to download and extract the binary and add the binary to your `PATH` environment variable.
+Pelican provides a binary executable file instead of a `DMG` installer for MacOS, so installation must happen through a terminal. This process entails downloading/extracting the executable and adding it to your computer's `PATH` environment variable.
 
-1. Navigate to [Pelican download page](../install.mdx#download-pelican-binary) and select the Pelican macOS binary you want to install.
+1. If you've not yet determined which executable you need, refer to the [download page](../install.mdx#determine-which-executable-to-download) and copy the relevant link: In the **Operating System** section, select **macOS**. In **Architectures** section, select **X86_64** or **ARM64** depending on the architecture of your machine.
 
-2. In the **Operating System** section, select **macOS**. In **Architectures** section, select **X86_64** or **ARM64** depending on the architecture of your machine.
+    > **Note:** If you don't know your computer's architecture, click the **Apple menu**  in the top-left corner of your screen, then click **About This Mac** and check the **Chip** or **Processor** field. If it mentions **Intel** your computer needs Pelican's **X86_64** executable, and if it mentions Apple M1, M2, or later, you'll need the **ARM64** executable. Intel Macs (x86_64) should see the file `pelican_Darwin_x86_64.tar.gz` and Apple Silicon Macs (ARM64) should see `pelican_Darwin_arm64.tar.gz`.
 
-3. In the list of candidates, copy the link to `pelican_Darwin_x86_64.tar.gz` if you select **X86_64**, or `pelican_Darwin_arm64.tar.gz` if you select **ARM64**.
-
-4. Change the following command with the link to the binary you copied in the previous step and run the command:
+1. Open a terminal and navigate to a directory where you can download, extract and store the Pelican executable. Then use your command line tools of choice to download and extract the link you copied in the previous step. The rest of these intructions assume `curl` for downloading and `tar` for extraction:
 
     ```bash
-    wget <replace-with-the-link-you-copied>
-    tar -zxvf pelican_Darwin_arm64.tar.gz // ARM user
+    curl -LO <replace-with-the-link-you-copied>
+    tar -zxvf <name-of-downloaded-file>
     ```
 
-    Note that you need to replace `pelican_Darwin_arm64.tar.gz` with `pelican_Darwin_x86_64.tar.gz` if you are running an X86 machine.
-
-    Example to install Pelican binary for an ARM machine:
+    Example to install Pelican executable for an Apple Silicon Mac:
 
     ```bash
-    curl -O https://github.com/PelicanPlatform/pelican/releases/download/v7.5.8/pelican_Darwin_arm64.tar.gz
+    curl -LO https://github.com/PelicanPlatform/pelican/releases/download/v7.10.5/pelican_Darwin_x86_64.tar.gz
     tar -zxvf pelican_Darwin_arm64.tar.gz
     ```
 
-5. The above command extracted the binary from the tar file. You may run the binary in the current folder, but it is recommended that you add Pelican binary to your `PATH` environment variable to allow `pelican` to be called directly from your command line. To run Pelican binary from the download folder:
+1. There should now be another directory called `pelican-<version>` containing a Pelican executable that you can run directly using a relative `./` path. For example:
 
     ```bash
-    $ cd pelican_Darwin_arm64 # Go to the binary folder
-    $ ./pelican --version # Run Pelican binary
+    $ cd pelican-7.10.5
+    $ ./pelican --version # Print the executable version
 
-    Version: 7.5.8
-    Build Date: 2024-03-01T18:13:00Z
-    Build Commit: d260a07d3b057d19b7fdd36125f91a8768531258
+    Version: 7.10.8
+    Build Date: 2024-10-09T14:56:56Z
+    Build Commit: 1ef2c25a1585803e0c74a9e41fceb214b80bf3da
     Built By: goreleaser
     ```
 
-## Add Pelican binary to your `PATH`
+    However, to make the `pelican` command available everywhere on your Mac without needing a relative path, you still need to add it to your system's `PATH` environment variable.
+
+## Add Pelican Executable to Your `PATH`
 
-  * Add Pelican binary to your `PATH` for the current terminal
+  * Add the Pelican executable to your `PATH` for the current terminal session (disappears after closing the terminal)
 
     ```bash
-    $ cd pelican_Darwin_arm64 # Go to the binary folder
+    $ cd pelican-7.10.5 # Go to the executable folder
     $ export PATH=$PWD:$PATH # Add current folder to the PATH
-    $ pelican --version # Run Pelican binary
+    $ pelican --version # Run Pelican executable
 
-    Version: 7.5.8
-    Build Date: 2024-03-01T18:13:00Z
-    Build Commit: d260a07d3b057d19b7fdd36125f91a8768531258
+    Version: 7.10.8
+    Build Date: 2024-10-09T14:56:56Z
+    Build Commit: 1ef2c25a1585803e0c74a9e41fceb214b80bf3da
     Built By: goreleaser
     ```
 
-  * Add Pelican binary to your `PATH` permanently
+  * Add the Pelican executable to your `PATH` permanently (persists through terminal restarts)
 
     ```bash
-    $ cd pelican_Darwin_arm64 # Go to the binary folder
+    $ cd pelican-7.10.5 # Go to the executable folder
     $ echo "export PATH=$PWD:\$PATH" >> ~/.zshrc # Add the current folder to your .zshrc file
     $ source ~/.zshrc # Apply the change
-    $ pelican --version # Run Pelican binary
+    $ pelican --version # Run Pelican executable
 
-    Version: 7.5.8
-    Build Date: 2024-03-01T18:13:00Z
-    Build Commit: d260a07d3b057d19b7fdd36125f91a8768531258
+    Version: 7.10.8
+    Build Date: 2024-10-09T14:56:56Z
+    Build Commit: 1ef2c25a1585803e0c74a9e41fceb214b80bf3da
     Built By: goreleaser
     ```