Update README with Docker usage instructions

README.md

@@ -1,13 +1,17 @@
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# biodiversityhorizons
+# Biodiversity Horizons
 
 <!-- badges: start -->
 
 [![codecov](https://codecov.io/gh/uw-ssec/biodiversity-horizons/graph/badge.svg?token=ee1oeNuMlb)](https://codecov.io/gh/uw-ssec/biodiversity-horizons)
 
 <!-- badges: end -->
 
+**Biodiversity Horizons** is an R-based project for processing climate data and
+analyzing primate distributions. It can be used locally (in R/RStudio) or run
+inside a Docker container for consistent dependencies across systems.
+
 ## Installation
 
 You can install the development version of biodiversityhorizons like so:
@@ -29,5 +33,163 @@ library(biodiversityhorizons)
 ## basic example code
 ```
 
-You’ll still need to render `README.Rmd` regularly, to keep `README.md`
-up-to-date. `devtools::build_readme()` is handy for this.
+#### For more advanced usage, refer to our [**Contributing Guidelines**](./Contributing.md)
+
+## Docker Usage
+
+We provide a Docker image so you can run the data processing scripts in a
+containerized environment, ensuring consistent R dependencies.
+
+### 1. Prerequisites
+
+- #### Install Docker: Refer to [**Install Docker Desktop Guide**](https://docs.docker.com/desktop/)
+
+### 2. Pull the Docker Image
+
+```
+docker pull ghcr.io/uw-ssec/biodiversity-horizons:latest
+```
+
+If this succeeds, the image is downloaded locally.
+
+#### (Optional) GitHub Container Registry Authentication:
+
+If pulling fails with a `“denied”` error, generate a
+[Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+(classic) with `read:packages` scope and run:
+
+```
+echo YOUR_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+```
+
+### 3. Obtain or Prepare your `data-raw/` folder
+
+- #### Option A: Using Your Own Data
+
+  If you already have .rds files:
+
+  - Create a local folder (e.g., ~/my_data) and place your .rds files there.
+  - That folder will be mounted as `/home/biodiversity-horizons/data-raw` in the
+    container.
+
+- #### Option B: Cloning This Repo for Sample Data
+
+  If you need sample .rds files provided by this project (in data-raw/):
+
+  **1. Clone this repository:**
+
+  ```
+  git clone https://github.com/uw-ssec/biodiversity-horizons.git
+  ```
+
+  ```
+  cd biodiversity-horizons
+  ```
+
+  **2. Use the included data-raw/ folder. It contains sample .rds files.**
+
+### 4. Run the Container Using run_container.sh
+
+We recommend using the script `run_container.sh` for simplicity. It mounts your
+data and output folders to the container and executes the main R script.
+
+- Ensure the script is executable:
+
+  ```
+  chmod +x run_container.sh
+  ```
+
+- Identify your directories:
+
+  - A data folder with .rds files (either your own or the cloned data-raw/)
+  - An outputs directory for script results
+
+- Run the container:
+
+  ```
+  ./run_container.sh /absolute/path/to/data-raw /absolute/path/to/outputs
+  ```
+
+  - Replace `/absolute/path/to/data-raw` or `/absolute/path/to/data-outputs`
+    with the paths on your machine.
+
+  - This mounts your local data-raw folder into the container and runs the
+    default script.
+
+### 5. Passing Additional Arguments
+
+You can pass custom arguments (e.g., parallel plan, workers), example:
+
+```
+./run_container.sh /absolute/path/to/data-raw /absolute/path/to/outputs multisession 4
+```
+
+These extra arguments are forwarded to the R script inside the container.
+
+## Setup and Run Apptainer
+
+**Step 1: Navigate to the biodiversity-horizons project directory**
+
+```
+cd ~/Desktop/biodiversity-horizons  # Adjust this path as needed
+```
+
+**Step 2: Run Docker with Apptainer inside an AMD64 environment**
+
+```
+docker run --rm -it --privileged \
+  --platform linux/amd64 \
+  -v $(pwd):/mnt \
+  godlovedc/apptainer bash
+```
+
+### Inside Docker Container:
+
+**Step 3: Pull and convert the Docker image into a .sif file for Apptainer**
+
+```
+apptainer pull /mnt/biodiversity-horizons.sif docker://ghcr.io/uw-ssec/biodiversity-horizons:latest
+```
+
+**Step 4: Verify the .sif file was created**
+
+```
+ls -l /mnt/biodiversity-horizons.sif
+```
+
+**Step 5: Run Apptainer shell and mount required directories**
+
+```
+apptainer shell --bind /mnt/data-raw:/home/biodiversity-horizons/data-raw /mnt/biodiversity-horizons.sif
+```
+
+### Inside Apptainer Shell:
+
+**Step 6: Move to the correct working directory**
+
+```
+cd /home/biodiversity-horizons
+```
+
+**Step 7: Run the R script**
+
+```
+Rscript /home/biodiversity-horizons/scripts/VISS_Sample_Data.R /home/biodiversity-horizons/data-raw
+```
+
+**(Optional) Step 8: Run the R script with custom arguments (e.g., using 2
+workers)**
+
+```
+Rscript /home/biodiversity-horizons/scripts/VISS_Sample_Data.R /home/biodiversity-horizons/data-raw multisession 2
+```
+
+## Running and Developing
+
+Instructions to run and contribute to the portal can be found in
+[**Contributing Guidelines**](./CONTRIBUTING.md)
+
+Please follow our [**UW-SSEC Code of Conduct**](./CODE_OF_CONDUCT.md) in all
+interactions. For questions or issues, open an
+[**Issue**](https://github.com/uw-ssec/biodiversity-horizons/issues) or contact
+the maintainers.