.. Installation Guide

==================
Installation Guide
==================

This guide provides instructions for you to get L7\|ESP installed and running on your server. Be aware that **installation requires a basic knowledge of command line operations in Unix/Linux**.

L7\|ESP Quick Installation
==========================

.. note:: **Requirements:** Linux (x86_64 architecture) + container runtime (e.g. `Docker Engine <https://docs.docker.com/engine/install/#server>`_).

#. Connect to the L7\|ESP container registry on Docker Hub with credentials provided by L7 Informatics:

    .. code-block:: none

        $ docker login

#. Run a container from L7\|ESP image, while providing an initial administrator password and exposing the HTTP port on the host machine (TCP 8002):

    .. code-block:: none

        $ docker run \
            --env L7ESP_PASSWORD=<password> \
            --name server \
            --publish 8002:8002 \
            --volume ./data:/opt/l7esp/data \
            l7esp/server:3.0.0

#. Wait for the L7\|ESP services to start up and stabilize.

    .. code-block:: none

        $ docker exec server l7 status

#. Verify L7\|ESP is running. The following command should return ``PASS``.

    .. code-block:: none

        $ curl --fail http://localhost:8002/health
        PASS

#. Finally, verify that you are able to log in with your web browser:

    .. figure:: images/login.png
        :width: 303px
        :height: 385px
        :align: center
        :alt: log in credentials image

        L7|ESP Login Page

    **Credentials:**

    - URL: `http://localhost:8002/login <http://localhost:8002/login>`_
    - Email: ``admin@localhost``
    - Password: (supplied above as ``L7ESP_PASSWORD`` environment variable)

.. note:: If you encounter problems with the L7\|ESP installation process, please contact us at support@l7informatics.com.

L7\|ESP Directories
===================

Directory Hierarchy
-------------------

The L7\|ESP directory hierarchy is as follows:

::

    /opt/l7esp/
        data/
            conf/
            database/
            log/
            pipeline/
            run/
            site_id.txt
        server/
            bin/
            doc/
            lab7/
            lib/
            support/
            sys/
            tools/


Data Directories
----------------

The ``/opt/l7esp/data/conf`` directory contains the configuration files for the L7 Informatics System Services. The ``/opt/l7esp/data/conf/lab7.conf`` file contains configuration information for the L7 Informatics web server and system services. The ``/opt/l7esp/data/conf/postgresql.conf`` file contains configuration information used by the PostgreSQL database server.

An individual with the **Admin Role** may edit these files to customize the L7\|ESP installation. After editing, L7\|ESP should be restarted by running ``l7 stop`` then ``l7 start`` from the container image.

The ``/opt/l7esp/data/database`` directory is reserved for the PostgreSQL database tables and files. **Please do not modify these files.**

The ``/opt/l7esp/data/log`` directory contains various log files generated by L7\|ESP services, including:

    * ``/opt/l7esp/data/log/db.log``: PostgreSQL database server log
    * ``/opt/l7esp/data/log/supervisord.log``: L7\|ESP system services log
    * ``/opt/l7esp/data/log/l7-esp.http.*.access.log``: L7\|ESP web server access log
    * ``/opt/l7esp/data/log/l7-esp.log``: L7\|ESP web server application and error log

The ``/opt/l7esp/data/pipeline`` and ``/opt/l7esp/data/run`` directories contain various run-time files generated by L7\|ESP system services. **Please do not modify these files.**

*Note:* In order to preserve existing data, the ``/opt/l7esp/data`` directory should *not* be deleted when updating L7\|ESP.


Server Directories
------------------

The ``/opt/l7esp/server`` directory contains the self-contained runtime code for that release of the L7\|ESP software.

::

    /opt/l7esp/
         data/
         server/

The ``/opt/l7esp/server/bin`` directory contains the L7\|ESP command line executables, including the ``l7`` command used to start and stop the L7\|ESP services.

The ``/opt/l7esp/server/doc`` contains HTML documentation for this version of L7\|ESP, which can be accessed by connecting to ``http://localhost:8002/doc/`` with a web browser.

The ``/opt/l7esp/server/lab7``, ``/opt/l7esp/server/lib``, and ``/opt/l7esp/server/sys`` directories contain various files needed to run L7\|ESP. **Please do not modify the files in these subdirectories.**

The ``/opt/l7esp/server/support`` and ``/opt/l7esp/server/tools`` contain various scripts and tools that support advanced features such as instrument integration.