Merge pull request #625 from cocopuff2u/nist-pages-docs

Updated Installation Documentation for mSCP 2.0 and Getting Started

src/content/docs/mscp-2/overview.mdx

@@ -138,42 +138,192 @@ macos_security/
 For testing only. Requirements may change before release.
 </Aside>
 
+There are three ways to run mSCP 2.0. Choose the method that works best for your environment.
+
+### Option 1: Python + Ruby
+
+Manual setup with virtual environment.
+
+**Requirements:**
+- Python >= 3.12.1 (3.14 is not supported)
+  - Recommended: [Macadmins Python](https://github.com/macadmins/python)
+- Ruby >= 3.4.4
+
 <Steps>
 
-1. ### Clone the dev_2.0 Branch
+1. ### Clone the Repository
 
    ```bash
    git clone -b dev_2.0 https://github.com/usnistgov/macos_security.git
    cd macos_security
    ```
 
-2. ### Install Prerequisites
+2. ### Python Setup
 
-   Requires Python 3.12.1 or higher.
-
-   **Python packages (required):**
    ```bash
-   pip3 install -r requirements.txt
+   # Create virtual environment
-   ```
+   python3 -m venv .venv
+   source .venv/bin/activate
 
-   **Ruby gems (optional — only needed for PDF output):**
+   # Install requirements
-   ```bash
+   python3 -m pip install .
-   gem install asciidoctor asciidoctor-pdf rouge --user-install
    ```
 
    <details>
-   <summary>**Want isolated installs?** Click to expand</summary>
+   <summary>**Having Python version issues?** Click to expand</summary>
 
-   **Python virtual environment:**
+   **Check your Python version:**
+   ```bash
+   python3 --version
+   ```
+
+   **Check version inside the venv:**
    ```bash
-   python3 -m venv .venv
    source .venv/bin/activate
-   pip3 install -r requirements.txt
+   python --version
-   deactivate  # when done
+   ```
+
+   **List all installed Python versions:**
+   ```bash
+   ls /opt/homebrew/bin/python3*
+   ls /usr/local/bin/python3*
+   ```
+
+   **Create venv with a specific version:**
+   ```bash
+   # Remove old venv if needed
+   rm -rf .venv
+
+   # Use full path to the Python version you want
+   /opt/homebrew/bin/python3.13 -m venv .venv
+   source .venv/bin/activate
    ```
 
    </details>
 
+3. ### Ruby Setup
+
+   ```bash
+   bundle install --binstubs --path mscp_gems
+   ```
+
+4. ### Generate Content
+
+   ```bash
+   # Create a baseline
+   ./mscp.py baseline -k cis_lvl1
+
+   # Generate guidance with all outputs
+   ./mscp.py guidance custom/baselines/cis_lvl1_macos_26.0.yaml -A
+
+   # When done, deactivate the virtual environment
+   deactivate
+   ```
+
+</Steps>
+
+---
+
+### Option 2: Container
+
+The easiest way to get started — no local dependencies required.
+
+**Requirements:**
+- [Apple Container](https://github.com/apple/container) or [Docker](https://www.docker.com/)
+
+<Steps>
+
+1. ### Create Local Folders
+
+   ```bash
+   mkdir -p ~/Desktop/mscp/custom
+   ```
+
+2. ### Run the Container
+
+   **Using Apple Container:**
+   ```bash
+   container run -it \
+     --volume ~/Desktop/mscp:/mscp/build \
+     --volume ~/Desktop/mscp/custom:/mscp/custom \
+     ghcr.io/brodjieski/mscp_2.0:latest
+   ```
+
+   <details>
+   <summary>**Apple Container commands** Click to expand</summary>
+
+   **Start the container service (required before first run):**
+   ```bash
+   container system start
+   ```
+
+   **Exit the container:**
+   ```bash
+   exit
+   ```
+
+   **Stop the container service:**
+   ```bash
+   container system stop
+   ```
+
+   **Check container service status:**
+   ```bash
+   container system status
+   ```
+
+   </details>
+
+   **Or Using Docker:**
+   ```bash
+   # Note: Docker requires full paths for volume mounts
+   docker run -it \
+     --volume /Users/<username>/Desktop/mscp:/mscp/build \
+     --volume /Users/<username>/Desktop/mscp/custom:/mscp/custom \
+     ghcr.io/brodjieski/mscp_2.0:latest
+   ```
+
+3. ### Generate Content
+
+   ```bash
+   # Create a baseline
+   ./mscp.py baseline -k cis_lvl1
+   # Output: Generated new baseline file: config/custom/baselines/cis_lvl1_macos_26.0.yaml
+
+   # Generate guidance with all outputs
+   ./mscp.py guidance custom/baselines/cis_lvl1_macos_26.0.yaml -A
+   # Output: MSCP DOCUMENT GENERATION COMPLETE! All documents in: /build/cis_lvl1_macos_26.0/
+   ```
+
+</Steps>
+
+---
+
+### Option 3: UV Workflow
+
+A fast, modern Python workflow using [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+**Requirements:**
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Ruby
+
+<Steps>
+
+1. ### Clone and Setup
+
+   ```bash
+   git clone https://github.com/usnistgov/macos_security.git
+   cd macos_security
+   git checkout dev_2.0
+   bundle install --binstubs --path mscp_gems
+   ```
+
+2. ### Run Commands
+
+   ```bash
+   uv run --python 3.13 mscp.py guidance config/default/baselines/macos/15/cis_lvl1.yaml
+   ```
+
 </Steps>
 
 ---

src/content/docs/welcome/getting-started.mdx

@@ -20,69 +20,89 @@ Each macOS version has its own branch (`sequoia`, `sonoma`, `ventura`, etc.).
 
 ## Setup
 
+**Requirements:**
+- Python >= 3.12.1 (3.14 is not supported)
+  - Recommended: [Macadmins Python](https://github.com/macadmins/python)
+- Ruby >= 3.4.4 (optional — for PDF output)
+
 <Steps>
 
-1. ### Install Python Packages
+1. ### Clone the Repository
 
-   macOS includes Python 3. Just install the required packages:
-
-   ```bash
-   pip3 install pyyaml xlwt --user
-   ```
-
-   **Optional** — for PDF output, also install Ruby gems:
-   ```bash
-   gem install asciidoctor asciidoctor-pdf rouge --user-install
-   ```
-
-   <details>
-   <summary>**Want isolated installs?** Click to expand</summary>
-
-   A **virtual environment** keeps packages separate from your system Python — useful if you don't want to install packages globally or need to avoid conflicts.
-
-   **Python virtual environment:**
-   ```bash
-   # Create environment (once)
-   python3 -m venv venv
-
-   # Activate before running scripts
-   source venv/bin/activate
-
-   # Install packages inside the environment
-   pip3 install -r requirements.txt
-
-   # When done, deactivate
-   deactivate
-   ```
-
-   **Ruby local bundle:**
-   ```bash
-   bundle install --path vendor/bundle
-   ```
-
-   </details>
-
-2. ### Get the Repository
-
-   **Option A: Clone with Git** (recommended)
    ```bash
    git clone https://github.com/usnistgov/macos_security.git
    cd macos_security
    git checkout sequoia
    ```
-   Replace `sequoia` with your target macOS version.
+   Replace `sequoia` with your target macOS version (`sequoia`, `sonoma`, `ventura`, etc.).
+
+   <details>
+   <summary>**Prefer to download a ZIP?** Click to expand</summary>
 
-   **Option B: Download ZIP**
    1. Go to the [GitHub repository](https://github.com/usnistgov/macos_security)
    2. Click the branch dropdown and select your macOS version
    3. Click **Code** → **Download ZIP**
    4. Extract and open the folder
 
-3. ### Verify Setup
+   </details>
+
+2. ### Python Setup
+
+   ```bash
+   # Create virtual environment
+   python3 -m venv .venv
+   source .venv/bin/activate
+
+   # Install requirements
+   pip3 install -r requirements.txt
+   ```
+
+   <details>
+   <summary>**Having Python version issues?** Click to expand</summary>
+
+   **Check your Python version:**
+   ```bash
+   python3 --version
+   ```
+
+   **Check version inside the venv:**
+   ```bash
+   source .venv/bin/activate
+   python --version
+   ```
+
+   **List all installed Python versions:**
+   ```bash
+   ls /opt/homebrew/bin/python3*
+   ls /usr/local/bin/python3*
+   ```
+
+   **Create venv with a specific version:**
+   ```bash
+   # Remove old venv if needed
+   rm -rf .venv
+
+   # Use full path to the Python version you want
+   /opt/homebrew/bin/python3.13 -m venv .venv
+   source .venv/bin/activate
+   ```
+
+   </details>
+
+3. ### Ruby Setup (Optional — for PDF output)
+
+   ```bash
+   bundle install --binstubs --path mscp_gems
+   ```
+
+4. ### Verify Setup
 
    Run this command to confirm everything works:
    ```bash
    ./scripts/generate_baseline.py -l
+
+   # When done, deactivate the virtual environment
+   deactivate
    ```
    You should see a list of available baselines.