.. _wconfiguration:

Configuration
*************
    
A warsa configuration file is useful and sometimes also necessary. Downloads of global data (precipitation, climate, digital elevation models, etc.) require a target directory on your computer and sometimes also a user name and password. The configuration file ``~/.configs/.warsa.cfg`` defines where on your computer you will save global data, as well as, if necessary, user names and passwords from servers you download from. We show below how to create a config file. The file will be located in the directory .configs in your home directory (symbolized by ~). Here some examples:

    * in linux: `/home/MYNAME/.configs/.warsa.cfg`
    * in windows: `C:/users/MYNAME/.configs/.warsa.cfg`

Note that your computer may be configured to hide files and directories starting with "." (dot). If you want to see the directory ``~/.configs`` and the configuration file ``.warsa.cfg``, make them visible (see `windows <https://support.microsoft.com/en-us/help/14201/windows-show-hidden-files>`_ and `linux <https://askubuntu.com/questions/232649/how-to-show-a-hidden-files>`_).

The file ``~/.configs/.warsa.cfg`` must be created only once and remains the same until you change or delete it.


Creating the configuration file
===============================

In order to create the configuration file ``~/.configs/.warsa.cfg``, the following target directories may be defined:

    - [dem]: set the local directory where digital elevation models are stored
    - [grp]: set the local directory where global rainfall (precipitation) products are stored

The examples below assumes you are registered:

    * for gpm: https://registration.pps.eosdis.nasa.gov/registration/
..    * for srtm: https://urs.earthdata.nasa.gov/users/new
    
Example in windows:

.. code-block:: python

	dem = 'D:/dem'
	grp = 'D:/sarp'
	gpm_usr = 'my_gpm_user'
	gpm_pwd = 'my_gpm_passsword'
..	earthdata_usr = 'my_earthdata_usr'
..	earthdata_pwd = 'my_earthdata_pwd'


Example in linux (external disk mounted as '/media/myname/SARP):

.. code-block:: python

	dem = '/media/myname/SARP/dem'
	grp = '/media/myname/SARP/sarp'
	gpm_usr = 'my_gpm_user'
	gpm_pwd = 'my_gpm_passsword'
..	earthdata_usr = 'my_earthdata_usr'
..	earthdata_pwd = 'my_earthdata_pwd'

Creating the config file:

.. code-block:: python

	create_config(dem=dem, grp=grp, gpm_usr=gpm_usr, gpm_pwd=gpm_pwd)
..				  earthdata_usr=earthdata_usr, earthdata_pwd=earthdata_pwd,

You should now find ``.configs/.warsa.cfg`` in your home directory.

An example of a generated config file will be::

	[grp]
	dir = /media/roehrig/SARP/sarp

	[gpm]
	usr = gAAAAABcs0WIQlrvwB0mhZFz7ojRpGZ_bdVrjdlyuihYUI9JfoHP4ceCJxn43PETH5tZ-Aq2VGgAEEIteAvcNuHYeZkSB0fz4oEXVQkBRzMnhUHvTqxiKdg=
	pwd = gAAAAABcs0WI0cSe10H2cC4f-TqoX11iU6Ic6bZYw3qscMPQj9uY1iIs5OL2lXzM533xsiUgN5bmQfTAHqyyJhw2Qz_iylor287hAb4D6-Gfh2nNpcMgk6M=

	[dem]
	dir = /media/roehrig/SARP/dem

User names and passwords in ``~/.configs/.warsa.cfg`` are encrypted in order to diminish the risk other persons accidentally read them (see gpm/usr and gpm/pwd). Encryption requires a security key, which is automatically created under ``~/.warsa_key``. 

Example of the content of ``~/.warsa_key`` (your automatically generated content will be different)::

    F4haaSKj2Jlgc-_ZdD6gtVa_dIsmy1KMsAxXYEZJylI=