Merge pull request #35 from cdot65:29-enhancement-ship-docker-contain…

…er-for-pan-os-upgrade-script-execution

Add Dockerfile and GitHub Actions workflow for Docker image

.github/workflows/container-build-publish.yml

@@ -0,0 +1,25 @@
+name: Build and push Docker image to GitHub Container Registry
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish-container-image:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v1
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build the container image
+        run: |
+          docker build --tag ghcr.io/cdot65/pan-os-upgrade:latest
+          docker push ghcr.io/cdot65/pan-os-upgrade:latest

README.md

@@ -10,7 +10,7 @@
 <!-- PROJECT LOGO -->
 <br />
 <div align="center">
-    <img src="https://github.com/cdot65/pan-os-upgrade/blob/main/images/logo.svg?raw=true" alt="Logo">
+    <img src="https://github.com/cdot65/pan-os-upgrade/blob/main/docs/images/logo.svg?raw=true" alt="Logo">
     <h3 align="center">PAN-OS Automation Project</h3>
     <p align="center">
         Streamlining Palo Alto Networks Firewall Upgrades with Python Automation
@@ -52,28 +52,84 @@ Key Features:
 
 > Note: this script is targeted towards standalone and `active-passive` HA environments, no testing has been performed against `active-active` or clustered firewalls.
 
-Example Screenshot
+Example Execution
 
-![Example Screenshot](https://github.com/cdot65/pan-os-upgrade/blob/main/images/screenshot.jpg?raw=true)
+<div class="termy">
+
+```console
+pan-os-upgrade --ip-address 192.168.255.211 --username admin --password secret --version 10.2.0-h2
+INFO - ✅ Connection to firewall established
+INFO - 📝 007054000123456 houston 192.168.255.211
+INFO - 📝 Firewall HA mode: disabled
+INFO - 📝 Current PAN-OS version: 10.2.0
+INFO - 📝 Target PAN-OS version: 10.2.0-h2
+INFO - ✅ Confirmed that moving from 10.2.0 to 10.2.0-h2 is an upgrade
+INFO - ✅ Target PAN-OS version 10.2.0-h2 is available for download
+INFO - ✅ Base image for 10.2.0-h2 is already downloaded
+INFO - 🚀 Performing test to see if 10.2.0-h2 is already downloaded...
+INFO - 🔍 PAN-OS version 10.2.0-h2 is not on the firewall
+INFO - 🚀 PAN-OS version 10.2.0-h2 is beginning download
+INFO - Device 007054000123456 downloading version: 10.2.0-h2
+INFO - ⚙️ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 4 seconds
+INFO - ⚙️ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 36 seconds
+INFO - ⚙️ Downloading PAN-OS version 10.2.0-h2 - Elapsed time: 71 seconds
+INFO - ✅ 10.2.0-h2 downloaded in 103 seconds
+INFO - ✅ PAN-OS version 10.2.0-h2 has been downloaded.
+INFO - 🚀 Performing snapshot of network state information...
+INFO - ✅ Network snapshot created successfully
+INFO - 🚀 Performing readiness checks to determine if firewall is ready for upgrade...
+INFO - ✅ Passed Readiness Check: Check if there are pending changes on device
+INFO - ✅ Passed Readiness Check: No Expired Licenses
+INFO - ✅ Passed Readiness Check: Check if a there is enough space on the `/opt/panrepo` volume for downloading an PanOS image.
+INFO - ✅ Passed Readiness Check: Check if NTP is synchronized
+INFO - ✅ Passed Readiness Check: Check connectivity with the Panorama appliance
+INFO - ✅ Readiness Checks completed
+INFO - 🚀 Performing backup of houston's configuration to local filesystem...
+INFO - 🚀 Not a dry run, continue with upgrade...
+INFO - 🚀 Performing upgrade on houston to version 10.2.0-h2...
+INFO - 🚀 Attempting upgrade houston to version 10.2.0-h2 (Attempt 1 of 3)...
+INFO - Device 007054000123456 installing version: 10.2.0-h2
+INFO - ✅ houston upgrade completed successfully
+INFO - 🚀 Rebooting the firewall...
+INFO - 📝 Command succeeded with no output
+INFO - ⚙️ Firewall is responding to requests but hasn't finished its reboot process...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is rebooting...
+INFO - ⚙️ Firewall is responding to requests but hasn't finished its reboot process...
+INFO - ⚙️ Firewall is responding to requests but hasn't finished its reboot process...
+INFO - ⚙️ Firewall is responding to requests but hasn't finished its reboot process...
+INFO - ✅ Firewall upgraded and rebooted in 542 seconds
+```
+
+</div>
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- GETTING STARTED -->
 ## Getting Started
 
-This guide will help you set up the `pan-os-upgrade` library in your environment, especially focusing on users who are new to Python and virtual environments.
+There are two primary methods to utilize the `pan-os-upgrade` tool: through a Python virtual environment or via a Docker container. Both methods are outlined below to cater to different preferences or requirements.
+
+### Running with Python Virtual Environment
 
-### Prerequisites
+This approach involves setting up a Python virtual environment on your local machine and running the `pan-os-upgrade` tool within this isolated environment.
+
+#### Python Prerequisites
 
 * Python 3.8 or newer.
 * Access to a Palo Alto Networks firewall.
 * An active internet connection to download the package from PyPI.
 
-### Installation
+#### Installation
 
 The `pan-os-upgrade` library is available on PyPI and can be installed within a Python virtual environment. A virtual environment is a self-contained directory that contains a Python installation for a particular version of Python, plus a number of additional packages.
 
-#### Creating a Python Virtual Environment
+##### Creating a Python Virtual Environment
 
 The steps below highlight the process for creating, activating, and installing `pan-os-upgrade` into a Python virtual environment. If you're new to Python, it may be beneficial to understand why this is such an important step, [here is a good writeup](https://realpython.com/python-virtual-environments-a-primer/) to prime yourself.
 
@@ -109,11 +165,11 @@ The steps below highlight the process for creating, activating, and installing `
     pip install pan-os-upgrade
     ```
 
-### Setting Up Your Environment
+#### Setting Up Your Environment
 
-After setting up the virtual environment and installing the package, you can configure your environment to use the library. This can be done using command-line arguments or an .env file.
+After setting up the virtual environment and installing the package, you can configure your environment to use the library. This can be done using command-line arguments or using the interactive shell.
 
-#### Option 1: Execute `pan-os-upgrade` without Command-Line Arguments
+##### Option 1: Execute `pan-os-upgrade` without Command-Line Arguments
 
 You can simply get started by issuing `pan-os-upgrade` from your current working directory, you will be guided to input the missing requirement arguments through an interactive shell.
 
@@ -132,7 +188,7 @@ INFO - ✅ Confirmed that moving from 11.0.2 to 11.1.1 is an upgrade
 ...continue until completed...
 ```
 
-#### Option 2: Execute `pan-os-upgrade` Using Command-Line Arguments
+##### Option 2: Execute `pan-os-upgrade` Using Command-Line Arguments
 
 Alternatively, you can pass these details as command-line arguments when running the script:
 
@@ -148,6 +204,50 @@ pan-os-upgrade --ip-address 192.168.1.1 --username admin --password secret --ver
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+### Running with Docker
+
+Alternatively, you can run `pan-os-upgrade` as a Docker container. This method ensures that the tool runs in an isolated environment with all its dependencies packaged together.
+
+#### Docker Prerequisites
+
+* Docker installed on your system. You can download it from [Docker's official site](https://www.docker.com/products/docker-desktop).
+
+#### Pulling the Docker Image
+
+First, pull the `pan-os-upgrade` image from GitHub Packages:
+
+```bash
+docker pull ghcr.io/cdot65/pan-os-upgrade:latest
+```
+
+#### Running the Container
+
+To run the container and mount local directories for `assurance` and `logs`, use the following commands:
+
+On macOS and Linux:
+
+```bash
+docker run -v $(pwd)/assurance:/app/assurance -v $(pwd)/logs:/app/logs -it pan-os-upgrade
+```
+
+On Windows:
+
+```bash
+docker run -v %CD%/assurance:/app/assurance -v %CD%/logs:/app/logs -it pan-os-upgrade
+```
+
+These commands mount the current directory's `assurance` and `logs` subdirectories to the corresponding directories in the container. If these directories don't exist on your host, Docker will create them.
+
+#### Interactive Mode
+
+The container will start in interactive mode, prompting you for the necessary input like IP address, username, password, and target PAN-OS version.
+
+#### Accessing Logs and Output
+
+After the container stops, you can find the logs and other output files in the `assurance` and `logs` directories of your current working directory on your host machine.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 <!-- USAGE EXAMPLES -->
 ## Usage
 
@@ -255,4 +355,3 @@ Project Link: [https://github.com/cdot65/pan-os-upgrade](https://github.com/cdot
 [issues-url]: https://github.com/cdot65/pan-os-upgrade/issues
 [license-shield]: https://img.shields.io/github/license/cdot65/pan-os-upgrade.svg?style=for-the-badge
 [license-url]: https://github.com/cdot65/pan-os-upgrade/blob/main/LICENSE
-[product-screenshot]: https://github.com/cdot65/pan-os-upgrade/blob/main/images/screenshot.jpg

docker/Dockerfile

@@ -0,0 +1,24 @@
+# Use an official Python runtime as a parent image, based on Alpine
+FROM python:3.12-alpine
+
+# Install dependencies required for compiling certain Python packages
+# gcc and musl-dev are required for compiling C extensions
+# libffi-dev is required for the cffi package
+# make is often required for building packages
+RUN apk add --no-cache gcc musl-dev libffi-dev make
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy the requirements file into the container at /app
+COPY requirements.txt /app/
+
+# Install any needed packages specified in requirements.txt
+# Note: The requirements.txt should contain pan-os-upgrade==0.2.2
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Set the locale to avoid issues with emoji rendering
+ENV LANG C.UTF-8
+
+# Run the application
+CMD ["pan-os-upgrade"]

docker/requirements.txt

@@ -0,0 +1 @@
+pan-os-upgrade==0.2.2

docs/about/contributing.md

@@ -25,7 +25,7 @@ Before you begin, make sure you have a GitHub account and are familiar with Git
     git checkout -b feature/YourFeatureName
     ```
 
-4. **Set Up the Development Environment:** Follow the [Getting Started](../user-guide/getting-started.md) to set up your local development environment.
+4. **Set Up the Development Environment:** Follow the [Getting Started](../user-guide/python/getting-started.md) to set up your local development environment.
 
 ---
 

docs/about/release-notes.md

@@ -2,6 +2,24 @@
 
 Welcome to the release notes for the `pan-os-upgrade` tool. This document provides a detailed record of changes, enhancements, and fixes in each version of the tool.
 
+## Version 0.2.2
+
+**Release Date:** *<20240121>*
+
+### What's New
+
+- Optimized for Docker execution.
+- Refreshed documentation to showcase both paths of execution (Python virtual environments and Docker)
+
+## Version 0.2.1
+
+**Release Date:** *<20240121>*
+
+### What's New
+
+- Adjusting the execution of our script to instead reference the Typer app `app()` instead of `main()`.
+- Updated the `pan-os-upgrade` alias within the pyproject.toml file to directly call `app()` instead of `main()`
+
 ## Version 0.2.0
 
 **Release Date:** *<20240121>*