xan/awips2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Revamped our CAVE Installation Page

Browse source 
-Change the entire layout to have consistent sections for the three OS's: System Requirements and Download and Installation Instructions.
-Windows now has two distinct installation methods
-Removed RHEL/Centos6 from documention (just say 7)
-Added a General Requirements section that is more directed at hardware (not OS specific)
-Renamed the caveData section to "Local Cache"
-Renamed the AWIPS Data in the Cloud section to "EDEX Connection"
-removed all the tables from the previous formatting, just use section headers, ordered and unordered lists, and notes
This commit is contained in:
Shay Carter 2020-11-17 15:04:24 -07:00
parent 77e0a80e21
commit 1eadccdc89
1 changed files with 108 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
docs/install/install-cave.md
View file

@ -1,55 +1,135 @@
# Install CAVE
## Download and Install CAVE
CAVE is the **C**ommon **A**WIPS **V**isualization **E**nvironment that is used for rendering and analyzing data for AWIPS. Unidata supports CAVE to work on three platforms: [Centos (Redhat) Linux](#linux), [Windows](#windows), and [macOS](#macos). The installer may require administrator priviledges to install and may require other system changes (environment variables, etc) as well.
> [Release 18.1.1-7, March 25, 2019](https://www.unidata.ucar.edu/blogs/news/category/AWIPS)
---
## Linux
| | |
|:----------------------------------------:|:--|
| <h1><i class="fa fa-linux"></i></h1> | <h4>[awips_install.sh --cave <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/software/awips2/awips_install.sh) </h4> <p>For CentOS/Red Hat 6 and 7. Installs to /awips2/cave and writes files to ~/caveData.</p> <tt><code>chmod 755 awips_install.sh<br>sudo ./awips_install.sh --cave</code></tt><p>Run CAVE from the Linux Desktop menu Applications > Internet > AWIPS CAVE, or from the command line as simply `cave`.</p> <div class="admonition note"><p class="admonition-title">System Requirements</p><ul><li>x86_64 CentOS/RHEL 6 or 7</li><li>OpenGL 2.0 capable device</li><li>4GB RAM</li><li><a href="http://www.nvidia.com/Download/index.aspx?lang=en-us">Latest NVIDIA driver</a></li><li>NVIDIA Quadro graphics card is recommended for full visualization quality</li><li>approx. 2GB disk space for data caching (~/caveData)</li></ul></div><p>You can reset CAVE at any time by removing the **~/caveData** directory (on macOS **~/Library/caveData**) and reconnecting to an EDEX server. </p> |
## General Requirements
## macOS
| | |
|:----------------------------------------:|:--|
| <h1><i class="fa fa-apple"></i></h1>|<h4> Download and install both<br>[awips-cave.dmg <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.dmg)<br>[awips-python.pkg <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-python.pkg)</h4> <p>**Supported Graphics Devices for macOS**<li>Intel HD Graphics</li><li>Intel Iris</li><li>NVIDIA GeForce</li></p><p>**Unsupported Graphics Devices for macOS**<li>AMD Radeon R9</li><li>AMD Radeon Pro</li><li>AMD FirePro D300</li></p> <p>Writes and syncs files to ~/Library/caveData.</p> <p>**awips-python.pkg** is not a prerequisite, and CAVE will still run and display data without it, but to use any derived parameter functions such as wind barbs/arrows and grid parameters on various vertical coordinates, jep must be installed in some way (it is assumed in /Library/Python/2.7/site-packages/jep/)</p>|
Regardless of what Operating System CAVE is running on, these general requirements are recommended in order for CAVE to perform optimally:
- OpenGL 2.0 Compatible Devices
- At least 4GB RAM
- At least 2GB Disk Space for Caching
- [Latest NVIDIA Driver](http://www.nvidia.com/Download/index.aspx?lang=en-us)
> Note: NVIDIA Quadro graphics card is recommended for full visualization capability
## Windows
| | |
|:----------------------------------------:|:--|
| <h1><i class="fa fa-windows"></i> </h1> |<b>Method 1: Install Directly on Windows</b> <h4> [awips-cave.msi <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.msi)</h4><p>Writes files to **~/caveData** (in your user home directory)</p> <p>Requires <b>Python 3</b>, <b>Numpy</b>, and <b>Jep</b> be installed</p> <p>Requires **PYTHONHOME** be defined</p> <p>In addition to the application directory, the MSI installer will attempt to copy the *[gridslice](https://github.com/mjames-upc/gridslice)* shared library to `$PYTHONHOME/Dlls`. If the `$PYTHONHOME` environmental variable is not defined, *gridslice* will not be installed. You can always rerun the installer after defining `$PYTHONHOME` and then check that the file `gridslice.pyd` is installed in `$PYTHONHOME/Dlls`.</p> <p>CAVE will still run without gridslice, but certain bundles which use derived parameters, such as [isentropic analyses](../cave/d2d-grids/#isentopic-analysis-270k-320k), will not load. </p> |
---
## Linux <i class="fa fa-linux"></i> 
### System Requirements
<p><b>Windows-Specific Instructions</b></p>
- 64 bit CentOS/Red Hat 7
### Download and Installation Instructions
1. Download the following installer: [**awips_install.sh** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/software/awips2/awips_install.sh)
2. Go to the download directory and run: `awips_install.sh --cave`
3. Make the installer an executable by running: `chmod 755 awips_install.sh`
4. Run the installer: `sudo ./awips_install.sh --cave`
- This will install the application in `/awips2/cave/` and set the local cache to `~/caveData/`
<div class="admonition note">
<h4>1) Download and install <strong><a href="https://conda.io/miniconda.html">Miniconda Python 3.7 for Windows</a></strong><a class="headerlink" href="#1-download-and-install-miniconda-python-37-for-windows" title="Permanent link"></a></h4><ul><li>Allow Miniconda3 to set <strong>PATH</strong> and other environment variables.</li><li><p>Ensure that <strong>PYTHONHOME</strong> is set to the Miniconda3 location.</p><p><img alt="" src="../../images/windows_envvars.png" /></p><p>If <strong>PYTHONHOME</strong> is not set, the <strong>gridslice</strong> Python module will not be installed or available.</p></li></ul><h4>2) Install dependent Python packages</h4><ul><li><code>pip install numpy==1.15.1 jep==3.8.2</code></li></ul><h4>3) Run <a href="https://www.unidata.ucar.edu/downloads/awips2/awips-cave.msi">awips-cave.msi <i class="fa fa-download"></i></a><a class="headerlink" href="#3-run-awips-cave-1amd64msi" title="Permanent link"></a></h4>
<p><b>**NOTE:</b> It has been noted that these instructions may result in the failed installation of jep and/or other required python components. We are working on a solution to install the python dependencies properly. If this failure occurs, then numerous products will not render properly. At this time we offer a second option below for Windows users -- download a pre-packaged Linux VM which contains CAVE. We're sorry for the inconvenience and appreciate your patience.</p>
</div>
To run CAVE either:
| | |
|:----------------------------------------:|:--|
| <h1><i class="fa fa-windows"></i> </h1> | <b>Method 2: Install Linux VM on Windows</b> <h4> [unidata_cave.zip <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/unidata_cave.zip)</h4><p>Requires **VMWare Workstation Player** to be installed (free software)</p><p>Once zipped file is downloaded, unzip the folder by right-clicking and selecting "Extract All". All files will be extracted into their own folder.</p><p>Open VMWare Player and go to Player >> File... >> Open, and then find the folder that was created from extracting the zipped file. There should be one file called "CentOS 7 - Unidata CAVE". Select that and it'll add a new option available in the right hand side VMWare Menu. Run that new option, if it asks if it's been moved or copied, select copied.</p><p>The user is named awips, the password is awips. The root password is unidataAWIPS. There should be a CAVE application icon on the desktop that will run CAVE. It should also run from the commandline with the command "cave".</p> |
- Use the terminal and type the command `cave`
- Find the application in the Linux Desktop menu: Applications > Internet > AWIPS CAVE
---
## AWIPS Data in the Cloud
## Windows <i class="fa fa-windows"></i> 
Unidata and XSEDE Jetstream have partnered to offer a EDEX data server in the cloud, open to the Unidata university community. Select the server in the Connectivity Preferences dialog, or enter **`edex-cloud.unidata.ucar.edu`** (without *http://* before, or *:9581/services* after).
For Windows, Unidata offers two installation options: a [**Linux Virtual Machine**](#method-1-linux-virtual-machine-recommended), or a [**Direct Windows Installation**](#method-2-direct-windows-install). Currently, the virtual machine is the recommended form of install. The direct installation can work, but currently we do not have complete instructions on how to get **jep** (which is a python package) running properly with CAVE. Because of this, CAVE will install just fine, but certain data products will not render in the application. The direct install also requires several system modifications and will require administrator priviledges. We are in the process of producing a working set of instructions for the direct install, but as of now just have old instructions, which likely will not have jep working properly.
### Method 1: Linux Virtual Machine (Recommended)
#### System Requirements
- [VMWare Workstation Player](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html) must be installed (free software)
#### Download and Installation Instructions
1. Download the zipped file containing the virtual machine: [**unidata_cave.zip** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/unidata_cave.zip)
2. Unzip the folder by right-clicking and selecting "Extract All". All files will be extracted into a new folder.
3. Open VMWare Player and go to **Player** > **File...** > **Open** and locate the folder that was created from the downloaded zipped file. Select the file called **"CentOS 7 - Unidata CAVE"**.
4. Run this new VM option. If it asks if it's been moved or copied, select **copied**.
- There will be a user in the Linux machine named "awips" and the password is "awips"
- The root password is "unidataAWIPS" if ever needed
To run CAVE either:
- Use the desktop icon
- Use the terminal and type the command `cave`
- Find the application in the Linux Desktop menu: Applications > Internet > AWIPS CAVE
### Method 2: Direct Windows Install
#### System Requirements
- Miniconda3
- Python
- Numpy
- Jep
- PYTHONHOME must be defined
- JAVA_HOME must be defined
- Visual C++ Build Tools 2015 Update 3 (Version 14.1)
> Note: [Specific instructions](#download-and-installation-instructions_2) are detailed for installing the above, but they still may not install jep properly
#### Download and Installation Instructions
1. Download and install [Miniconda Python 3.7 for Windows](https://conda.io/miniconda.html)
- Allow Miniconda3 to set **PATH** and other environment variables
- Ensure that **PYTHONHOME** is set to the Miniconda3 location
![Environment Variables Screenshot](../images/windows_envvars.png)
> Note: If PYTHONHOME is not set, the **gridslice** Python module will not be installed or available
2. [Download and install Microsoft Visual Studio C++ Build Tools](https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads)
- To access the page linked above you will need a Microsoft account
- Once at that webpage, **search for** ***"build tools c+"*** in order for the proper download to be returned
- Download **Visual C++ Build Tools 2015 Update 3**
3. Install dependent Python packages
- `pip install numpy==1.15.1 jep=3.8.2`
4. Download and install: [**awips-cave.msi** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.msi)
- In addition to the application directory, the MSI installer will attempt to copy the [*gridslice*](https://github.com/Unidata/gridslice) shared library to `$PYTHONHOME/Dlls/`. If the `$PYTHONHOME` environmental variable is not defined *gridslice* will not be installed. You can check to see if it was installed in the Dlls directory after you have completed steps 1-3.
> Note: CAVE will still run without gridslice, but certain bundles which use derived parameters, such as [**isentropic analysis**](../images/screenCapture-2016.04.04.13.41.26-20160404_000000.png), will not load.
---
## macOS <i class="fa fa-apple"></i> 
### System Requirements
- NVIDIA Graphics card is recommended, some Intel Graphics cards will working
> Note: Most AMD graphics cards are not supported
### Download and Installation Instructions
1. Download and install both: [**awips-cave.dmg** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.dmg) and [**awips-python.pkg** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-python.pkg)
- This will install CAVE as an application and set the local cache to `~/Library/caveData`
> Note: The awips-python.pkg is not necessarily required, and CAVE will still run without it, but any derived data such as barbs, arrows, and various grid products will not render without having **jep** installed (it is assumed to be in /Library/Python/2.7/site-packages/jep/)
To run CAVE either:
- Use the System Menu Go > Applications > CAVE
- Type &#8984; + Spacebar and then type "cave", the application should appear and you can hit **enter** to run it
---
## EDEX Connection
Unidata and XSEDE Jetstream have partnered to offer a EDEX data server in the cloud, open to the Unidata university community. Select the server in the Connectivity Preferences dialog, or enter **edex-cloud.unidata.ucar.edu** (without *http://* before, or *:9581/services* after).
![EDEX in the cloud](../images/boEbFSf28t.gif)
---
## caveData Directory
## Local Cache
After connecting to an EDEX server, you will have a local directory named **caveData** which contains files synced from EDEX as well as a client-side cache for data and map resources.
You can reset CAVE by removing the **caveData** directory and reconnecting to an EDEX server. Your local files have been removed, but if you are re-connecting to an EDEX server you have used before, the remote files will sync again to your local **~/caveData** (bundles, colormaps, etc.).
* Linux: `/home/<user>/caveData`
* macOS: `/Users/<user>/Library/caveData`
* Windows: `C:\Users\<user>\caveData`
- Linux: `/home/<user>/caveData/`
- macOS: `/Users/<user>/Library/caveData/`
- Windows: `C:\Users\<user>\caveData\`