6. Configure an instance#

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

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

For example:


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


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


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.


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

6.2. Setting up the web client#


regular expression matching sites which could be “embedded” in the site (controllers ‘embed’)


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

6.3. RQL server configuration#


host name if it can not be detected correctly


file where will be written the server pid


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


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


SMTP server username for authenticated email sending


SMTP server password for authenticated email sending


name to use for outgoing mail of the instance


address for outgoing mail of the instance


value of the header X-CW for outgoing mails 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)


destination addresses of e-mails of supervision (separated by commas)

6.5. Configuring logging#


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


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.


Character encoding to use for the web


number of characters for “short” display


maximum number of entities to show per results page


number of related entities to show up on primary entity view


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’s support for the CORS protocol is provided by the wsgicors middleware at the Pyramid level. 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.

A few parameters can be set to configure the CORS capabilities of CubicWeb, the values are passed to the wsgicors.CORS() middleware constructor, hence the wsgicors documentation can be used for more details.


comma-separated list of allowed origin domains or “*” for any domain


comma-separated list of allowed HTTP methods


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


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


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

credentials is always set to true and is not configurable.