1 .. -*- coding: utf-8 -*-

     2 

     3 

     4 Configure an instance

     5 =====================

     6 

     7 While creating an instance, a configuration file is generated in::

     8 

     9     $ (CW_INSTANCES_DIR) / <instance> / <configuration name>.conf

    10 

    11 For example::

    12 

    13     /etc/cubicweb.d/myblog/all-in-one.conf

    14 

    15 It is a simple text file in the INI format

    16 (http://en.wikipedia.org/wiki/INI_file). In the following description,

    17 each option name is prefixed with its own section and followed by its

    18 default value if necessary, e.g. "`<section>.<option>` [value]."

    19 

    20 .. _`WebServerConfig`:

    21 

    22 Configuring the Web server

    23 --------------------------

    24 :`web.auth-model` [cookie]:

    25     authentication mode, cookie or http

    26 :`web.realm`:

    27     realm of the instance in http authentication mode

    28 :`web.http-session-time` [0]:

    29     period of inactivity of an HTTP session before it closes automatically.

    30     Duration in seconds, 0 meaning no expiration (or more exactly at the

    31     closing of the browser client)

    32 

    33 :`main.anonymous-user`, `main.anonymous-password`:

    34     login and password to use to connect to the RQL server with

    35     HTTP anonymous connection. CWUser account should exist.

    36 

    37 :`main.base-url`:

    38     url base site to be used to generate the urls of web pages

    39 

    40 Https configuration

    41 ```````````````````

    42 It is possible to make a site accessible for anonymous http connections

    43 and https for authenticated users. This requires to

    44 use apache (for example) for redirection and the variable `main.https-url`

    45 of configuration file.

    46 

    47 For this to work you have to activate the following apache modules :

    48 

    49 * rewrite

    50 * proxy

    51 * http_proxy

    52 

    53 The command on Debian based systems for that is ::

    54 

    55   a2enmod rewrite http_proxy proxy

    56   /etc/init.d/apache2 restart

    57 

    58 :Example:

    59 

    60    For an apache redirection of a site accessible via `http://localhost/demo`

    61    and `https://localhost/demo` and actually running on port 8080, it

    62    takes to the http:::

    63 

    64      ProxyPreserveHost On

    65      RewriteEngine On

    66      RewriteCond %{REQUEST_URI} ^/demo

    67      RewriteRule ^/demo$ /demo/

    68      RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]

    69 

    70    and for the https:::

    71 

    72      ProxyPreserveHost On

    73      RewriteEngine On

    74      RewriteCond %{REQUEST_URI} ^/ demo

    75      RewriteRule ^/demo$/demo/

    76      RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]

    77 

    78 

    79    and we will file in the all-in-one.conf of the instance:::

    80 

    81      base-url = http://localhost/demo

    82      https-url = https://localhost/demo

    83 

    84 Notice that if you simply want a site accessible through https, not *both* http

    85 and https, simply set `base-url` to the https url and the first section into your

    86 apache configuration (as you would have to do for an http configuration with an

    87 apache front-end).

    88 

    89 Setting up the web client

    90 -------------------------

    91 :`web.embed-allowed`:

    92     regular expression matching sites which could be "embedded" in

    93     the site (controllers 'embed')

    94 :`web.submit-url`:

    95     url where the bugs encountered in the instance can be mailed to

    96 

    97 

    98 RQL server configuration

    99 ------------------------

   100 :`main.host`:

   101     host name if it can not be detected correctly

   102 :`main.pid-file`:

   103     file where will be written the server pid

   104 :`main.uid`:

   105     user account to use for launching the server when it is

   106     root launched by init

   107 :`main.session-time [30*60]`:

   108     timeout of a RQL session

   109 :`main.query-log-file`:

   110     file where all requests RQL executed by the server are written

   111 

   112 

   113 Configuring e-mail

   114 ------------------

   115 RQL and web server side:

   116 

   117 :`email.mangle-mails [no]`:

   118     indicates whether the email addresses must be displayed as is or

   119     transformed

   120 

   121 RQL server side:

   122 

   123 :`email.smtp-host [mail]`:

   124     hostname hosting the SMTP server to use for outgoing mail

   125 :`email.smtp-port [25]`:

   126     SMTP server port to use for outgoing mail

   127 :`email.sender-name`:

   128     name to use for outgoing mail of the instance

   129 :`email.sender-addr`:

   130     address for outgoing mail of the instance

   131 :`email.default dest-addrs`:

   132     destination addresses by default, if used by the configuration of the

   133     dissemination of the model (separated by commas)

   134 :`email.supervising-addrs`:

   135     destination addresses of e-mails of supervision (separated by

   136     commas)

   137 

   138 

   139 Configuring logging

   140 -------------------

   141 :`main.log-threshold`:

   142     level of filtering messages (DEBUG, INFO, WARNING, ERROR)

   143 :`main.log-file`:

   144     file to write messages

   145 

   146 

   147 .. _PersistentProperties:

   148 

   149 Configuring persistent properties

   150 ---------------------------------

   151 Other configuration settings are in the form of entities `CWProperty`

   152 in the database. It must be edited via the web interface or by

   153 RQL queries.

   154 

   155 :`ui.encoding`:

   156     Character encoding to use for the web

   157 :`navigation.short-line-size`:

   158     number of characters for "short" display

   159 :`navigation.page-size`:

   160     maximum number of entities to show per results page

   161 :`navigation.related-limit`:

   162     number of related entities to show up on primary entity view

   163 :`navigation.combobox-limit`:

   164     number of entities unrelated to show up on the drop-down lists of

   165     the sight on an editing entity view

   166 

   167 Cross-Origin Resource Sharing

   168 -----------------------------

   169 

   170 CubicWeb provides some support for the CORS_ protocol. For now, the

   171 provided implementation only deals with access to a CubicWeb instance

   172 as a whole. Support for a finer granularity may be considered in the

   173 future.

   174 

   175 Specificities of the provided implementation:

   176 

   177 - ``Access-Control-Allow-Credentials`` is always true

   178 - ``Access-Control-Allow-Origin`` header in response will never be

   179   ``*``

   180 - ``Access-Control-Expose-Headers`` can be configured globally (see below)

   181 - ``Access-Control-Max-Age`` can be configured globally (see below)

   182 - ``Access-Control-Allow-Methods`` can be configured globally (see below)

   183 - ``Access-Control-Allow-Headers`` can be configured globally (see below)

   184 

   185 

   186 A few parameters can be set to configure the CORS_ capabilities of CubicWeb.

   187 

   188 .. _CORS: http://www.w3.org/TR/cors/

   189 

   190 :`access-control-allow-origin`:

   191    comma-separated list of allowed origin domains or "*" for any domain

   192 :`access-control-allow-methods`:

   193    comma-separated list of allowed HTTP methods

   194 :`access-control-max-age`:

   195    maximum age of cross-origin resource sharing (in seconds)

   196 :`access-control-allow-headers`:

   197    comma-separated list of allowed HTTP custom headers (used in simple requests)

   198 :`access-control-expose-headers`:

   199    comma-separated list of allowed HTTP custom headers (used in preflight requests)

   200