[doc] fix link to setup info in README
... and fix URL to the repository's gpg key.
.. -*- coding: utf-8 -*-
Configure an instance
=====================
While creating an instance, a configuration file is generated in::
$ (CW_INSTANCES_DIR) / <instance> / <configuration name>.conf
For example::
/etc/cubicweb.d/myblog/all-in-one.conf
It is a simple text file in the INI format
(http://en.wikipedia.org/wiki/INI_file). In the following description,
each option name is prefixed with its own section and followed by its
default value if necessary, e.g. "`<section>.<option>` [value]."
.. _`WebServerConfig`:
Configuring the Web server
--------------------------
:`web.auth-model` [cookie]:
authentication mode, cookie or http
:`web.realm`:
realm of the instance in http authentication mode
:`web.http-session-time` [0]:
period of inactivity of an HTTP session before it closes automatically.
Duration in seconds, 0 meaning no expiration (or more exactly at the
closing of the browser client)
:`main.anonymous-user`, `main.anonymous-password`:
login and password to use to connect to the RQL server with
HTTP anonymous connection. CWUser account should exist.
:`main.base-url`:
url base site to be used to generate the urls of web pages
Https configuration
```````````````````
It is possible to make a site accessible for anonymous http connections
and https for authenticated users. This requires to
use apache (for example) for redirection and the variable `main.https-url`
of configuration file.
For this to work you have to activate the following apache modules :
* rewrite
* proxy
* http_proxy
The command on Debian based systems for that is ::
a2enmod rewrite http_proxy proxy
/etc/init.d/apache2 restart
:Example:
For an apache redirection of a site accessible via `http://localhost/demo`
and `https://localhost/demo` and actually running on port 8080, it
takes to the http:::
ProxyPreserveHost On
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/demo
RewriteRule ^/demo$ /demo/
RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]
and for the https:::
ProxyPreserveHost On
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/ demo
RewriteRule ^/demo$/demo/
RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]
and we will file in the all-in-one.conf of the instance:::
base-url = http://localhost/demo
https-url = https://localhost/demo
Notice that if you simply want a site accessible through https, not *both* http
and https, simply set `base-url` to the https url and the first section into your
apache configuration (as you would have to do for an http configuration with an
apache front-end).
Setting up the web client
-------------------------
:`web.embed-allowed`:
regular expression matching sites which could be "embedded" in
the site (controllers 'embed')
:`web.submit-url`:
url where the bugs encountered in the instance can be mailed to
RQL server configuration
------------------------
:`main.host`:
host name if it can not be detected correctly
:`main.pid-file`:
file where will be written the server pid
:`main.uid`:
user account to use for launching the server when it is
root launched by init
:`main.session-time [30*60]`:
timeout of a RQL session
:`main.query-log-file`:
file where all requests RQL executed by the server are written
Configuring e-mail
------------------
RQL and web server side:
:`email.mangle-mails [no]`:
indicates whether the email addresses must be displayed as is or
transformed
RQL server side:
:`email.smtp-host [mail]`:
hostname hosting the SMTP server to use for outgoing mail
:`email.smtp-port [25]`:
SMTP server port to use for outgoing mail
:`email.sender-name`:
name to use for outgoing mail of the instance
:`email.sender-addr`:
address for outgoing mail of the instance
:`email.default dest-addrs`:
destination addresses by default, if used by the configuration of the
dissemination of the model (separated by commas)
:`email.supervising-addrs`:
destination addresses of e-mails of supervision (separated by
commas)
Configuring logging
-------------------
:`main.log-threshold`:
level of filtering messages (DEBUG, INFO, WARNING, ERROR)
:`main.log-file`:
file to write messages
.. _PersistentProperties:
Configuring persistent properties
---------------------------------
Other configuration settings are in the form of entities `CWProperty`
in the database. It must be edited via the web interface or by
RQL queries.
:`ui.encoding`:
Character encoding to use for the web
:`navigation.short-line-size`:
number of characters for "short" display
:`navigation.page-size`:
maximum number of entities to show per results page
:`navigation.related-limit`:
number of related entities to show up on primary entity view
:`navigation.combobox-limit`:
number of entities unrelated to show up on the drop-down lists of
the sight on an editing entity view
Cross-Origin Resource Sharing
-----------------------------
CubicWeb provides some support for the CORS_ protocol. For now, the
provided implementation only deals with access to a CubicWeb instance
as a whole. Support for a finer granularity may be considered in the
future.
Specificities of the provided implementation:
- ``Access-Control-Allow-Credentials`` is always true
- ``Access-Control-Allow-Origin`` header in response will never be
``*``
- ``Access-Control-Expose-Headers`` can be configured globally (see below)
- ``Access-Control-Max-Age`` can be configured globally (see below)
- ``Access-Control-Allow-Methods`` can be configured globally (see below)
- ``Access-Control-Allow-Headers`` can be configured globally (see below)
A few parameters can be set to configure the CORS_ capabilities of CubicWeb.
.. _CORS: http://www.w3.org/TR/cors/
:`access-control-allow-origin`:
comma-separated list of allowed origin domains or "*" for any domain
:`access-control-allow-methods`:
comma-separated list of allowed HTTP methods
:`access-control-max-age`:
maximum age of cross-origin resource sharing (in seconds)
:`access-control-allow-headers`:
comma-separated list of allowed HTTP custom headers (used in simple requests)
:`access-control-expose-headers`:
comma-separated list of allowed HTTP custom headers (used in preflight requests)