<commit_before>================================
    Setup and Administration
================================

While the :ref:`quickstart` instructions will get you exploring the Tangelo
examples in just two commands, Tangelo has a rich set of configuration options
that can be used to administer Tangelo effectively.  This page will discuss
configuration and deployment strategies, including suggestions for best
practices.

Configuring and Launching Tangelo
=================================

The simplest way to launch a Tangelo server is to use this command: ::

    tangelo

Tangelo's runtime behaviors are specified via configuration file and command
line options.  Tangelo configuration files are INI-style files as read by the
standard Python `ConfigParse
<https://docs.python.org/2/library/configparser.html>`_ module.  These files
consist of one or more `sections`, each of which contains one or more option
settings.  A section begins with the section title, wrapped in square brackets.
Options are given as key-value pairs:  the line starts with the name of the
key, then a colon followed by a space, and then the value.

The example configuration found at
``/usr/share/tangelo/conf/tangelo/local/conf`` reads something like the
following:

.. code-block:: cfg

    [tangelo]
    hostname: 0.0.0.0
    port:     8080

This minimal configuration file specifies that Tangelo should listen on all
interfaces for connections on port 8080.  By contrast, ``tangelo.conf.global``
looks like this:

.. code-block:: cfg

    [tangelo]
    hostname: 0.0.0.0
    port:     80

    user:     nobody
    group:    nobody

This configuration file is meant for the case when Tangelo is to be installed as
a system-level service.  It will run on port 80 (the standard port for an HTTP
server) and, though it will need to be started with superuser privileges, it
will drop those privleges to run as user ``nobody`` in group ``nobody`` to
prevent damage to the system should the process be, e.g., hijacked by an
attacker.

To run Tangelo using a particular configuration file, ``tangelo`` can be invoked
with the ``-c`` or ``--config`` option: ::

    tangelo -c ~/myconfig.json

When the flag is omitted, Tangelo will use default values for all
configuration options (see :ref:`config-options` below).

Finally, all configuration options can also be specified on the command line.
This has the effect of overriding whatever value may be set in the specified
configuration file.  This can be useful for, e.g., using a single configuration
file for multiple Tangelo instances, but varying the port number.

.. _config-options:

Configuration Options
---------------------

The following tables, organized by section title, show what fields can be
included in the configuration file, what they mean, and their default values if
left unspecified.

The **[tangelo]** section contains general server options:

================ =================================================================   =================================
Option           Meaning                                                             Default value
================ =================================================================   =================================
hostname         The hostname interface on which to listen for connections           ``localhost``

port             The port number on which to listen for connections                  ``8080``

root             The path to the directory to be served by Tangelo as the web root   ``/usr/share/tangelo/www`` [#root]_

drop_privileges  Whether to drop privileges when started as the superuser            ``True``

sessions         Wehther to enable server-side session tracking                      ``True``

user             The user account to drop privileges to                              ``nobody`` [#usergroup]_

group            The user group to drop privileges to                                ``nobody`` [#usergroup]_

access_auth      Whether to protect directories containing a ``.htaccess`` file      ``True``

key              The path to the SSL key                                             ``None`` [#https]_ [#unset]_

cert             The path to the SSL certificate                                     ``None`` [#https]_ [#unset]_
================ =================================================================   =================================

The **[vtkpython]** section contains options related to :ref:`vtkweb` integration:

================ =================================================================   =================================
Option           Meaning                                                             Default value
================ =================================================================   =================================
vtkpython        The path to the ``vtkptyhon`` program                               ``None`` [#unset]_
================ =================================================================   =================================

The **[girder]** section contains options related to mounting a Girder API: [#gird]_

================ =================================================================   =================================
Option           Meaning                                                             Default value
================ =================================================================   =================================
host [#girdopt]_ The hostname running Girder                                         ``localhost``

port [#girdopt]_ The port on which the Girder database is running                    ``27017``

path [#girdopt]_ The path on which to mount a Girder API                             ``None`` [#unset]_
================ =================================================================   =================================

.. rubric:: Footnotes

.. [#root] The first component of this path may vary by platform.  Technically,
    the path begins with the Python value stored in ``sys.prefix``; in a Unix
    system, this value is */usr*, yielding the default path shown here.

.. [#usergroup] Your Unix system may already have a user named "nobody" which
    has the least possible level of permissions.  The theory is that system daemons
    can be run as this user, limiting the damage a rogue process can do.  However,
    if multiple daemons are run this way, any rogue daemon can theoretically gain
    control of the others.  Therefore, the recommendation is to create a new user
    named "tangelo", that also has minimal permissions, but is only used to run
    Tangelo in privilege drop mode.

.. [#https] You must also specify both key and cert to serve content over
    https.<commit_msg>Remove mention of vtkpython option to command line Tangelo<commit_after>================================
    Setup and Administration
================================

While the :ref:`quickstart` instructions will get you exploring the Tangelo
examples in just two commands, Tangelo has a rich set of configuration options
that can be used to administer Tangelo effectively.  This page will discuss
configuration and deployment strategies, including suggestions for best
practices.

Configuring and Launching Tangelo
=================================

The simplest way to launch a Tangelo server is to use this command: ::

    tangelo

Tangelo's runtime behaviors are specified via configuration file and command
line options.  Tangelo configuration files are INI-style files as read by the
standard Python `ConfigParse
<https://docs.python.org/2/library/configparser.html>`_ module.  These files
consist of one or more `sections`, each of which contains one or more option
settings.  A section begins with the section title, wrapped in square brackets.
Options are given as key-value pairs:  the line starts with the name of the
key, then a colon followed by a space, and then the value.

The example configuration found at
``/usr/share/tangelo/conf/tangelo/local/conf`` reads something like the
following:

.. code-block:: cfg

    [tangelo]
    hostname: 0.0.0.0
    port:     8080

This minimal configuration file specifies that Tangelo should listen on all
interfaces for connections on port 8080.  By contrast, ``tangelo.conf.global``
looks like this:

.. code-block:: cfg

    [tangelo]
    hostname: 0.0.0.0
    port:     80

    user:     nobody
    group:    nobody

This configuration file is meant for the case when Tangelo is to be installed as
a system-level service.  It will run on port 80 (the standard port for an HTTP
server) and, though it will need to be started with superuser privileges, it
will drop those privleges to run as user ``nobody`` in group ``nobody`` to
prevent damage to the system should the process be, e.g., hijacked by an
attacker.

To run Tangelo using a particular configuration file, ``tangelo`` can be invoked
with the ``-c`` or ``--config`` option: ::

    tangelo -c ~/myconfig.json

When the flag is omitted, Tangelo will use default values for all
configuration options (see :ref:`config-options` below).

Finally, all configuration options can also be specified on the command line.
This has the effect of overriding whatever value may be set in the specified
configuration file.  This can be useful for, e.g., using a single configuration
file for multiple Tangelo instances, but varying the port number.

.. _config-options:

Configuration Options
---------------------

The following tables, organized by section title, show what fields can be
included in the configuration file, what they mean, and their default values if
left unspecified.

The **[tangelo]** section contains general server options:

================ =================================================================   =================================
Option           Meaning                                                             Default value
================ =================================================================   =================================
hostname         The hostname interface on which to listen for connections           ``localhost``

port             The port number on which to listen for connections                  ``8080``

root             The path to the directory to be served by Tangelo as the web root   ``/usr/share/tangelo/www`` [#root]_

drop_privileges  Whether to drop privileges when started as the superuser            ``True``

sessions         Wehther to enable server-side session tracking                      ``True``

user             The user account to drop privileges to                              ``nobody`` [#usergroup]_

group            The user group to drop privileges to                                ``nobody`` [#usergroup]_

access_auth      Whether to protect directories containing a ``.htaccess`` file      ``True``

key              The path to the SSL key                                             ``None`` [#https]_ [#unset]_

cert             The path to the SSL certificate                                     ``None`` [#https]_ [#unset]_
================ =================================================================   =================================

The **[girder]** section contains options related to mounting a Girder API: [#gird]_

================ =================================================================   =================================
Option           Meaning                                                             Default value
================ =================================================================   =================================
host [#girdopt]_ The hostname running Girder                                         ``localhost``

port [#girdopt]_ The port on which the Girder database is running                    ``27017``

path [#girdopt]_ The path on which to mount a Girder API                             ``None`` [#unset]_
================ =================================================================   =================================

.. rubric:: Footnotes

.. [#root] The first component of this path may vary by platform.  Technically,
    the path begins with the Python value stored in ``sys.prefix``; in a Unix
    system, this value is */usr*, yielding the default path shown here.

.. [#usergroup] Your Unix system may already have a user named "nobody" which
    has the least possible level of permissions.  The theory is that system daemons
    can be run as this user, limiting the damage a rogue process can do.  However,
    if multiple daemons are run this way, any rogue daemon can theoretically gain
    control of the others.  Therefore, the recommendation is to create a new user
    named "tangelo", that also has minimal permissions, but is only used to run
    Tangelo in privilege drop mode.

.. [#https] You must also specify both key and cert to serve content over
    https.
{'fraction_non_alphanumeric': 0.20114321025799475, 'fraction_numerical': 0.004634636181059787, 'mean_word_length': 3.0855159356263804, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 26, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1402543', 'n_tokens_mistral': 2942, 'n_tokens_neox': 2692, 'n_words': 1405}