installing isis and setting up the data area (#125)

* installing isis and setting up the data area * spelling commmand * Combine TESTDATA info from readme, update TOC * data area changes from PR feedback 1 * native mac unix tab * Point links to new docs instead of readme * misssion spelling
DOI-USGS · Nov 21, 2024 · 203e2d2 · 203e2d2
1 parent 1ecd688
commit 203e2d2
Show file tree

Hide file tree

Showing 8 changed files with 553 additions and 120 deletions.
diff --git a/docs/getting-started/using-ale/isd-generate.md b/docs/getting-started/using-ale/isd-generate.md
@@ -178,7 +178,7 @@ isd_generate --version
 
 ## Setting Up NAIF Data
 
-For use of NAIF Data with ISIS, see [The ISIS Data Area](https://github.com/DOI-USGS/ISIS3/blob/dev/README.md#the-isis-data-area).  For use of NAIF data with ALE, continue below.
+For use of NAIF Data with ISIS, see the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md).  For use of NAIF data with ALE, continue below.
 
 ### Downloading NAIF SPICE Data with wget
 

diff --git a/docs/getting-started/using-isis-first-steps/isis-faq.md b/docs/getting-started/using-isis-first-steps/isis-faq.md
@@ -76,9 +76,9 @@
     Some ISIS software updates include mission specific command updates motivated by new information (updated kernels, format changes, etc.) from mission teams. When the software is updated the data area should also be updated, see [Mission Specific Data Downloads][5].
 
     [3]: https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html
-    [4]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#full-isis-data-download
-    [5]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#mission-specific-data-downloads
-    [6]: https://github.com/DOI-USGS/ISIS3?tab=readme-ov-file#isis-spice-web-service
+    [4]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#full-download
+    [5]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#mission-specific-data-areas
+    [6]: ../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#isis-spice-web-service
     [7]: ../../getting-started/using-isis-first-steps/locating-and-ingesting-image-data.md
 
 ???+ abstract "Additional Helpful Docs"

diff --git a/docs/how-to-guides/ale-developer-guides/creating-ale-drivers.md b/docs/how-to-guides/ale-developer-guides/creating-ale-drivers.md
@@ -4,7 +4,7 @@ This guide provides step-by-step instructions for creating an ALE driver for an
 
 ## Prerequisites 
 1. Clone and build [ISIS](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake) locally.
-1. Download base and mission kernels related to the driver you plan to implement.  One means of downloading this kernels is through ISIS's [downloadIsisData script](https://github.com/DOI-USGS/ISIS3/blob/dev/README.md#partial-download-of-isis-base-data).
+1. Download base and mission kernels related to the driver you plan to implement.  One means of downloading this kernels is through ISIS's [downloadIsisData script](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md#downloading-isisdata).
 1. Fork [the ALE repository](https://github.com/USGS-Astrogeology/ale)
 1. Clone from your fork (with the recursive flag to clone submodules as well):
     ```sh

diff --git a/...how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md b/...how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md
@@ -1,124 +1,270 @@
-# Installation
+# Installing ISIS
 
-This installation guide is for ISIS users interested in installing ISIS (3.6.0)+ through conda.
+## Prerequisites
 
-## ISIS Installation With Conda
+??? "Conda"
 
-1. Download either the Anaconda or Miniconda installation script for your OS platform. Anaconda is a much larger distribution of packages supporting scientific python, while Miniconda is a minimal installation and not as large: [Anaconda installer](https://www.anaconda.com/download), [Miniconda installer](https://conda.io/miniconda.html)
-1. If you are running on some variant of Linux, open a terminal window in the directory where you downloaded the script, and run the following commands. In this example, we chose to do a full install of Anaconda, and our OS is Linux-based. Your file name may be different depending on your environment.
-
-    ```bash
-    chmod +x Anaconda3-5.3.0-Linux-x86_64.sh
-    ./Anaconda3-5.3.0-Linux-x86_64.sh
+    If you don't have conda yet, download and install it.  We recommend getting conda through [MiniForge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge).
+
+    ```sh
+    # Via Miniforge:
+    curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+    bash Miniforge3-$(uname)-$(uname -m).sh
     ```
-    This will start the Anaconda installer which will guide you through the installation process.
 
-1. If you are running Mac OS X, a pkg file (which looks similar to Anaconda3-5.3.0-MacOSX-x86\_64.pkg) will be downloaded. Double-click on the file to start the installation process.
-1. After the installation has finished, open up a bash prompt in your terminal window.
-1. If you have an ARM64 Mac (M1/M2) running Catalina (or later), additional prerequisites must be installed for ISIS to run in emulation:
- - Install [XQuartz](https://www.xquartz.org/). (Tested with XQuartz 2.8.5 on MacOS Catalina)
- - Install Rosetta2. From the terminal run: `/usr/sbin/softwareupdate --install-rosetta --agree-to-license`
- - Include the `# MacOS ARM64 Only` lines below
-1. Next setup your Anaconda environment for ISIS. In the bash prompt, run the following commands:
+??? "x86 emulation on ARM Macs - Rosetta"
+
+    If you have an ARM mac and want to run the x86 version of ISIS, you will need Rosetta.
 
-    ```bash
+    ```sh
+    /usr/sbin/softwareupdate --install-rosetta --agree-to-license
+    ```
 
-    #MacOS ARM64 Only - Setup the new environment as an x86_64 environment
+
+## Conda Environment
+
+=== "Native Mac/Unix"
+
+    ```sh
+    # Create conda environment, then activate it.
+    conda create -n isis 
+    conda activate isis
+    ```
+
+=== "x86 on ARM Macs"
+
+    ```sh
+    # ARM Macs Only - Setup the new environment as x86_64
     export CONDA_SUBDIR=osx-64
 
-    #Create a new conda environment to install ISIS in
-    conda create -n isis python>=3.9
-
-    #Activate the environment
+    # Create conda environment, then activate it.
+    conda create -n isis
     conda activate isis
 
-    #MacOS ARM64 Only - Force installation of x86_64 packages instead of ARM64
+    # ARM Macs Only - Force installation of x86_64 packages, not ARM64
     conda config --env --set subdir osx-64
+    ```
 
-    #Add the following channels to the environment
-    conda config --env --add channels conda-forge
-    conda config --env --add channels usgs-astrogeology
+### Channels
+
+```sh
 
-    #Verify you have the correct channels:
+# Add conda-forge and usgs-astrogeology channels
+conda config --env --add channels conda-forge
+conda config --env --add channels usgs-astrogeology
+
+# Check channel order
+conda config --show channels
+```
+
+??? warning "Channel Order: `usgs-astrogeology` must be higher than `conda-forge`"
+
+    Show the channel order with:
+
+    ```sh
     conda config --show channels
+    ```
 
-    #You should see:
+    You should see:
 
+    ```
     channels:
         - usgs-astrogeology
         - conda-forge
         - defaults
+    ```
 
-    #The order is important.  If conda-forge is before usgs-astrogeology, you will need to run:
+    If `conda-forge` is before `usgs-astrogeology`, add usgs-astrogeology again to bring up.  Set channel priority to flexible instead of strict.
 
+    ```sh
     conda config --env --add channels usgs-astrogeology
-    
-    #Then set channel_priority to flexible in case there is a global channel_priority=strict setting
     conda config --env --set channel_priority flexible
     ```
 
-1. The environment is now ready to download ISIS and its dependencies:
+## Downloading ISIS
+
+The environment is now ready to download ISIS and its dependencies:
+
+=== "Latest Release"
 
-    ```bash
+    ```sh
     conda install -c usgs-astrogeology isis
     ```
 
-1. Finally, setup the environment variables:
+=== "LTS"
+
+    ```sh
+    conda install -c usgs-astrogeology/label/LTS isis
+    ```
+
+=== "Release Candidate"
+
+    ```sh
+    conda install -c usgs-astrogeology/label/RC isis
+    ```
+
+
+## Environmental Variables
+
+ISIS requires these environment variables to be set in order to run correctly:
+
+- `ISISROOT` - Directory path containing your ISIS install
+- `ISISDATA` - Directory path containing the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md)
+
+???+ example "Setting Environmental Variables"
+
+    The **Conda Env** method is recommended, and the **Python Script** automates that method:
+
+    === "Conda Env"
+
+        ??? "Requires Conda 4.8 or above"
+
+            Check your conda version, and update if needed:
 
-    ISIS requires several environment variables to be set in order to run correctly.
-    The variables include: ISISROOT and ISISDATA.
+            ```sh
+            # Check version
+            conda --version
 
-    The following steps are only valid for versions of ISIS after 4.2.0.
-    For older versions of ISIS follow the instructions in [this readme file.](https://github.com/USGS-Astrogeology/ISIS3/blob/adf52de0a04b087411d53f3fe1c9218b06dff92e/README.md)
+            # Update
+            conda update -n base conda
+            ```
 
-    There are two methods to configure the environment variables for ISIS:
+        1.  Activate your ISIS environment.  
+            ```
+            conda activate isis
 
-    A. Using `conda env config vars` *preferred*
+            # Now you can set variables with:
+            # conda config vars set KEY=VALUE
+            ```
 
-       Conda has a built in method for configuring environment variables that are specific to a conda environment since version 4.8.
-       This version number applies only to the conda package, not to the version of miniconda or anaconda that was installed.
+        1.  This command sets both required variables (fill in your `ISISDATA` path):
 
-       To determine if your version of conda is recent enough run:
+                conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[your data path]
 
-           conda --version
+        1.  Re-activate your isis environment. 
+            ```sh
+            conda deactivate
+            conda activate isis
+            ```
 
-       If the version number is less than 4.8, update conda to a newer version by running:
+        The environment variables are now set and ISIS is ready for use every time the isis conda environment is activated.
 
-           conda update -n base conda
 
-       The version number should now be greater than 4.8.
+    === "Python Script"
 
-       To use the built in environment variable configuration feature, first activate the environment by first running:
+        By default, running this script will set `ISISROOT=$CONDA_PREFIX` and `ISISDATA=$CONDA_PREFIX/data`:
 
-           conda activate isis
+            python $CONDA_PREFIX/scripts/isisVarInit.py
+        
+        You can specify a different path for `$ISISDATA` using the optional value:
 
-       After activation, the environment variables can be set using the syntax: `conda config vars set KEY=VALUE`.
-       To set all the environment variables ISIS requires, run the following command, updating the path to `ISISDATA` as needed:
+            python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]
 
-           conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[path to data directory]
+        Now every time the isis environment is activated, `$ISISROOT` and `$ISISDATA` will be set to the values passed to isisVarInit.py.
+        This does not happen retroactively, so re-activate the isis environment:
 
-       To make these changes take effect, re-activate the isis environment by running:
+            conda deactivate
+            conda activate isis
 
-           conda activate isis
 
-       The environment variables are now set and ISIS is ready for use every time the isis environment is activated.
+    === "export (shell)"
+
+        `export` sets a variable in your current shell environment until you close it.  Adding `export` commands to your `.bashrc` or `.zshrc` can make them persistent.
+
+        ```sh
+        export ISISROOT=[path to ISIS]
+        export ISISDATA=[path to data]
+        ```
+
+
+    === "ISIS <4.2.0"
+
+        Use the python script per instructions from [the old readme](https://github.com/USGS-Astrogeology/ISIS3/blob/adf52de0a04b087411d53f3fe1c9218b06dff92e/README.md).
+
+
+## The ISIS Data Area
+
+Many ISIS apps need extra data to carry out their functions.  This data varies depending on the mission, and may be quite large, so it is not included with ISIS; You will need to [download it separately](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md).
+
+-----
+
+!!! success "Installation Complete"
+
+    If you followed the above steps and didn't encounter any errors, you have completed your installation of ISIS.
+
+-----
+
+
+## Updating ISIS
+
+If ISIS was already installed with Conda, you can update it with:
+
+=== "Latest Release"
+
+    ```sh
+    conda update -c usgs-astrogeology isis
+    ```
+
+=== "LTS"
+
+    ```sh
+    conda update -c usgs-astrogeology/label/LTS isis
+    ```
+
+=== "Release Candidate"
+
+    ```sh
+    conda update -c usgs-astrogeology/label/RC isis
+    ```
+
+
+## Uninstalling ISIS
+
+To uninstall ISIS, deactivate the ISIS Conda Environment, and then remove it.  If you want to uninstall conda as well, see your conda installation's website ([Miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#uninstallation) if you installed conda with the above instructions).
+
+```sh
+conda deactivate
+conda env remove -n isis
+```
 
-    !!! Warning "The above method will not enable tab completion for arguments in C-Shell."
 -----
 
-    B. Using the provided isisVarInit.py script:
+## ISIS in Docker
+
+!!! quote ""
+
+    The ISIS production Dockerfile automates the conda installation process above.
+    You can either build the Dockerfile yourself or use the
+    [usgsastro/isis](https://hub.docker.com/repository/docker/usgsastro/isis)
+    image from DockerHub.
+
+    === "Prebuilt Image"
+
+        ```sh
+        docker run -it usgsastro/isis bash
+        ```
 
-       To use the default values for: `$ISISROOT` and `$ISISDATA`, run the ISIS variable initialization script with default arguments:
+    === "Building the Dockerfile"
 
-           python $CONDA_PREFIX/scripts/isisVarInit.py
 
-       Executing this script with no arguments will result in $ISISROOT=$CONDA\_PREFIX and $ISISDATA=$CONDA\_PREFIX/data. The user can specify different directories for `$ISISDATA` using the optional value:
+        Download [the production Docker file](https://github.com/DOI-USGS/ISIS3/blob/dev/docker/production.dockerfile), build, and run it:
 
-           python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]
+        ```sh
+        # Build
+        docker build -t isis -f production.dockerfile .
 
-       Now every time the isis environment is activated, $ISISROOT and $ISISDATA will be set to the values passed to isisVarInit.py.
-       This does not happen retroactively, so re-activate the isis environment with one of the following commands:
+        # Run
+        docker run -it isis bash
+        ```
 
-           for Anaconda 3.4 and up - conda activate isis
-           prior to Anaconda 3.4 - source activate isis
+    ### Mounting the ISIS data area
+
+    Usually you'll want to mount an external directory containing the ISIS data.
+    The data is not included in the Docker image.
+
+    ```
+    docker run -v /my/data/dir:/opt/conda/data -v /my/testdata/dir:/opt/conda/testData -it usgsastro/isis bash
+    ```
 
+    Then [download the data](#the-isis-data-area) into /my/data/dir to make it accessible inside your
+    container.