.. _installation_customization: Customization with INI File =========================== You can customize your installation with the ``development.ini`` and ``agent_development.ini`` files or the ``production.ini`` file whether you are under development or in production. Here are parameters you can tune. .. ............................................................................ [app:PubliForge] Section ------------------------ Instance defintion `````````````````` .. code-block:: ini [app:PubliForge] uid = pfinstance encryption = secretkey This option is required and the ``uid`` must be unique. ``encryption`` is used to encrypt Beaker session cookie, to hash user password or to encrypt VCS password. Internationalization ```````````````````` .. code-block:: ini [app:PubliForge] languages = fr, es, en #pyramid.default_locale_name = en #translation_dirs = custom:Locale Optional options are: * ``languages``: a comma separated list of a ISO 639 available languages. Each language must be one of the following values: ``en``, ``fr`` or ``es``. Default: ``en``. * ``pyramid.default_locale_name``: this value supplies the default locale name. It must be one of the language list. Default: ``en``. * ``translation_dirs``: a comma separated list of translation directory paths. Each item can be an absolute directory path (e.g. ``/home/pfinstance/PubliForge/Locale``) or an asset specification (e.g. ``custom:Locale``). Debug Mode `````````` .. code-block:: ini [app:PubliForge] pyramid.reload_templates = false pyramid.debug_authorization = false pyramid.debug_notfound = false pyramid.debug_routematch = false pyramid.debug_templates = false See `Pyramid documentation `_ for more information. Front: Skin ``````````` .. code-block:: ini [app:PubliForge] #skin.title = PubliForge – PFInstance #skin.static.name = Static2 #skin.static.path = /home/pfinstance/PubliForge/Static #skin.favicon = /Static2/favicon.ico #skin.css.base = #skin.css.login = #skin.css.custom = /Static2/Css/pfinstance.css #skin.template.base = custom:Templates/base.pt #skin.template.login = custom:Templates/login.pt All ``skin.*`` options are optional. * ``skin.title``: main title of HTML pages * ``skin.static.name``: a string representing an application-relative local URL prefix. It may alternately be a full URL. If you use ``Static``, it overrides the standard static path. * ``skin.static.path``: If you define ``skin.static.name``, you have to define ``skin.static.path``. It is the path on disk where the static files reside. This can be absolute paths (e.g. ``/home/pfinstance/PubliForge/Static``) or asset specifications (e.g. ``custom:Static``). * ``skin.favicon``: application-relative local URL to ``favicon.ico``, for instance, ``/Static2/favicon.ico``. * ``skin.css.base``: application-relative local URL to ``base.css``. If defined, it overrides standard base CSS. * ``skin.css.login``: application-relative local URL to ``login.css``. If defined, it overrides standard login page CSS. * ``skin.css.custom``: application-relative local URL to an additional CSS, for instance ``/Static2/Css/pfinstance.css``. * ``skin.template.base``: path or asset to a `Chameleon `_ template to override the standard one. * ``skin.template.login``: path or asset to a `Chameleon `_ template to override the standard one. Front: Temporary Directory `````````````````````````` .. code-block:: ini [app:PubliForge] temporary_dir = %(here)s/Cache/Tmp Front: Beaker cache ``````````````````` .. code-block:: ini [app:PubliForge] #cache.type = file #cache.data_dir = %(here)s/Cache/Beaker/Cache/Data #cache.lock_dir = %(here)s/Cache/Beaker/Cache/Lock All ``cache.*`` options are optional. By default, a memory cache is used. Front: Beaker Session ````````````````````` .. code-block:: ini [app:PubliForge] #session.type = file #session.data_dir = %(here)s/Cache/Beaker/Sessions/Data #session.lock_dir = %(here)s/Cache/Beaker/Sessions/Lock session.key = PF_SESSION Only ``session.key`` is required. By default, memory is used for sessions. Front: SqlAlchemy ````````````````` As `PubliForge` use `SqlAlchemy `_, you can choose the SQL databse you prefer. If you want to use `PostgreSQL `_ (the recommended database), make the following configuration: .. code-block:: ini [app:PubliForge] sqlalchemy.url = postgresql://publiforge:sesame@localhost/PubliForge #sqlalchemy.pool_size = 5 #sqlalchemy.max_overflow = 10 #sqlalchemy.pool_timeout = 30 You can adjust `SqlAlchemy `_ parameters: * ``sqlalchemy.pool_size``: The size of the pool to be maintained, defaults to 5. This is the largest number of connections that will be kept persistently in the pool. * ``sqlalchemy.max_overflow``: The maximum overflow size of the pool. When the number of checked-out connections reaches the size set in ``pool_size``, additional connections will be returned up to this limit. Defaults to 10. * ``sqlalchemy.pool_timeout``: The number of seconds to wait before giving up on returning a connection. Defaults to 30 (30 seconds). * ``sqlalchemy.pool_recycle``: If set to non -1, number of seconds between connection recycling, which means upon checkout, if this timeout is surpassed the connection will be closed and replaced with a newly opened connection. Defaults to -1. If you prefer `MySQL `_, here is the configuration: .. code-block:: ini [app:PubliForge] sqlalchemy.url = mysql://publiforge:sesame@localhost/PubliForge?charset=utf8 sqlalchemy.pool_recycle = 3600 #sqlalchemy.pool_size = 5 #sqlalchemy.max_overflow = 10 #sqlalchemy.pool_timeout = 30 .. For a quick test, you can also use `SQLite `_: .. .. code-block:: ini .. sqlalchemy.url = sqlite:///%(here)s/publiforge.db .. .. caution:: You should not use SQLite in production. Front: Authentification ``````````````````````` .. code-block:: ini [app:PubliForge] auth.cookie = PF_AUTH auth.remember = 5184000 Optional options are: * ``auth.cookie``: the name of the cookie for `remember me` login option. The default value is ``PF_AUTH``. * ``auth.remember``: the time in seconds to for `remember me` login option. The default value is ``5184000`` i.e. 2 months. Front: Page Refresh ``````````````````` .. code-block:: ini [app:PubliForge] #refresh.short = 2 #refresh.long = 5 * ``refresh.short`` is period to refresh page when a simple action is in progress. Default = 2 (2 seconds). * ``refresh.long`` is period to refresh page when a complex action is in progress. Default = 5 (5 seconds). Front: Storages ``````````````` .. code-block:: ini [app:PubliForge] storage.root = %(here)s/Storages storage.index = %(here)s/StoragesIndex storage.vcs = none, local, hg, hgsvn #storage.report_ttl = 120 #storage.cache = 3600 Required options for storages are: * ``storage.root``: full path to root directory for storages. * ``storage.vcs``: comma separated IDs of available VCS (at least one). IDs are selected from the following: ``none`` (no version control system), ``local`` (local Mercurial), ``hg`` (Mercurial), ``hgsvn`` (Subversion via Mercurial), ``svn`` (Subversion). Other available options are: * ``storage.index``: full path to directory for storage indexes. It activates search functionality. * ``storage.report_ttl``: Time to Live in seconds of a report of an action on a storage. Default is 120 (2 minutes). * ``storage.cache``: cache expire time and Time to Live in seconds of Storage Control System session. Default is 3600 (1 hour). Front: Opener ````````````` File *openers* are responsible for the display, the rendering and the edition of specific types of file. `PubliForge` supplies basic openers for plain text files, Web images, INI files and Publidoc/Publiquiz XML files. .. code-block:: ini [app:PubliForge] #opener.develop = false opener.roots = %(here)s/Openers opener.list = Publi*, Ini* opener.cache = %(here)s/Cache/Openers * ``opener.develop``: if ``true``, no optimization occurs during the creation of the cache directory. It is destroyed and created at each use. Default = ``false``. * ``opener.roots``: a comma separated list of opener directories. Each item can be an absolute directory path (e.g. ``%(here)s/Openers``) or an asset specification (e.g. ``custom:Openers``). The default is an empty list. * ``opener.list``: a comma separated list of IDs or patterns to add to available opener list. Openers are used in the order of the list. * ``opener.cache``: a full path to the cache directory for openers. Front: Available Agents ``````````````````````` .. code-block:: ini [app:PubliForge] agent.refresh = 0 agent.synchronize = 1 agent.0.weight = 1 agent.0.password = sesame agent.1.url = http://devel.publiforge.org agent.1.weight = 2 agent.1.password = sesame If you configure a Web site you need at least one active agent. Required option for an agent is: * ``agent..weight``: the higher this number is, the greater the agent accepts processings. If 0, its rejects all requests. Other available options are: * ``agent.refresh``: the period to refresh information about agent. If 0 (default value), information is only read at initialization time. * ``agent.synchronize``: the number of concurrent synchronizations between the front and the agent. The default is 1. * ``agent..url``: URL of the agent. If empty, agent and front are the sames. * ``agent..password``: the password to authenticate with the agent. It is optional but recommended. Front: Processors for Background Job ```````````````````````````````````` A ``background job`` is a processing which is periodically run by a scheduler. To be active, the main PubliForge scheduler must be configurated. See :ref:`installation_deployment_scheduler`. .. code-block:: ini [app:PubliForge] job.processor.roots = %(here)s/Processors job.processor.list = CleanStorage, Publidoc2* * ``job.processor.roots``: a comma separated list of processor directories. Each item can be an absolute directory path (e.g. ``%(here)s/JobProcessors``) or an asset specification (e.g. ``custom:JobProcessors``). The default is an empty list. * ``job.processor.list``: a comma separated list of IDs or patterns to add to available job processor list. Agent: Buildspaces `````````````````` .. code-block:: ini [app:PubliForge] buildspace.root = %(here)s/Buildspaces #buildspace.ttl = 2678400 If your application is only an agent, ``buildspace.root`` is required. It is the place where to copy remote storage data. The default value of its Time To Live (``buildspace.ttl``) is 2678400 (1 month). Agent: Processors ````````````````` .. code-block:: ini [app:PubliForge] processor.roots = %(here)s/Processors processor.list = Publi*, Parallel, CharCount, DTBookValid * ``processor.roots``: a comma separated list of processor directories. Each item can be an absolute directory path (e.g. ``%(here)s/Processors``) or an asset specification (e.g. ``custom:Processors``). The default is an empty list. * ``processor.list``: a comma separated list of IDs or patterns to add to available processor list. There is not default value. Agent: Builds ````````````` .. code-block:: ini #build.reset = false #build.develop = false build.root = %(here)s/Builds #build.ttl = 1800 #build.result_ttl = 604800 #build.concurrent = 3 The required option is ``build.root``, a path to a sand box for builds. Other available options are: * ``build.reset``: if ``true``, the sand box for builds is deleted at each starting up of the server. Default = ``false``. * ``build.develop``: if ``true``, no optimization occurs during the creation of the ``Processor`` directory. It is destroyed and created at each build. Default = ``false``. * ``build.ttl``: Time To Live for a build. Default = 1800 (30 minutes). * ``build.result_ttl``: Time To Live for build result. Default = 604800 (1 week). * ``build.concurrent``: Number of concurrent builds. Default = 3. Agent: Authorized Fronts ```````````````````````` .. code-block:: ini [app:PubliForge] #front.concurrent = 1 front.0.uid = pfinstance front.0.password = sesame front.1.uid = pfdemo front.1.password = sesame ``front.concurrent`` the number of concurrent synchronizations between the agent and the front. The default is 1. At least, one authorized *front* is required. ``front..password`` is the password to authenticate the caller. It is optional but recommended. .. ............................................................................ .. _installation_customization_populate: [Populate] Section ------------------ In the ``Populate`` section, you can define the main administrator, populate your database with other users, storages and projects and retreive storage content from repositories. It is used by :ref:`frontguide_scripts_pfpopulate` to initialize your instance. Database ```````` In development, it's better to destroy the tables at each start up. To do so, add this option: .. code-block:: ini [Populate] drop_tables = true However, it is a bad idea in production. Administrator ````````````` .. code-block:: ini [Populate] # ------ Administrator admin.login = admin admin.password = adminpwd admin.name = Administrator admin.email = admin@prismallia.fr The required options are ``admin.login``, ``admin.password``, ``admin.name`` and ``admin.email``. Other available options are: * ``admin.language``: a ISO 639 value ; the default value if the value of ``pyramid.default_locale_name`` option of ``[app:PubliForge]`` section * ``admin.page_size``: number of lines in a list page, default value is 20 * ``admin.home``: available values are ``site`` (default), ``projects`` and ``storages`` * ``admin.ips``: comma separated IP to restrict access (optional) XML Configuration Files ``````````````````````` .. code-block:: ini [Populate] # ------ Users file.a01 = %(here)s/Configuration/Users/users.pfusr.xml file.a02 = %(here)s/Configuration/Users/tests.pfusr.xml file.a03 = %(here)s/Configuration/Users/guests.pfusr.xml # ------ Groups file.b11 = %(here)s/Configuration/Groups/groups_fr.pfgrp.xml file.b12 = %(here)s/Configuration/Groups/sa_gaze.pfgrp.xml # ------ Storages file.c01 = %(here)s/Configuration/Storages/none.pfstg.xml file.c02 = %(here)s/Configuration/Storages/local.pfstg.xml file.c03 = %(here)s/Configuration/Storages/hg.pfstg.xml file.c04 = %(here)s/Configuration/Storages/svn.pfstg.xml # ------ Indexers file.d01 = %(here)s/Configuration/Indexers/publidoc.pfidx.xml # ------ Projects file.e01 = %(here)s/Configuration/Projects/publidoc.pfprj.xml file.e02 = %(here)s/Configuration/Projects/publiquiz.pfprj.xml To known more about XML configuration files, read :ref:`frontguide_scripts_pfpopulate`.