INSTALL

Installing the Pan Galactic Engineering Framework (pangalactic)
===============================================================

Platform Notes
--------------

* The pangalactic Desktop Client (``pangalaxian.py``) should run on any
  OS for which its dependencies can be installed; it has been tested on Windows
  10, Linux (mainly Ubuntu), and OSX.

* The Virtual Galactic Engineering Repository (``vger.py``) server is only
  supported on Linux.  For details on installing and running the server, either
  using Docker or standalone, see the ``pangalactic.vger`` package --
  specifically, the README files:

    - ``pangalactic.vger/README``
    - ``pangalactic.vger/docker/README``

-------------------------------------------------------------------------------


Dependencies
------------

pangalactic depends on several libraries and other applications.  This section
specifies the software required and where to obtain it.

All of the following software is free and open source.

NOTE:  Use of the "conda" package manager is *strongly* recommended.  The
recommended practice is to install "Miniforge"
(https://conda-forge.org/miniforge/), which will set up the `conda` package
manager and a minimal set of associated libraries, then use `conda` to install
the dependencies listed below.

(0) Python requirements:

    - Python 3.12 (3.9 - 3.11 *might* work but are not guaranteed)

          Configuration:  Python has binary installers for several platforms
          and can also be compiled and installed from source, but the
          recommended practice is to use the Python binary that Miniforge
          installs.  Be sure to install it configured with SSL support, as this
          is used by pangalactic (see instructions included with the Python
          distribution -- if you install from source, OpenSSL is required).

(1) pangalactic.core (base package of pangalactic)

    (1.1) Put the following channels in your '.condarc' file
          (NOTE: DO *NOT* use the "default" channel):

          channels:
            - conda-forge

    (1.2) Install the following dependencies of pangalactic.core:

    - pint
      Units and quantities

          Configuration:  'conda install pint'

    - pydispatch
      Python application event signals

          Configuration:  'conda install pydispatch'

    - python-dateutil
      Date utilities

          Configuration:  'conda install python-dateutil'

    - pytz (latest released version)
      Correct timezones implementation

          Configuration:  'conda install pytz'

    - rdflib (version 3.0.0 or greater)
      <http://rdflib.net/>

          Configuration:  'conda install rdflib'

    - ruamel_yaml <=0.15
      * NOTE: the pin to under 0.15 is recommended by the package for
        "production" use (possibly unstable API changes) currently, this
        results in conda installing version 0.11.14

          Configuration:  'conda install ruamel_yaml'

    - SqlAlchemy
      <http://www.sqlalchemy.org>
      NOTE: version 2.0 and later broke compatibility

          Configuration:  'conda install sqlalchemy=1.4'

    - tzlocal (latest released version)
      Local timezones implementation
      * NOTE: is in the conda-forge channel

          Configuration:  'conda install tzlocal'

    - xlrd
      Reads .xls files

          Configuration:  'conda install xlrd'

    - xlsxwriter (latest released version)
      Writes .xlsx files

          Configuration:  'conda install xlsxwriter'

    - xlwt
      Writes .xls files

          Configuration:  'conda install xlwt'

    - openpyxl (latest released version)
      Reads .xlsx files

          Configuration:  'conda install openpyxl'


(2) pangalactic.node (the pangalactic GUI client package):

    Install the following dependencies of pangalactic.node:

    - autobahn

          Configuration:  'conda install autobahn'

    - Twisted
      Asynchronous networking framework
      <http://twistedmatrix.com>
      NOTE:  autobahn can be used with asyncio or twisted -- pangalactic uses
      it with twisted.

          Configuration:  'conda install twisted'

    - PyNaCl
      Cryptography library required for autobahn to be able to use
      WAMP-Cryptosign (public key authentication).

          Configuration:  'conda install pynacl'

    - binaryornot (conda-forge)
      Detects whether a file is binary, and certain types of files

          Configuration:  'conda install binaryornot'

    - pyqt
      * NOTE: this will install PyQt5 (pangalactic.node is not yet compatible
        with PyQt6)

          Configuration:  'conda install pyqt'

    - pythonqwt
      Graphing package for pyqt apps, used for the mission concept modeler
      module, 'conops'.

          Configuration:  'conda install pythonqwt'

    - qt5reactor
      Integration of twisted reactor with PyQt5 event loop

          Configuration:  'conda install qt5reactor'

    - pythonocc-core
      (for CAD viewer functionality)

          Configuration: 'conda install pythonocc-core'

    - Twisted
      Asynchronous networking framework
      <http://twistedmatrix.com>
      NOTE:  autobahn can be used with asyncio or twisted -- pangalactic uses
      it with twisted.

          Configuration:  'conda install twisted'

    - websocket-client
      (Checks status of server when logging in to repository)

          Configuration: 'conda install websocket-client'


(3) Required for pangalactic.vger (repository service):

    The items in (1) *plus* the following packages ...

    - autobahn

          Configuration:  'conda install autobahn'

    - Twisted
      Asynchronous networking framework
      <http://twistedmatrix.com>
      NOTE:  autobahn can be used with asyncio or twisted -- pangalactic uses
      it with twisted.

          Configuration:  'conda install twisted'

    - PyNaCl
      Cryptography library required for autobahn to be able to use
      WAMP-Cryptosign (public key authentication).

          Configuration:  'conda install pynacl'

    - PostgreSQL 7.4.x or later
      <http://www.ca.postgresql.org>

          Configuration:  'conda install postgresql'

          Configuration Options:  see PostgreSQL documentation for detailed
          instructions.  Since PostgreSQL will only be accessed internally
          to the VGER server, security will be significantly improved on
          platforms that support unix domain sockets by setting the
          PostgreSQL server to listen on a unix domain socket.

          *** IMPORTANT:  when running initdb, set environment variables
          ``LC_COLLATE`` and ``LC_CTYPE`` to ``C``, so that PostgreSQL will be
          able to use its indexes in LIKE and regexp queries (see the
          PostgreSQL admin docs for more info).

    - psycopg2 (latest version)
      <http://initd.org/pub/software/psycopg/>
      (Note:  current development is using psycopg2-2.9.9)

          Configuration:  'conda install psycopg2'

    - python-ldap
      [to enable LDAP searches of enterprise directories, as part of
      administration of users]

        Configuration: 'conda install python-ldap'

---------------------------------------------------------------------------