.. _configuration_chapter:
Configuring :program:`Yith Library Server`
==========================================
How the configuration is read
-----------------------------
:program:`Yith Library Server` read its configuration options from
two different sources:
- A configuration file with a INI syntax
- Environment variables. This work for many options but not all of them.
If an option is defined both in the configuration file and an
environment variable, :program:`Yith Library Server` will use the
value of the environment variable.
:program:`Yith Library Server` comes with two configuration
templates, one for development and one for production purposes.
You should copy one of these templates instead of editing them
because that would make the upgrade process easier. These templates
are located inside the :file:`config-templates` directory of the
main ``yithlibraryserver`` Python package.
The development template is named :file:`development.ini` and the
production template is named :file:`production.ini`. These templates
have plenty of comments so it should not be very hard to get
started with them.
Once you have your configuration options established in a
configuration file you can run :program:`Yith Library Server`
using the following command:
.. code-block:: text
pserve configuration_file.ini
Starting server in PID 6743.
serving on http://0.0.0.0:6543
Configuration options
---------------------
Authentication
~~~~~~~~~~~~~~
:program:`Yith Library Server` uses a secret value to sign the
authentication ticket cookie, which is used to keep track of the
authentication status of the current user.
It is extremely important that **this value is kept secret**. This
is a required value with an empty default value. This means that
you need to set it before running the server. The
:file:`development.ini` template has a value of ``1234`` for this
option so you can get your server running as fast as possible
without worrying about these things.
.. code-block:: ini
auth_tk_secret = komb81v1mi1t9fsia9q22sg3wobylz88
In this example, the auth_tk_secret value has been generated
with the following command in a Unix shell:
.. code-block:: text
$ tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' /dev/null;echo
You can also set this option with an environment variable:
.. code-block:: bash
$ export AUTH_TK_SECRET=komb81v1mi1t9fsia9q22sg3wobylz88
Available languages
~~~~~~~~~~~~~~~~~~~
This option defines the set of available languages that
:program:`Yith Library Server` will use for internationalization
purposes. The value is a space delimited list of iso codes.
.. code-block:: ini
available_languages = en es
The default value for this option is ``en es``, which means
there is support for English and Spanish.
As of this writing only English and Spanish translation of UI
text messages are available. With this configuration option
you can restrict the set of available languages but it you add
new languages to it, their translatation catalogs will not be
generated magically.
This option does not have a environment variable. You can only
set it with a configuration file.
CORS support
~~~~~~~~~~~~
:abbr:`CORS (Cross-Origin resource sharing)` is useful when a browser
based client wants to communicate with :program:`Yith Library Server`.
Using this setting you can define a whitelist of allowed hosts to
whom you want to allow access from the server.
The syntax is a space separated list of URLs:
.. code-block:: ini
cors_allowed_origins = http://localhost https://localhost
Note that if you want to allow access from HTTP and HTTPS both
URLs need to be defined.
You can also set this option with an environment variable:
.. code-block:: bash
$ export CORS_ALLOWED_ORIGINS="http://localhost https://localhost"
The default value for this option is the empty list.
Database
~~~~~~~~
Chaging this setting you can customize your database location and
access settings.
The syntax is defined in MongoDB reference documentation as the
`Connection String URI Format `_
.. code-block:: ini
mongo_uri = mongodb://localhost:27017/yith-library
You can also set this option with an environment variable:
.. code-block:: bash
$ export MONGO_URI=mongodb://localhost:27017/yith-library
The default value for this option is ``mongodb://localhost:27017/yith-library``
Facebook authentication
~~~~~~~~~~~~~~~~~~~~~~~
You can configure support for Facebook authentication in
:program:`Yith Library Server` by defining several settings. If you
do so, your users will be able to access your server authenticating
themselves via Facebook.
But first you need to create a Facebook application at
https://developers.facebook.com/apps . The type of Facebook application
is **Website with Facebook Login** and you need to enter your server
URL, e.g. http://localhost:65432/
After you have created and configured the Facebook application you
are ready to fill the settings in :program:`Yith Library Server`.
The first setting is ``facebook_app_id`` and is a number you can
obtain from your App summary page at Facebook.
.. code-block:: ini
facebook_app_id = 123456789012345
Then, there is ``facebook_app_secret`` which is the secret part of
Facebook client credentials. You can also obtain it from your
App summary page at Facebook.
.. code-block:: ini
facebook_app_secret = 1234567890abcdef1234567890abcdef
There are no default values for the settings ``facebook_app_id``
and ``facebook_app_secret``. If they are not set, Facebook
authentication is automatically disabled.
.. warning::
It is perfectly fine to avoid Facebook authentication but it is
actually required to enable at least one of the supported
authentication mechanisms (Facebook, Google, Twitter or Persona).
Otherwise your users won't be able to access your server.
There are three more Facebook settings that are used to perform the
actual authentication but they have good default values and you
should only need to change them if Facebook itself changes them.
These are the settings and their default values:
.. code-block:: ini
facebook_dialog_oauth_url = https://www.facebook.com/dialog/oauth/
facebook_access_token_url = https://graph.facebook.com/oauth/access_token
facebook_basic_information_url = https://graph.facebook.com/me
You can also set these options with environment variables:
.. code-block:: bash
$ export FACEBOOK_APP_ID="123456789012345"
$ export FACEBOOK_APP_SECRET="1234567890abcdef1234567890abcdef"
$ export FACEBOOK_DIALOG_OAUTH_URL="https://www.facebook.com/dialog/oauth/"
$ export FACEBOOK_ACCESS_TOKEN_URL="https://graph.facebook.com/oauth/access_token"
$ export FACEBOOK_BASIC_INFORMATION_URL="https://graph.facebook.com/me"
Google Analytics support
~~~~~~~~~~~~~~~~~~~~~~~~
This is an optional settings to enable Google Analytics in
:program:`Yith Library Server`. Before you configure it you have
to add your server URL into
`Google Analytics `_ and obtain
the code they give you to add the Javascript snippet.
After that, you are ready to configure this setting:
.. code-block:: ini
google_analytis_code = UA-12345678-2
You can also set this option with an environment variable:
.. code-block:: bash
$ export GOOGLE_ANALYTICS_CODE="UA-12345678-2"
There is no default value for this setting. If unset, the Javascript
snippet for Google Analytics will not be rendered in the final HTML
of your server.
Google authentication
~~~~~~~~~~~~~~~~~~~~~
You can configure support for Google authentication in
:program:`Yith Library Server` by defining several settings. If you
do so, your users will be able to access your server authenticating
themselves via Google.
But first you need to create a Google application at
https://code.google.com/apis/console?hl=es#access . Your need to
enter the Redirect URI and the Javascript origin. If your server is
located at http://localhost:65432/ then that is the value for the
Javascript origin and your redirect URI would be
http://localhost:65432/google/callback
After you have created and configured the Google application you
are ready to fill the settings in :program:`Yith Library Server`.
The first setting is ``facebook_client_id`` and is a number you can
obtain from your API Access page at Google.
.. code-block:: ini
google_client_id = 123456789012.apps.googleusercontent.com
Then, there is ``google_client_secret`` which is the secret part of
Google client credentials. You can also obtain it from your
API Access page at Google.
.. code-block:: ini
google_client_secret = 1234567890abcdefghijklmn
There are no default values for the settings ``google_client_id``
and ``google_client_secret``. If they are not set, Google
authentication is automatically disabled.
.. warning::
It is perfectly fine to avoid Google authentication but it is
actually required to enable at least one of the supported
authentication mechanisms (Facebook, Google, Twitter or Persona).
Otherwise your users won't be able to access your server.
There are three more Google settings that are used to perform the
actual authentication but they have good default values and you
should only need to change them if Google itself changes them.
These are the settings and their default values:
.. code-block:: ini
google_auth_uri = https://accounts.google.com/o/oauth2/auth
google_token_uri = https://accounts.google.com/o/oauth2/token
google_user_info_uri = https://www.googleapis.com/oauth2/v1/userinfo
You can also set these options with environment variables:
.. code-block:: bash
$ export GOOGLE_CLIENT_ID="123456789012.apps.googleusercontent.com"
$ export GOOGLE_CLIENT_SECRET="1234567890abcdefghijklmn"
$ export GOOGLE_AUTH_URI="https://accounts.google.com/o/oauth2/auth"
$ export GOOGLE_TOKEN_URI="https://accounts.google.com/o/oauth2/token"
$ export GOOGLE_USER_INFO_URI="https://www.googleapis.com/oauth2/v1/userinfo"
.. todo::
Logging
.. todo::
Mail
Persona authentication
~~~~~~~~~~~~~~~~~~~~~~
You can configure support for Mozilla Persona authentication in
:program:`Yith Library Server` by defining several settings. If you
do so, your users will be able to access your server authenticating
themselves via Persona.
The first setting is ``persona_audience`` and it should be the full
URL of your server, including the port.
.. code-block:: ini
persona_audience = http://localhost:80
There are no default value for the¡s setting. If it is not set,
Persona authentication is automatically disabled.
.. warning::
It is perfectly fine to avoid Persona authentication but it is
actually required to enable at least one of the supported
authentication mechanisms (Facebook, Google, Twitter or Persona).
Otherwise your users won't be able to access your server.
There is one more Persona seetting that is used to verify the
assertion that Persona sends to :program:`Yith Library Server`.
It has a good default value and you should only need to change
it if Persona itself change it:
.. code-block:: ini
persona_verifier_url = https://verifier.login.persona.org/verify
You can also set these options with environment variables:
.. code-block:: bash
$ export PERSONA_AUDIENCE="http://localhost:80"
$ export PERSONA_VERIFIER_URL="https://verifier.login.persona.org/verify"
.. todo::
Sessions
Twitter authentication
~~~~~~~~~~~~~~~~~~~~~~
You can configure support for Twitter authentication in
:program:`Yith Library Server` by defining several settings. If you
do so, your users will be able to access your server authenticating
themselves via Twitter.
But first you need to create a Twitter application at
https://dev.twitter.com/apps/new . Your need to
enter the Website and Callback URL. If your server is
located at http://localhost:65432/ then that is the value for the
Website your redirect URI would be http://localhost:65432/twitter/callback
After you have created and configured the Twitter application you
are ready to fill the settings in :program:`Yith Library Server`.
The first setting is ``twitter_consumer_key`` and is a string you can
obtain from your App page at Twitter.
.. code-block:: ini
twitter_consumer_key = 1234567890abcdefghij
Then, there is ``twitter_consumer_secret`` which is the secret part of
Twitter client credentials. You can also obtain it from your
App page at Twitter.
.. code-block:: ini
twitter_consumer_secret = 1234567890abcdefghijklmnopqrstuvwxyzABCDE
There are no default values for the settings ``twitter_consumer_key``
and ``twitter_consumer_secret``. If they are not set, Twitter
authentication is automatically disabled.
.. warning::
It is perfectly fine to avoid Twitter authentication but it is
actually required to enable at least one of the supported
authentication mechanisms (Facebook, Google, Twitter or Persona).
Otherwise your users won't be able to access your server.
There are three more Twitter settings that are used to perform the
actual authentication but they have good default values and you
should only need to change them if Twitter itself changes them.
These are the settings and their default values:
.. code-block:: ini
twitter_request_token_url = https://api.twitter.com/oauth/request_token
twitter_authenticate_url = https://api.twitter.com/oauth/authenticate
twitter_access_token_url = https://api.twitter.com/oauth/access_token
You can also set these options with environment variables:
.. code-block:: bash
$ export TWITTER_CONSUMER_KEY="1234567890abcdefghij"
$ export TWITTER_CONSUMER_SECRET="1234567890abcdefghijklmnopqrstuvwxyzABCDE"
$ export TWITTER_REQUEST_TOKEN_URL="https://api.twitter.com/oauth/request_token"
$ export TWITTER_AUTHENTICATE_URL="https://api.twitter.com/oauth/authenticate"
$ export TWITTER_ACCESS_TOKEN_URL="https://api.twitter.com/oauth/access_token"