6. 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].”

Note

At runtime, configuration options can be overriden by environments variables which name follows the option name with - replaced by _ and a CW_ prefix. For instance CW_BASE_URL=https://www.example.com would override the base-url configuration option.

6.1. 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

6.1.1. 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).

6.2. 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

6.3. 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

6.4. 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)

6.5. Configuring logging

main.log-threshold:
 level of filtering messages (DEBUG, INFO, WARNING, ERROR)
main.log-file:file to write messages

6.6. 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

6.7. 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.

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)