.. _manual-configuration:

Configuring falcon
==================

Falcon has several options that can be configured through a configuration file
that is written in YAML format. By default, Falcon will look for a
configuration file in the $HOME/.falcon folder and if this file does
not exist, a new one will be created with default values. A configuration file path
can also be specified on the command line (see :ref:`usage`).

The configuration file has a number of sections with configurable options.
An example configuration file is shown below:

.. code-block:: yaml

   debug:
     enabled: false
   testing:
      enabled: false
   graph:
     autostart: false
     file: ""
   network:
     port: 5555
   logging:
     path: "./"
     screen:
       enabled: true
     cloud:
       enabled: true
       port: 5556
   server_side_storage:
     environment: "./"
     resources: installation path /share/resources  # default path

network
.......

Falcon communicates with clients over a network connection. In the network
section you can set the *port* that Falcon uses for this communication.

graph
.....

You can specify a graph definition *file* that is loaded when Falcon is
started. If a graph file is also specified separately on the command line,
then this will override the configured file. If you would like Falcon to
automatically start execution of the processing graph (without the user having
to manually start execution by pressing a key), then set the *autostart*
option to true.

logging
.......

Falcon provides information about its operation through log messages that are
saved to a file on disk, shown on screen and broadcast over the network to
clients. Use the *path* option to specify the path where the log file should
be saved. You can enable/disable logging to screen and network by setting the
screen.enabled and cloud.enabled properties to true/false. For logging to the
cloud, you can additionally set the network *port*.

server side storage
...................

To refer to paths and resources on the computer that runs Falcon, users can
configure a mapping between URIs (uniform resource identifiers) and paths.
Falcon defines a number of URIs mostly for internal use, including the top
level path for storing data generated by individual processors (set by the
*environment* option) and the top level path for resources such as digital
filter definitions and example graph definitions (set by the *resources*
option).

.. warning:: About the resource server side storage, each extensions will also contained a resource folder with filter definition, graph definitions... etc.

    During the build of the app, these resources are gathered and copied in the build folder, then in the
    installation folder (if make install). Falcon will automatically generate the resource path.
    Be careful if it is override in the config file, Falcon will lose access to this resource folder.

Users can also specify custom URIs that point to paths on the computer running
Falcon. In the *server_side_storage* section of the configuration, the
*custom* option can be set to a map that links a URI to a path.

For example based on the example below, a file example.txt in the folder "/path/to/user/location" can be reach in falcon
by using "mypath://example.txt".

.. code-block:: yaml

   server_side_storage:
     environment: "./"                   # Where to store the output data
     resources: "/"          # Build path where resource from extensions are stored  (filter definitions, graph definitions...)
     custom:
       mypath: "/path/to/user/location"

All path should be an existing path.