====================
Installation Runbook
====================

Overview
========

Anaconda Enterprise Notebooks (AEN) is a Python data analysis
environment from Continuum Analytics. Accessed through a browser,
Anaconda Enterprise Notebooks is a ready-to-use, powerful,
fully-configured Python analytics environment.

We believe that programmers, scientists, and analysts should spend their
time analyzing data, not working to set up a system. Data should be
shareable, and analysis should be repeatable. Reproducibility should
extend beyond just code to include the runtime environment,
configuration, and input data.

Anaconda Enterprise Notebooks makes it easy to start your analysis
immediately.

Components
==========

This run book walks through the steps needed to install a basic Anaconda
Enterprise Notebooks system comprised of the front-end server, gateway,
and two compute machines.

-  **AEN Server:** The Anaconda Enterprise Notebooks *Server* is the
   administrative front-end to the AEN system. This is where users login
   to the AEN system, where user accounts are stored, and where AEN
   system administrators can manage the system.

-  **AEN Gateway:** The Anaconda Enterprise Notebooks *Gateway* is a
   gateway to a cluster of compute nodes, sits between the AEN *Server*
   where the users log in, and AEN Compute nodes where their projects
   run. It acts as a reverse proxy that authenticates users and
   automatically directs them to the proper AEN *Compute* node for their
   AEN Project. Users will not notice this component as it automatically
   routes them. One could put a *Gateway* in each data center in a
   tiered scale-out fashion.

-  **AEN Compute:** Anaconda Enterprise Notebooks *Compute* nodes are
   where AEN Projects are stored and run. AEN *Compute* nodes only need
   to be reachable by the *Gateway*, so they can be completely isolated
   by a firewall.

Table of Contents
=================

-  Anaconda Enterprise Installation Run Book

   -  Overview
   -  Components
   -  Table of Contents

-  Installation Requirements

   -  Hardware Recommendations
   -  OS Requirements
   -  Software Dependency Requirements
   -  Configuration Requirements

-  Install Preparation

   -  Download the Installers
   -  Document IP addresses

-  AEN Server

   -  AEN Server Install Preparation

      -  Install Nginx and MongoDB
      -  Install Elasticsearch and Java

   -  AEN Server Installation

      -  Setup Variables
      -  Install ``aen-server``
      -  Agree to license

   -  Post-Install Requirements

      -  Start Elasticsearch
      -  Test the AEN Server install
      -  Update the License

-  AEN Gateway

   -  AEN Gateway Installation

      -  Setup Environment Variables
      -  Install ``aen-gateway``

   -  Post-Install Requirements

      -  Register the Gateway
      -  Verify the Gateway has registered

-  AEN Compute

   -  AEN Compute Pre-requisites

      -  Log in for install host(s)
      -  Disk Space for Anaconda distribution
      -  Git for Notebook Version Control
      -  X Windows System for Plotting

   -  AEN Compute Installation

      -  Setup Environment Variables
      -  Install ``aen-compute``

   -  Post-Install Requirements

      -  Log in to AEN Server
      -  Create a New Resource

-  Optional Configuration

   -  Optional: Configure AEN Server to use a local Anaconda Repository
   -  Optional: Change the Projects Directory
   -  Optional: Enable Search Indexing
   -  Optional: Setting up a Default Project Environment
   -  Optional: Configure remote database

-  Wrapping Up

Installation Requirements
=========================

Hardware Requirements
---------------------

-  AEN Server

   -  2+GB RAM
   -  2+CPU cores
   -  20GB storage

-  AEN Gateway

   -  2 GB RAM
   -  2 CPU cores

-  AEN Compute (N-machines)

   -  Configure to meet the needs of the projects. At least:
   -  2GB RAM
   -  2 CPU cores

OS Requirements
---------------

-  RHEL/CentOS 6.7 on all nodes (Other operating systems are supported,
   however this document assumes RHEL or CentOS 6.7)
-  ``/opt/wakari``: Ability to install here and at least 5GB of storage
-  ``/projects``: this directory needs the filesystem mounted with Posix
   ACL support (Posix.1e)
-  Check with ``mount`` and
   ``tune2fs -l /path/to/filesystem | grep options``

Software Dependency Requirements
--------------------------------

-  Mongo Version: >= 2.6.8 and < 3.0 [AEN Server]
-  Nginx version: >=1.4.0 [AEN Server]
-  git [AEN Compute]
-  Elasticsearch Version: >=1.7 [AEN Server] (tested with 1.7.2 and 2.3.5)
-  Oracle Java Runtime Environment (JRE) 8 (tested with version 8U60) [AEN Server]

Configuration Requirements
--------------------------

Security Requirements

-  root or sudo access
-  SELinux in Permissive or Disabled mode - check with ``getenforce``

Network Requirements

-  TCP Ports

   -  Server: 80
   -  Gateway: 8089
   -  Compute: 5002

Other Requirements

-  AEN will require access to the home directory to create and manage users (unless
   you restricts AEN from managing user accounts meaning that the IT department
   must create and manage all user accounts at the OS level, see the :doc:`post-installation
   documentation <customization>` for additional information)

Assuming the above requirements are met, there are no additional
dependencies necessary for Anaconda Enterprise Notebooks.

Note: While not a requirement for running the software, these
instructions use wget to download packages used in the install process.
You may use other appropriate means to put the needed files into the
installation directory.

Installation Preparation
========================

Download the Installers
-----------------------

Download the installers and copy them onto each computer.

::

    wget http://cdn.demo.wakari.io/aen-server-4.0.0-Linux-x86_64.sh
    wget http://cdn.demo.wakari.io/aen-gateway-4.0.0-Linux-x86_64.sh
    wget http://cdn.demo.wakari.io/aen-compute-4.0.0-Linux-x86_64.sh

Document IP addresses or FQDNs
------------------------------

Anaconda Enterprise Notebooks is very sensitive to the IP address or
domain name used to connect to the *Server* and *Gateway* components. If
users will be using the domain name, you should install the components
using the domain name instead of the IP addresses. The authentication
system requires the proper hostnames when authenticating users between
the services.

Fill in the domain names or IP addresses of the components below and
record the auto-generated password for the administrative user account
``wakari`` in the box below after installing the *Server* component.

+---------------+------------------------+
| Component     | IP address -or- FQDN   |
+===============+========================+
| AEN Server    |                        |
+---------------+------------------------+
| AEN Gateway   |                        |
+---------------+------------------------+
| AEN Compute   |                        |
+---------------+------------------------+

Notes:

-  you can use FQDN or the IP address, but you must be consistent and
   use only one or the other.
-  we will refer to the values of these IP entries or DNS entries as,
   e.g., ``<AEN_SERVER_IP>`` or ``<AEN_SERVER_FQDN>``, particularly in
   examples of shell commands. Consider actually assigning those values
   to environment variables with similar names.
-  All three IP addresses can be the same if you wish to test on a
   single host before installing, e.g., AEN *Compute* across many
   separate compute nodes.

AEN Admin Account
-----------------

+--------------------------+------------+
| Admin Account Username   | Password   |
+==========================+============+
| ``wakari``               |            |
+--------------------------+------------+

The password in the table will be auto-generated later when we execute
the ``aen-server`` install script, and referred to throughout this
document as ``<AEN_PASSWORD>``. The table entry above is provided for
comparison to output from that step.

The AEN Admin account is named "wakari" by default but can be given any name by
setting the :ref:`AEN Functional ID <aen-functional-id>` before installation.
The AEN Functional ID will also be the username of the AEN Admin account.

Additional admin accounts can be created as described in the section on
:ref:`adding administrative users <adding-administrative-users>`.

AEN Server
==========

AEN *Server* is the administrative front-end to the entire system. This
is where users will log in to the system, where user accounts will be
stored, and where admins can manage the system.

*Note: Your users will only need the AEN*\ Server\ *IP address or FQDN*

This installation will create a AEN administration account with the user
name ``wakari`` and a randomized password referenced throughout this
document as ``<AEN_PASSWORD>``

AEN Server Install Preparation
------------------------------

Transfer the AEN Server installer to the AEN Server. Log in to the AEN
Server host machine.

Install Nginx and MongoDB
~~~~~~~~~~~~~~~~~~~~~~~~~

Download RPM files for installing nginx and mongodb:

::

    RPM_CDN="https://820451f3d8380952ce65-4cc6343b423784e82fd202bb87cf87cf.ssl.cf1.rackcdn.com"
    wget $RPM_CDN/nginx-1.6.2-1.el6.ngx.x86_64.rpm
    wget $RPM_CDN/mongodb-org-tools-2.6.8-1.x86_64.rpm
    wget $RPM_CDN/mongodb-org-shell-2.6.8-1.x86_64.rpm
    wget $RPM_CDN/mongodb-org-server-2.6.8-1.x86_64.rpm
    wget $RPM_CDN/mongodb-org-mongos-2.6.8-1.x86_64.rpm
    wget $RPM_CDN/mongodb-org-2.6.8-1.x86_64.rpm

Install the RPMs:

::

    sudo rpm -i *.rpm

Start MongoDB:

::

    sudo /etc/init.d/mongod start

Install ElasticSearch and Java
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Elasticsearch enables search to locate notebooks on AEN Server, and
enables searching for packages used by notebooks and their environments.

A recent version of Java (JRE) is required for installing Elasticsearch.
There are two options for obtaining the JRE:

#. Download with a browser

   -  http://download.oracle.com/otn-pub/java/jdk/8u65-b17/jre-8u65-linux-x64.rpm
   -  Must agree to the Oracle license terms for Java

#. Download with ``wget``
#. To enable scripted or automated installs, this step bypasses
   interactive shell prompts, including the license
#. Read and agree to the license before using this method:
   http://www.oracle.com/technetwork/licenses/standard-license-152015.html
#. Using this method constitutes acceptance of the Oracle License

::

    wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/8u65-b17/jre-8u65-linux-x64.rpm

Once you have agreed to the license and downloaded the RPM file, install
Java:

::

    sudo rpm -i jre*.rpm

Once you have installed the JRE, download and install Elasticsearch.

::

    wget https://download.elastic.co/elasticsearch/release/org/elasticsearch/distribution/rpm/elasticsearch/2.3.5/elasticsearch-2.3.5.rpm
    sudo rpm -i elasticsearch*.rpm
    sudo chkconfig --add elasticsearch

AEN Server Installation
-----------------------

Setup Variables
~~~~~~~~~~~~~~~

AEN Server Address
^^^^^^^^^^^^^^^^^^

Define an environment variable for the AEN Server address (FQDN or IP):

::

    export AEN_SERVER=<AEN_SERVER_IP>  # <from table above>

Note that the address (FQDN or IP) specified for the AEN server must be
resolvable by your intended AEN users web clients. You may verify your
hostname as follows:

::

    echo $AEN_SERVER

.. _`aen-functional-id`:

AEN Functional ID
^^^^^^^^^^^^^^^^^

AEN must be installed and executed by a Linux account called the AEN Service
Account. The username of the AEN Service Account is called the AEN Functional
ID (NFI). The AEN Service Account is created during AEN installation if it does
not exist and is used to run all AEN services.

The default NFI username is "wakari". To override that default value and set
the NFI to another name, set the environment variable "AEN_SRVC_ACCT" *before*
installation::

    export AEN_SRVC_ACCT="aen_admin"

This name will then be the username of the AEN Service Account and the username
of the AEN Admin account.

AEN Functional Group
^^^^^^^^^^^^^^^^^^^^

By default, AEN uses a Linux group (NFG) name of ``wakari`` for all
files and directories owned by the NFI. Set the following environment
variable ***before*** installation to specify a custom NFG whenever the
NFI environment variable is set: ``AEN_SRVC_GRP``

Example:

::

    export AEN_SRVC_GRP="aen_admin"

AEN Install sudo Command
^^^^^^^^^^^^^^^^^^^^^^^^

During AEN installation the installers perform various operations that
require root level privileges. By default the installers use the
``sudo`` command to perform these operations. Set the following
environment variable ***before*** installation to override the default
``sudo`` command to perform root level operations or no command at all
when the user running the installers has root privileges and the
``sudo`` command is not needed or available: ``AEN_SUDO_INSTALL_CMD``

Examples:

::

    export AEN_SUDO_INSTALL_CMD=""
    export AEN_SUDO_INSTALL_CMD="sudo2"

AEN sudo Command
^^^^^^^^^^^^^^^^

By default the AEN services uses ``sudo -u`` to perform operations on
behalf of other users. Such operations include ``mkdir``, ``chmod``,
``cp`` and ``mv``. Set the following environment variable before
installation to override the default ``sudo`` command when sudo is not
available on the system: ``AEN_SUDO_CMD``.

Note, AEN must have the ability to perform operations on behalf of other
users. This environment variable cannot be set to an empty string or
null. The ``AEN_SUDO_CMD`` must support the ``-u`` command line
parameter similar to the ``sudo`` command.

Example:

::

    export AEN_SUDO_CMD="sudo2"

Note on Post-Install Customization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Please** review the :doc:`post-installation
documentation <customization>` for additional information on
configuration options.

While root/sudo privileges are required during installation, root/sudo
privileges are not required during normal operations after install, if
user accounts are managed outside the software (for example, via LDAP).
However root/sudo privileges are required to start the services, thus in
the service config files there may still need to be a ``AEN_SUDO_CMD``
entry.

Install ``aen-server``
~~~~~~~~~~~~~~~~~~~~~~

Ensure that the installation scripts have execute permissions:

::

    chmod a+x aen-*.sh

Execute the appropriate installation script:

::

    # use -b to avoid license prompt
    sudo -E ./aen-server-4.0.0-Linux-x86_64.sh -w $AEN_SERVER

If you have no license file or encounter any problems, please contact
your enterprise support representative.

Agree to the License
~~~~~~~~~~~~~~~~~~~~

You must agree to the license first. Hit spacebar to page through the
license and type ``yes`` to accept the terms.

::

    <license text>
    ...
    ...

    PREFIX=/opt/wakari/wakari-server
    Logging to /tmp/wakari_server.log
    Checking server name
    Ready for pre-install steps
    Installing miniconda
    installing: python-2.7.10-1 ...
    Python 2.7.10 :: Continuum Analytics, Inc.
    installing: bootstrap-3.1.1-7 ...
    installing: boto-2.38.0-py27_0 ...
    installing: bower-1.3.8-0 ...
    installing: compass-0.12.4-9 ...
    installing: conda-api-1.1.0-py27_0 ...
    installing: distribute-0.6.45-py27_1 ...
    installing: ecdsa-0.13-py27_0 ...
    installing: elasticsearch-1.6.0-0 ...
    tar: info/index.json: implausibly old time stamp 1970-01-01 00:00:00
    installing: elasticsearch-dsl-0.0.4-py27_0 ...
    installing: elasticsearch-py-1.6.0-py27_0 ...
    installing: flask-0.10.1-py27_1 ...
    installing: flask-ldap-login-0.3.1-py27_0 ...
    installing: flask-login-0.2.11-py27_0 ...
    installing: flask-oauthlib-0.3.4-py27_0 ...
    installing: flask-wtf-0.11-py27_0 ...
    installing: gevent-1.0.2-py27_0 ...
    installing: greenlet-0.4.9-py27_0 ...
    installing: grunt-cli-0.1.9-py27_33 ...
    installing: gunicorn-19.1.0-py27_0 ...
    installing: honcho-0.5.0-py27_0 ...
    installing: hoover-0.6.0-py27_41 ...
    installing: itsdangerous-0.24-py27_0 ...
    installing: jinja2-2.8-py27_0 ...
    installing: markdown2-2.3.0-py27_0 ...
    installing: markupsafe-0.23-py27_0 ...
    installing: meld3-1.0.2-py27_0 ...
    installing: mtq-0.6.3-py27_0 ...
    installing: nodejs-0.10.29-1 ...
    installing: oauthlib-0.6.0-py27_55 ...
    installing: openldap-2.4.36-0 ...
    installing: openssl-1.0.1k-1 ...
    installing: paramiko-1.15.3-py27_0 ...
    installing: pastedeploy-1.5.2-py27_1 ...
    installing: pip-7.1.2-py27_0 ...
    installing: pycrypto-2.6.1-py27_0 ...
    installing: pymongo-2.8-py27_0 ...
    installing: python-dateutil-2.4.2-py27_0 ...
    installing: python-ldap-2.4.13-py27_0 ...
    installing: pytz-2015.6-py27_0 ...
    installing: pyyaml-3.11-py27_1 ...
    installing: readline-6.2-2 ...
    installing: requests-2.8.1-py27_0 ...
    installing: ruby-2.1.1-py27_3 ...
    installing: setuptools-18.4-py27_0 ...
    installing: six-1.10.0-py27_0 ...
    installing: sqlite-3.8.4.1-1 ...
    installing: stripe-1.25.0-py27_0 ...
    installing: supervisor-we-3.0b2-py27_44 ...
    installing: tk-8.5.18-0 ...
    installing: urllib3-1.11-py27_0 ...
    installing: wakari-docs-0.9.1-6_g31a4000 ...
    installing: wakari-enterprise-server-conf-1.8.3-26 ...
    Backing up the nginx conf files in /etc/nginx/conf.d/
    nginx conf files moved to /etc/nginx/conf.d.backup/
    Backing up the Elasticsearch conf files in /etc/elasticsearch
    installing: wakari-frontend-1.2.0-0_gc21106c ...
    installing: wakari-server-1.9.2-5_ga75d324 ...
    installing: wakari-version-0.9.1-py27_0 ...
    installing: werkzeug-0.10.4-py27_0 ...
    installing: wheel-0.26.0-py27_1 ...
    installing: wtforms-2.0.2-py27_0 ...
    installing: yaml-0.1.6-0 ...
    installing: zlib-1.2.8-0 ...
    Checking server name
    Loading config from /opt/wakari/wakari-server/etc/wakari/config.json
    Loading config from /opt/wakari/wakari-server/etc/wakari/wk-server-config.json


    ===================================

    Created password 'ZZCcR3lMrO4=' for user 'wakari'

    ===================================


    Starting Wakari daemons...
    installation finished.

*Note: you may be prompted to update ``/root/.bashrc``: for this
particular install, the update is not needed, so please enter ``no``*

After successfully completing the installation script, the installer
will create the administrator account (user name ``wakari``) and assign
it a password (excerpt from above):

::

    Created password 'ZZCcR3lMrO4=' for user 'wakari'

**Record this password.** This is the administrative password referred
to above as ``<AEN_PASSWORD>``. It will be needed in the following
steps. Do not copy the quotes surrounding the password. It is also
available in the installation log file found at
``/tmp/wakari_server.log``.

Post-Install Requirements
-------------------------

Start ElasticSearch
~~~~~~~~~~~~~~~~~~~

The installation of AEN Server has created a new configuration file for
elasticsearch. You must start elasticsearch now to load the new
configuration file.

::

    sudo service elasticsearch start

Test the AEN Server install
~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, take note of the IP address from the table at the top, labeled
here as ``<AEN_SERVER_IP>``.

Use that IP address, in a web-browser, to visit
``http://<AEN_SERVER_IP>``.

Because you have not yet uploaded a license, you will see a message
indicating that you have an expired license. This lets you know that the
program is installed successfully.

Update the License
~~~~~~~~~~~~~~~~~~

From the license expired page. Follow the onscreen instructions and
upload your license file. After submitting, you should see the login
page.

AEN Gateway
===========

The gateway is a reverse proxy that authenticates users and
automatically directs them to the proper AEN Compute machine for their
project.

Users will not notice this component as it automatically (re)routes
them.

AEN Gateway Installation
------------------------

Setup Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The AEN Gateway must be made aware of the AEN Server IP address. And the
install process must be made aware of the AEN Gateway IP and port
number. The AEN Gateway must also register with the AEN Server and will
need , which is the password generated during the server installation.

::

    export AEN_SERVER=<AEN_SERVER_IP>
    export AEN_GATEWAY_PORT=8089
    export AEN_GATEWAY=<AEN_GATEWAY_IP>
    export AEN_PASSWORD=<AEN_PASSWORD>

*Note: you can use FQDN or the IP address, but you must be consistent
and use only one or the other*

Install ``aen-gateway``
~~~~~~~~~~~~~~~~~~~~~~~

Ensure that the install scripts have execute permissions set:

::

    chmod a+x aen-*.sh

Execute the gateway installation script using ``sudo``:

::

    sudo -E ./aen-gateway-4.0.0-Linux-x86_64.sh -w $AEN_SERVER

The result will be the output you see below. You must agree to the
license first. Hit spacebar to page through the license and type yes to
accept the terms.

::

    <snip>  License Text </snip>
    ...
    ...
    Do you approve the license terms? [yes|no]
    [no] >>> yes
    PREFIX=/opt/wakari/wakari-gateway
    Logging to /tmp/wakari_gateway.log
    Checking server name
    Installing miniconda
    installing: python-2.7.10-1 ...
    Python 2.7.10 :: Continuum Analytics, Inc.
    installing: distribute-0.6.45-py27_1 ...
    installing: meld3-1.0.2-py27_0 ...
    installing: nodejs-0.10.29-1 ...
    installing: openssl-1.0.1k-1 ...
    installing: pip-7.1.2-py27_0 ...
    installing: readline-6.2-2 ...
    installing: setuptools-18.4-py27_0 ...
    installing: sqlite-3.8.4.1-1 ...
    installing: supervisor-we-3.0b2-py27_44 ...
    installing: tk-8.5.18-0 ...
    installing: wakari-enterprise-gateway-conf-1.5.4-6 ...
    installing: wakari-gateway-1.5.3-1_g6549a44 ...
    installing: wakari-version-0.9.1-py27_0 ...
    installing: wheel-0.26.0-py27_1 ...
    installing: zlib-1.2.8-0 ...
    Checking server name
    Please restart the Gateway  after running the following command to connect this Gateway to the Wakari Server

    PATH=/opt/wakari/wakari-gateway/bin:$PATH /opt/wakari/wakari-gateway/bin/wk-gateway-configure --server http://54.173.136.7 --host 172.31.57.216 --port 8088 --name Gateway --protocol http --summary Gateway --username wakari --password password

    (replace 'password' with the password of the wakari user that was generated during server installation)
    The start the Wakari-gateway using: sudo service wakari-gateway start

Notes: \* you may be prompted to update ``/root/.bashrc``: for this
particular install, the update is not needed, so please enter ``no``

Post-Install Requirements
-------------------------

Register the AEN Gateway
~~~~~~~~~~~~~~~~~~~~~~~~

The AEN Gateway needs to register with the AEN Server.

-  This needs to be authenticated, so use the wakari user's credentials
   automatically created during the AEN Server install.
-  This needs to be run as root to write the configuration file:
   ``/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json``.

::

    /opt/wakari/wakari-gateway/bin/wk-gateway-configure --server http://$AEN_SERVER --host $AEN_GATEWAY --port $AEN_GATEWAY_PORT --name Gateway --protocol http --summary Gateway --username wakari --password $AEN_PASSWORD || echo "You forgot to use the password or another failure happened"

Change the ownership of the config file to the user named ``wakari``:

::

    sudo chown wakari:wakari /opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json

Start the gateway to load the new configuration file

::

    sudo service wakari-gateway start

Verify the AEN Gateway has Registered
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Login to the AEN Server using Chrome or Firefox browser using the
   admin user account ``wakari``.
#. Click the Admin link in the toolbar
#. Click the Gateway (aka "Datacenter") sub-section and then click your
   Gateway:
#. Verify that your Gateway is registered and looks like the following:
   status = ok.

AEN Compute
===========

AEN Compute Overview
--------------------

AEN Compute instances are where projects are stored and run. Adding
multiple AEN Compute nodes allows one to scale-out horizontally to
increase capacity. Projects can be created on each compute node to
spread the load.

AEN Compute Pre-requisites
--------------------------

Log in for install host(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Log in to the host where you want to install AEN Compute.

-  You will need root or sudo privileges.
-  It can be the same host as used to install AEN Gateway.
-  If you want to install 5 compute nodes, on 5 different host machines,
   you have to repeat the follow steps 5 times, logging into 5 different
   hosts.

Disk Space for Anaconda Distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each AEN Compute install will include the installation of a custom
version of the Anaconda python distribution, approximately the same size
as the normal version, which requires ~ **1 GB in disk-space** per each
AEN Compute instance.

This custom version differs from the normal Anaconda distribution in
several ways, but most importantly:

-  Removal of some unused packages
-  Addition a custom version of the Jupyter Notebook which supports
   implementation of SSL, so that the notebooks can use ``https``
   instead of ``http``.

Git for Notebook Version Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Anaconda Enterprise Notebooks can provide version control and tracking
for Jupyter Notebooks. This is done with the use of Git.

In order to do so, every AEN Compute Node must have Git installed, which
is available from ``http://git-scm.com/`` and can usually be installed
via the package manager for the host operating system upon which AEN
Compute is installed, for example:

::

    yum install git

X Windows for Plotting
~~~~~~~~~~~~~~~~~~~~~~

Finally, if you are using CentOS as your host operating system, in order
to able to successfully generate plots in a notebook using the R kernel,
you will need to have installed X Windows:

::

    yum groupinstall "X Window System"

If the plots are not working after the installation of this group
dependency, you should check that you have installed the following
additional dependencies:

Plotting Dependencies:

-  ``libXrender``
-  ``libXext``
-  ``libSM``

AEN Compute Installation
------------------------

Setup Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set the environment variable that defines the IP address (or FQDN) or
the AEN Server:

::

    export AEN_SERVER=<AEN_SERVER_IP>  # <from table above>

Install ``aen-compute``
~~~~~~~~~~~~~~~~~~~~~~~

Ensure that the install scripts have execute permissions set:

::

    chmod a+x aen-*.sh

Execute the appropriate installation script using ``sudo``:

::

    sudo -E ./aen-compute-4.0.0-Linux-x86_64.sh -w $AEN_SERVER

The result will be the output you see below. You must agree to the
license first. Hit spacebar to page through the license and type yes to
accept the terms.

::

    <snip>  License Text </snip>
    ...
    ...
    Do you approve the license terms? [yes|no]
    [no] >>> yes
    PREFIX=/opt/wakari/wakari-compute
    Logging to /tmp/wakari_compute.log
    Checking server name
    Installing Anaconda
    creating anaconda condarc
    installing: python-2.7.10-1 ...
    Python 2.7.10 :: Continuum Analytics, Inc.
    installing: argh-0.26.1-py27_0 ...
    installing: bleach-1.4.2-py27_0 ...
    installing: coffee-script-1.7.1-1 ...
    installing: conda-api-1.1.0-py27_0 ...
    installing: decorator-4.0.4-py27_0 ...
    installing: distribute-0.6.45-py27_1 ...
    installing: flask-0.10.1-py27_1 ...
    installing: freetype-2.5.2-2 ...
    installing: futures-3.0.3-py27_0 ...
    installing: gateone-master-py27_2 ...
    installing: gmp-4.3.2-0 ...
    installing: html5lib-0.999-py27_0 ...
    installing: ipykernel-4.1.0-py27_0 ...
    installing: ipyparallel-4.0.2-py27_0 ...
    installing: ipython-4.0.0-py27_0 ...
    installing: ipython-we-4.0.4-py27_2_gb521e5a ...
    installing: ipython_genutils-0.1.0-py27_0 ...
    installing: ipywidgets-4.0.3-py27_0 ...
    installing: itsdangerous-0.24-py27_0 ...
    installing: jinja2-2.8-py27_0 ...
    installing: jpeg-8d-0 ...
    installing: jsonpointer-1.4-py27_0 ...
    installing: jsonschema-2.4.0-py27_0 ...
    installing: jupyter_client-4.1.1-py27_0 ...
    installing: jupyter_core-4.0.6-py27_0 ...
    installing: lcms-1.19-0 ...
    installing: libffi-3.0.13-2 ...
    installing: libpng-1.6.17-0 ...
    installing: libsodium-0.4.5-0 ...
    installing: markupsafe-0.23-py27_0 ...
    installing: mathjax-2.2-py27_0 ...
    installing: meld3-1.0.2-py27_0 ...
    installing: mistune-0.7.1-py27_0 ...
    installing: nbconvert-4.0.0-py27_0 ...
    installing: nbformat-4.0.1-py27_0 ...
    installing: nodejs-0.10.29-1 ...
    installing: notebook-4.0.4-py27_0 ...
    installing: openssl-1.0.1k-1 ...
    installing: pandoc-1.12.3-3 ...
    installing: path.py-8.1.2-py27_0 ...
    installing: pathtools-0.1.2-py27_0 ...
    installing: pexpect-3.3-py27_0 ...
    installing: pickleshare-0.5-py27_0 ...
    installing: pil-1.1.7-py27_2 ...
    installing: pip-7.1.2-py27_0 ...
    installing: ptyprocess-0.4-py27_0 ...
    installing: pygments-2.0.2-py27_0 ...
    installing: pylibacl-0.5.3-py27_0 ...
    installing: pyyaml-3.11-py27_1 ...
    installing: pyzmq-14.7.0-py27_0 ...
    installing: readline-6.2-2 ...
    installing: requests-2.8.1-py27_0 ...
    installing: setuptools-18.4-py27_0 ...
    installing: simplegeneric-0.8.1-py27_0 ...
    installing: six-1.10.0-py27_0 ...
    installing: sqlite-3.8.4.1-1 ...
    installing: ssl_match_hostname-3.4.0.2-py27_0 ...
    installing: supervisor-we-3.0b2-py27_44 ...
    installing: terminado-0.5-py27_0 ...
    installing: tk-8.5.18-0 ...
    installing: tornado-4.0.2-py27_0 ...
    installing: traitlets-4.0.0-py27_0 ...
    installing: wakari-app-gateone-1.0.2-1_g6dd5cdd ...
    installing: wakari-app-terminal-1.2.1-20_gdf3bb1a ...
    installing: wakari-app-viewer-1.1.2-0_g884a2af ...
    installing: wakari-app-workbench-1.3.2-py27_150 ...
    installing: wakari-compute-launcher-1.5.0-0_gaa0a2d7 ...
    installing: wakari-enterprise-compute-conf-1.4.3-8 ...

    Wakari will create projects in the /projects directory.
    Creating the /projects directory.
    /projects directory created.
    installing: wakari-indexer-0.1.1-py27_1 ...
    installing: wakari-version-0.9.1-py27_0 ...
    installing: watchdog-0.8.3we-16_g6840bf4 ...
    installing: werkzeug-0.10.4-py27_0 ...
    installing: wheel-0.26.0-py27_1 ...
    installing: yaml-0.1.6-0 ...
    installing: zeromq-4.0.5-0 ...
    installing: zlib-1.2.8-0 ...
    Checking server name
    Initial clone of root environment...
    Starting Wakari daemons...
    installation finished.
    Do you wish the installer to prepend the wakari-compute install location
    to PATH in your /root/.bashrc ? [yes|no]
    [no] >>> yes

    Prepending PATH=/opt/wakari/wakari-compute/bin to PATH in /root/.bashrc
    A backup will be made to: /root/.bashrc-wakari-compute.bak


    For this change to become active, you have to open a new terminal.

    Thank you for installing wakari-compute!

Post-Install Requirements
-------------------------

Once installed, you need to configure the Compute service on AEN Server.
You must repeat this configuration for each compute node/host.

Log in to AEN Server
~~~~~~~~~~~~~~~~~~~~

-  Open a browser on any host that can "see" the AEN Server host on the
   network
-  Point your browser at the AEN Server FQDN or IP address
-  This will load a login page
-  Login as the administrative user ``wakari`` defined above, with
   ``<AEN_PASSWORD>`` generated when installing the AEN Server

Create a New Resource
~~~~~~~~~~~~~~~~~~~~~

Once logged into the AEN Server with the web browser interface:

-  Click on the ``Admin`` tab/link in the top navigation bar
-  This will take you to the ``Admin`` page, then
-  Scroll down to the bottom and look for the ``Providers`` block in the
   left column.
-  In the ``Providers`` section, Click on ``Enterprise Resources`` in
   the left navigation bar
-  This takes you to the ``Resources`` page
-  Click on ``Add Resource`` button (green button in top right corner)
-  Now fill out the resource details

   -  Select the correct (probably the only) *Gateway* to associate this
      *Compute* Node with
   -  For URL, enter the ``http://<AEN_COMPUTE_IP>:5002``. If the
      *Compute* service is located on the same box as the *Gateway*, we
      recommend using ``http://localhost:5002`` for the URL value.
   -  Add a ``Name`` and ``Description`` for the compute node

-  Now to finalize, click on ``Add Resource`` button (this time, the
   green button in bottom right corner)

*Note: for this resource configuration to work, port 5002 on the AEN
Compute host must be open and not blocked from access via the AEN
Gateway host*

**Congratulations! You've now successfully installed and configured
Anaconda Enterprise Notebooks.**

Optional Configuration
======================

Optional Configuration Overview
-------------------------------

There are additional, optional capabilities which are not required but
which you may decide you need. Herein are instructions for
configurations needed to enable additional features.

Optional: Configure Anaconda Enterprise Notebooks to use a local Anaconda Repository
------------------------------------------------------------------------------------

This integrates AEN with a local onsite Anaconda Repository instance
rather than ``Anaconda.org``.

Configure ``.condarc``
~~~~~~~~~~~~~~~~~~~~~~

::

    #/opt/wakari/anaconda/.condarc
    channels:
        - defaults

    create_default_packages:
        - anaconda-client
        - python
        - ipython-we
        - pip

    # Default channels is needed for when users override the system .condarc
    # with ~/.condarc.  This ensures that "defaults" maps to your Anaconda Repository and not
    # repo.continuum.io
    default_channels:
        - http://<your Anaconda Repository name:8080/conda/anaconda
        - http://<your Anaconda Repository name:8080/conda/wakari
        - http://<your Anaconda Repository name:8080/conda/anaconda-cluster
        - http://<your Anaconda Repository name:8080/conda/r-channel

    # Note:  You must add the "conda" subdirectory to the end
    channel_alias: http://<your Anaconda Repository name:8080/conda

Optional: Configure common AEN Compute options
----------------------------------------------

To make any of the changes described below, please edit the following file:
``/opt/wakari/wakari-compute/etc/wakari/wk-compute-launcher-config.json``

Then restart the AEN Compute service::

    sudo service wakari-compute restart

Change the project directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To make ``aen-compute`` service use a different directory than ``/projects``
for storing the projects, modify the configuration file referenced above as follows::

    "projectRoot" : "/nfs/storage/services/wakari/projects",

The directory ``/nfs/storage/services/wakari/projects`` specified as
``projectRoot`` above must exist for this to succeed.

Create groups with the same id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Additionally, if the ``/projects`` folder resides on an NFSv3 volume and
you have a setup with several compute nodes, AEN will create local users
with a different uid on each node.

To make the AEN Compute service create groups with the same id, edit the
configuration file referenced above so that it contains the key ``identicalGID``
and the value ``true`` as in the following example. If you don't see the
``identicalGID`` key, add it, and notice that you must add a comma at the
beginning of the line.
If you add this line as the last key, remove any comma at the end of the line.

::

    , "identicalGID": true

Use numeric usernames
~~~~~~~~~~~~~~~~~~~~~

To use numeric usernames, you must modify the configuration file
referenced above so that it contains the key ``numericUsernames`` and the value
``true`` as in the following example. If you don't see the ``numericUsernames``
key, add it, and notice that you must add a comma at the beginning of the line.
If you add this line as the last key, remove any comma at the end of the line.

::

    , "numericUsernames": true


Optional: Enabling Search Indexing
----------------------------------

Verify that the AEN Compute node can communicate with the AEN Server.
This is required for search indexing to work correctly.

::

    curl -m 5 $AEN_SERVER > /dev/null

Ensure that there are sufficient ``inotify`` watches available for the
number of subdirectories within the project root filesystem. Some Linux
distributions default to a low number of watches, which may prevent the
search indexer from monitoring project directories for changes.

::

    cat /proc/sys/fs/inotify/max_user_watches

If necessary, this can be increased with the following command:

::

    echo fs.inotify.max_user_watches=100000 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Ensure that there are sufficient ``inotify`` user instances available,
at least one per project.

::

    cat /proc/sys/fs/inotify/max_user_instances

If necessary, this can be increased with the following command:

::

    echo fs.inotify.max_user_instances=1000 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Optional: Setting up a Default Project Environment
--------------------------------------------------

Anaconda Enterprise Notebooks includes a full installation of the
Anaconda python distribution, along with several additional packages,
located in the ``root`` conda environment in the path
``/opt/wakari/anaconda``. A copy of this environment is created for each
new AEN Project.

To configure a different set of packages as the defaults, create a new
conda environment in the directory
``/opt/wakari/anaconda/envs/default``. For example, to do so using a
python 3.4 base environment, run the following command:

::

    sudo -u wakari /opt/wakari/anaconda/bin/conda create -p /opt/wakari/anaconda/envs/default python=3.4

Then use ``conda`` to install any additional packages into the
environment as needed. After creating the environment, clone it once to
ensure that it works correctly:

::

    sudo -u wakari /opt/wakari/anaconda/bin/conda create -p /opt/wakari/testenv --clone /opt/wakari/anaconda/envs/default
    sudo -u wakari rm -rf /opt/wakari/testenv

The default project environment will be cloned into the project
workspace the first time the project is started. To convert an existing
project, run the following command to clone the environment, replacing
``/projects/owner/project/envs/<ENV_NAME>`` with the path to the new
environment you would like to create within the project:

::

    sudo -u wakari /opt/wakari/anaconda/bin/conda create -n /projects/owner/project/envs/<ENV_NAME> --clone /opt/wakari/anaconda/envs/default

Then open the Compute Resource Config for the project and set the
project environment path there.

Configure a remote mongodb
--------------------------

First you will need to stop the AEN Server, AEN Gateway and AEN compute:

::

    sudo service wakari-server stop
    sudo service wakari-gateway stop
    sudo service wakari-compute stop

Now, in order to configure a remote database to work with
**AEN-Server**, you will need to edit
``/opt/wakari/wakari-server/etc/wakari/config.json``, create a new key
called ``MONGO_URL`` and as a value you will need to add the database
information. The final file should look like:

::

    {
      "MONGO_URL": "mongodb://MONGO-USER:MONGO-PASSWORD@MONGO-URL:MONGO-PORT",
      "WAKARI_SERVER": "http://YOUR-IP",
      "USE_SES": false,
      "CDN": "http://YOUR-UP/static/",
      "ANON_USER": "anonymous"
    }

You can migrate the data from the former database into the new one,
there is a guide about this in the `MongoDB documentation
website <https://docs.mongodb.com/manual/tutorial/backup-and-restore-tools/>`_.
Once the migration has been performed you can start back the services
with:

::

    sudo service wakari-server start
    sudo service wakari-gateway start
    sudo service wakari-compute start

Optional Configuration: SELinux Enforcing Mode
==============================================

In order to run SELinux in Enforcing mode, there are a few ports that
must be set which can be done using the ``semanage port`` command.

The semange command relies on ``policycoreutils-python``. To install (if
needed):

::

    sudo yum -y install policycoreutils-python

Enable port 5000 for core aen-server:

::

    sudo semanage port -m -t http_port_t -p tcp 5000

The ``-m`` flag is for modifying an existing usage of a port. If you get
an error ``Port tcp/5000 is not defined`` change the flag to ``-a`` to
add the port.

Enable ports 9200 and 9300 for elasticsearch:

::

    sudo semanage port -a -t http_port_t -p tcp 9200
    sudo semanage port -a -t http_port_t -p tcp 9300

Please see the :doc:`Administrative documentation <../admin/index>` for
additional information.

Wrapping Up
===========

Congratulations. You now have a fully installed Anaconda Enterprise
Notebooks system!

For additional documentation on topics such as creating user accounts
and instructions of users who wish to use the system for collaborative
analysis, please see other documentation resources.

Should you encounter any issues while installing AEN or have additional
questions, please do not hesitate to contact your enterprise support
representative.
