diff options
Diffstat (limited to 'source/installation.rst')
| -rw-r--r-- | source/installation.rst | 128 |
1 files changed, 37 insertions, 91 deletions
diff --git a/source/installation.rst b/source/installation.rst index 13a9534..d000661 100644 --- a/source/installation.rst +++ b/source/installation.rst @@ -1,136 +1,82 @@ -############ -Installation -############ +########################## +Selecting a Software Stack +########################## -Before you begin, the list below contains known requirements and limitations of AstroConda: +A "stack" is a collection of software designed to target the various use cases of our end-users. The three officially supported stacks are as follows: - - This documentation targets Miniconda3 (i.e. Python 3), but the installation instructions work equally well with any of the Miniconda distributions. - - AstroConda supports Linux (glibc ≥ 2.12) and Mac OS X (≥ 10.7; 10.6 is NOT supported) - - AstroConda contains packages for 64-bit [#archnote]_ Python 2.7 and 3.5. - - Conda only supports BASH and ZSH environments. If you are a native CSH user, execute ``bash -l`` prior to performing the procedures detailed in this guide. - - IRAF users: After configuring Miniconda for use with AstroConda, refer to the :ref:`iraf_install` section of this guide to continue your installation. +- :ref:`standard_install` provides: + - The full compliment of STScI software and utilities + - Python 2.7 or 3.x +- :ref:`iraf_install` provides: + - The full compliment of STScI software and utilities + - A IRAF/PyRAF environment + - Python 2.7 only +- :ref:`pipeline_install_jump` provides: + - The data processing environment used by STScI operations and instrument teams + - Python 3.x only -Obtain Miniconda -================ -.. note:: +.. _standard_install: - Installing Miniconda3 will not prevent you from using Python 2. +Standard Software Stack (without IRAF) +====================================== - ``conda`` allows you to deploy multiple independent Python environments, at-will, under a single Miniconda installation. You may have trouble following along with this guide if you choose to install Miniconda2. +The package management system, Conda, is now configured to pull from our repository, so you may go ahead and install the ``stsci`` package. This package installs nearly all of the software provided by STScI in one shot. - -Go grab a copy of `Miniconda3 <http://conda.pydata.org/miniconda.html>`_ from Continuum Analytics, Inc. Be sure to select the installation medium appropriate for your operating system (Linux or OS X) and architecture (64-bit). Follow the installation instructions for your platform provided on the download page. Before moving on to the next step, open a new terminal window, and run ``conda`` to verify your terminal session can find it. - - -Configure Conda -=============== - -In order to install packages directly from the AstroConda repository, you will need to configure Conda to do so. - -.. code-block:: sh - - $ conda config --add channels http://ssb.stsci.edu/astroconda - # Writes changes to ~/.condarc - -This command will append the AstroConda channel URL to Conda's channel search path. Be aware that adding additional `anaconda.org <https://anaconda.org>`_ or direct-url repositories can potentially effect thestability of AstroConda's run-time environment. - -For example, if you add a channel found on anaconda.org because it contains a software package you're interested in, but also provides the same software as AstroConda, it's possible you may lose track of where packages are coming from. If you decide to have multiple channels defined in your configuration and bugs begin to appear, it may be best to check their origin before issuing a support ticket to help@stsci.edu. ``conda list`` can be used to display such information about the packages installed in your environment. - - -Install AstroConda -================== - -.. attention:: - - If you are on an instrument team or need to calibrate data using the same environment as STScI operations, please `click here <releases.html>`_. - -Standard Installation (without IRAF) ------------------------------------- - -Now that Conda is configured to pull from our repository, you may go ahead and install the ``stsci`` metapackage. The example below generates a new conda environment named "astroconda", however, this naming convention is merely a suggestion. Feel free to use a name that works best for you. +The following example generates a new conda environment named "astroconda", however this naming convention is merely a suggestion. Feel free to use a name that works best for you. .. code-block:: sh $ conda create -n astroconda stsci -This will prompt you to confirm the installation of all the STScI packages available in AstroConda. After they are installed, the following command "activates" the astroconda environment, making these packages available to you. +After the installation is complete go ahead and activate the "astroconda" environment. This command only needs to be executed one time per terminal session. .. code-block:: sh $ source activate astroconda -.. note:: +To deactivate the "astroconda" environment, close your terminal window or run: - Though it is repeated a lot in examples, ``source activate astroconda`` only needs to be run once per terminal session. Running this command ensures subsequent commands will take effect only in the ``astroconda`` environment, keeping your system organized. +.. code-block:: sh - To deactivate the ``astroconda`` environment, close your terminal window or run ``source deactivate``. + $ source deactivate .. _iraf_install: -Legacy Installation (with IRAF) -------------------------------------- +Legacy Software Stack (with IRAF) +================================= +The maintainers of the AstroConda channel have limited resources to support :abbr:`IRAF (Image Reduction and Analysis Facility)`, but users that require the ability to run IRAF and PyRAF tasks may want to install it via AstroConda. For help with any issues that come up during installation or use, please visit the `PyRAF FAQ <http://www.stsci.edu/institute/software_hardware/pyraf/pyraf_faq>`_. **Linux users** please be sure to visit `this FAQ entry <faq.html#in-linux-how-do-i-install-iraf-s-32-bit-dependencies>`_ for a quick guide to installing IRAF's 32-bit dependencies. -The developers of AstroConda have limited resources to support :abbr:`IRAF (Image Reduction and Analysis Facility)`, but users that require the ability to run IRAF and PyRAF tasks may want to install it through AstroConda. For help with many issues that come up during installation or use, please visit the `PyRAF FAQ <http://www.stsci.edu/institute/software_hardware/pyraf/pyraf_faq>`_. If you are running Linux be sure to visit `this FAQ entry <faq.html#in-linux-how-do-i-install-iraf-s-32-bit-dependencies>`_ for a quick guide to installing IRAF's 32-bit dependencies. -.. attention:: +The package management system, Conda, is now configured to pull from our repository, so you may go ahead and install the ``stsci`` package, as well as ``pyraf``, and finally ``iraf``. The ``stsci`` package installs nearly all of the software provided by STScI in one shot, however if you prefer a slimmed down IRAF/PyRAF experience, feel free to omit it. - Usage of IRAF currently requires running in a Python 2.7 environment. - The instructions below will install IRAF into a separate, Python 2.7, - environment regardless of your default Python version or which environments - you've created previously. +Due to Python 3.x incompatibilities present in several tasks, it is recommended to install IRAF alongside Python 2.7. - This will keep your IRAF environment separate from your other day-to-day - environments, which will facilitate updating only one or the other, and allow - easier transition off in the event of deprecation. Simply ``source activate iraf27`` - for iraf work and ``source activate astroconda`` for day-to-day use. +The following example generates a new conda environment named "iraf27", however this naming convention is merely a suggestion, so please feel free to apply a name that works best for you. .. code-block:: sh - $ conda create -n iraf27 python=2.7 iraf pyraf stsci + $ conda create -n iraf27 python=2.7 stsci pyraf iraf -Then, just as with the default installation, it is necessary to activate the environment to make its commands and packages available. +After the installation is complete go ahead and activate the "iraf27" environment. This command only needs to be executed one time per terminal session. .. code-block:: sh $ source activate iraf27 - -Fine-tuning the Installation -============================ - -If you are short on hard drive space, have a slow internet connection, or are simply not interested in installing *everything but the kitchen sink*; please feel free to peruse the `manifest <http://ssb.stsci.edu/astroconda>`_ and install a custom mix of packages tailored to your needs. +To deactivate the "iraf27" environment, close your terminal window or run: .. code-block:: sh - $ conda create -n astroconda [package [package ...]] - $ source activate astroconda - -Installing Other Packages -========================= - -AstroConda provides a suite of packages that are known to work well together and are supported by engineers from STScI. However, being built on top of the widely-used ``conda`` tools for managing Python environments, AstroConda also supports the installation of additional 3rd-party packages. + $ source deactivate -Full documentation of the ``conda`` tool is available from Continuum Analytics, Inc., its creators and maintainers: http://conda.pydata.org/docs/using/index.html. However, we have provided a brief explanation of 3rd-party package installation below for quick reference. -For scientific packages available through Miniconda, installation is as simple as: - -.. code-block:: sh +.. _pipeline_install_jump: - $ source activate astroconda - $ conda install name_of_pkg - -Often, the easiest way to see if the package is available through Miniconda is to try installing it. The full list of available packages is here: http://repo.continuum.io/pkgs/. - -The Python-standard tool ``pip`` is also available to install packages distributed through the Python Package Index (PyPI): - -.. code-block:: sh - - $ source activate astroconda - $ pip install name_of_pkg +Pipeline Software Stack +======================= -.. rubric:: Footnotes +Due to the nature of the pipeline software stack, the installation instructions have been consolidated under a separate section, :ref:`pipeline_install`. -.. [#archnote] Intel x86_64 architecture |