5.7. Configuration

5.7.1. Resource mode

A resource mode is a predifined set of settings for various resources directories, such as cubes, instances, etc. to ease development with the framework. There are two running modes with CubicWeb:

• ‘user’, resources are searched / created in the user home directory:

  • instances are stored in ~/etc/cubicweb.d
  • temporary files (such as pid file) in /tmp

• ‘system’, resources are searched / created in the system directories (eg usually requiring root access):

  • instances are stored in <INSTALL_PREFIX>/etc/cubicweb.d
  • temporary files (such as pid file) in /var/run/cubicweb

  where <INSTALL_PREFIX> is the detected installation prefix (‘/usr/local’ for instance).

Notice that each resource path may be explicitly set using an environment variable if the default doesn’t suit your needs. Here are the default resource directories that are affected according to mode:

• ‘system’:

  CW_INSTANCES_DIR = <INSTALL_PREFIX>/etc/cubicweb.d/
  CW_INSTANCES_DATA_DIR = /var/lib/cubicweb/instances/
  CW_RUNTIME_DIR = /var/run/cubicweb/

• ‘user’:

  CW_INSTANCES_DIR = ~/etc/cubicweb.d/
  CW_INSTANCES_DATA_DIR = ~/etc/cubicweb.d/
  CW_RUNTIME_DIR = /tmp

Cubes search path is also affected, see the :ref:Cube section.

By default, the mode automatically set to ‘user’ if a .hg directory is found in the cubicweb package, else it’s set to ‘system’. You can force this by setting the CW_MODE environment variable to either ‘user’ or ‘system’ so you can easily:

• use system wide installation but user specific instances and all, without root privileges on the system (export CW_MODE=user)
• use local checkout of cubicweb on system wide instances (requires root privileges on the system (export CW_MODE=system)

If you’ve a doubt about the mode you’re currently running, check the first line outputed by the cubicweb-ctl list command.

Also, if cubicweb is a mercurial checkout located in <CW_SOFTWARE_ROOT>:

• main cubes directory is <CW_SOFTWARE_ROOT>/../cubes. You can specify another one with CW_INSTANCES_DIR environment variable or simply add some other directories by using CW_CUBES_PATH
• cubicweb migration files are searched in <CW_SOFTWARE_ROOT>/misc/migration instead of <INSTALL_PREFIX>/share/cubicweb/migration/.

5.7.2. Environment configuration

5.7.2.1. Python

If you installed CubicWeb by cloning the Mercurial forest or from source distribution, then you will need to update the environment variable PYTHONPATH by adding the path to the forest cubicweb:

Add the following lines to either .bashrc or .bash_profile to configure your development environment

export PYTHONPATH=/full/path/to/cubicweb-forest

If you installed CubicWeb with packages, no configuration is required and your new cubes will be placed in /usr/share/cubicweb/cubes and your instances will be placed in /etc/cubicweb.d.

5.7.2.2. CubicWeb

Here are all environment variables that may be used to configure CubicWeb:

CW_MODE

Resource mode: user or system, as explained in Resource mode.

CW_CUBES_PATH

Augments the default search path for cubes. You may specify several directories using ‘:’ as separator (‘;’ under windows environment).

CW_INSTANCES_DIR

Directory where cubicweb instances will be found.

CW_INSTANCES_DATA_DIR

Directory where cubicweb instances data will be written (backup file...)

CW_RUNTIME_DIR

Directory where pid files will be written

class cubicweb.cwconfig.CubicWebConfiguration(appid, debugmode=False)

base class for cubicweb server and web configurations

add_cubes(cubes)

add given cubes to the list of used cubes

available_languages(*args)

return available translation for an instance, by looking for compiled catalog

take *args to be usable as a vocabulary method

check_writeable_uid_directory(path)

check given directory path exists, belongs to the user running the server process and is writeable.

If not, try to fix this, letting exception propagate when not possible.

classmethod config_for(appid, config=None, debugmode=False)

return a configuration instance for the given instance identifier

cubes()

return the list of cubes used by this instance

result is ordered from the top level cubes to inner dependencies cubes

cubes_path()

return the list of path to cubes used by this instance, from outer most to inner most cubes

default_instance_id()

return the instance identifier, useful for option which need this as default value

default_log_file()

return default path to the log file of the instance’server

default_pid_file()

return default path to the pid file of the instance’server

init_log(logthreshold=None, force=False)

init the log service

classmethod instance_home(appid)

return the home directory of the instance with the given instance id

classmethod instances_dir()

return the control directory

load_configuration()

load instance’s configuration files

main_config_file()

return instance’s control configuration file

migration_handler()

return a migration handler instance

classmethod migration_scripts_dir()

cubicweb migration scripts directory

classmethod possible_configurations(appid)

return the name of possible configurations for the given instance id

save()

write down current configuration

sendmails(msgs)

msgs: list of 2-uple (message object, recipients). Return False if connection to the smtp server failed, else True.

vregistry_path()

return a list of files or directories where the registry will look for application objects

class cubicweb.cwconfig.CubicWebNoAppConfiguration(debugmode=False)

base class for cubicweb configuration without a specific instance directory

classmethod build_vregistry_path(templpath, evobjpath=None, tvobjpath=None)

given a list of directories, return a list of sub files and directories that should be loaded by the instance objects registry.

Parameters:

• evobjpath – optional list of sub-directories (or files without the .py ext) of the cubicweb library that should be tested and added to the output list if they exists. If not give, default to cubicweb_appobject_path class attribute.
• tvobjpath – optional list of sub-directories (or files without the .py ext) of directories given in templpath that should be tested and added to the output list if they exists. If not give, default to cube_appobject_path class attribute.

classmethod cls_adjust_sys_path()

update python path if necessary

classmethod critical(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

classmethod cube_dependencies(cube)

return cubicweb cubes used by the given cube

classmethod cube_dir(cube)

return the cube directory for the given cube id, raise ConfigurationError if it doesn’t exists

classmethod cube_migration_scripts_dir(cube)

cube migration scripts directory

classmethod cube_pkginfo(cube)

return the information module for the given cube

classmethod cube_recommends(cube)

return cubicweb cubes recommended by the given cube

classmethod cube_version(cube)

return the version of the cube located in the given directory

classmethod cubes_search_path()

return the path of directories where cubes should be searched

static cubicweb_version()

return installed cubicweb version

classmethod debug(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

default_instance_id()

return the instance identifier, useful for option which need this as default value

classmethod error(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

classmethod exception(msg, *args)

Convenience method for logging an ERROR with exception information.

classmethod expand_cubes(cubes, with_recommends=False)

expand the given list of top level cubes used by adding recursivly each cube dependencies

classmethod i18n_lib_dir()

return instance’s i18n directory

classmethod info(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

classmethod init_available_cubes()

cubes may register some sources (svnfile for instance) in their __init__ file, so they should be loaded early in the startup process

init_log(logthreshold=None, logfile=None, syslog=False)

init the log service

load_site_cubicweb(paths=None)

load instance’s specific site_cubicweb file

classmethod reorder_cubes(cubes)

reorder cubes from the top level cubes to inner dependencies cubes

classmethod shared_dir()

return the shared data directory (i.e. directory where standard library views and data may be found)

vregistry_path()

return a list of files or directories where the registry will look for application objects. By default return nothing in NoApp config.

classmethod warning(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)

cubicweb.cwconfig.configuration_cls(name)

return the configuration class registered with the given name

cubicweb.cwconfig.guess_configuration(directory)

try to guess the configuration to use for a directory. If multiple configurations are found, ConfigurationError is raised

cubicweb.cwconfig.instance_configuration

return a configuration instance for the given instance identifier

class cubicweb.cwconfig.metaconfiguration

metaclass to automaticaly register configuration

cubicweb.cwconfig.possible_configurations(directory)

return a list of installed configurations in a directory according to *-ctl files