1 # -*- coding: utf-8 -*- |
1 # -*- coding: utf-8 -*- |
2 """common configuration utilities for cubicweb |
2 #:organization: Logilab |
3 |
3 #:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. |
4 :organization: Logilab |
4 #:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr |
5 :copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2. |
5 #:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses |
6 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr |
6 |
7 |
7 # docstring included in doc/book/en/admin/setup.rst |
8 |
8 """ |
9 If cubicweb is a mercurial checkout (eg `CWDEV` is true), located in |
9 .. _ResourceMode: |
10 `CW_SOFTWARE_ROOT`: |
10 |
11 |
11 Resource mode |
12 * main cubes directory is `<CW_SOFTWARE_ROOT>/../cubes`. You can specify |
12 ------------- |
13 another one with `CW_INSTANCES_DIR` environment variable or simply add some |
13 |
14 other directories by using `CW_CUBES_PATH`. |
14 A resource *mode* is a predifined set of settings for various resources |
15 |
15 directories, such as cubes, instances, etc. to ease development with the |
16 * cubicweb migration files are by default searched in |
16 framework. There are two running modes with |cubicweb|: |
17 `<CW_SOFTWARE_ROOT>/misc/migration` instead of |
17 |
18 `/usr/share/cubicweb/migration/`(unless another emplacement is specified |
18 * 'user', resources are searched / created in the user home directory: |
19 using `CW_MIGRATION_DIR`. |
19 |
20 |
20 - instances are stored in :file:`~/etc/cubicweb.d` |
21 * Cubicweb will start in 'user' mode (see below) |
21 - temporary files (such as pid file) in :file:`/tmp` |
22 |
22 |
23 |
23 * 'system', resources are searched / created in the system directories (eg |
24 On startup, Cubicweb is using a specific *mode*. A mode corresponds to some |
24 usually requiring root access): |
25 default setting for various resource directories. There are currently 2 main |
25 |
26 modes : 'system', for system wide installation, and 'user', fur user local |
26 - instances are stored in :file:`<INSTALL_PREFIX>/etc/cubicweb.d` |
27 installation (e.g. no root privileges). |
27 - temporary files (such as pid file) in :file:`/var/run/cubicweb` |
28 |
28 |
29 'user' mode is activated automatically when cubicweb is a mercurial checkout |
29 where `<INSTALL_PREFIX>` is the detected installation prefix ('/usr/local' for |
30 (e.g. has a .hg directory). You can also force mode by using the `CW_MODE` |
30 instance). |
31 environment variable, to: |
31 |
32 |
32 |
33 * use system wide installation but user specific instances and all, without root |
33 Notice that each resource path may be explicitly set using an environment |
34 privileges on the system (`export CW_MODE=user`) |
34 variable if the default doesn't suit your needs. Here are the default resource |
35 |
35 directories that are affected according to mode: |
36 * use local checkout of cubicweb on system wide instances (requires root |
|
37 privileges on the system (`export CW_MODE=system`) |
|
38 |
|
39 Here is the default resource directories settings according to mode: |
|
40 |
36 |
41 * 'system': :: |
37 * 'system': :: |
42 |
38 |
43 CW_INSTANCES_DIR = /etc/cubicweb.d/ |
39 CW_INSTANCES_DIR = <INSTALL_PREFIX>/etc/cubicweb.d/ |
44 CW_INSTANCES_DATA_DIR = /var/lib/cubicweb/instances/ |
40 CW_INSTANCES_DATA_DIR = /var/lib/cubicweb/instances/ |
45 CW_RUNTIME_DIR = /var/run/cubicweb/ |
41 CW_RUNTIME_DIR = /var/run/cubicweb/ |
46 |
42 |
47 * 'user': :: |
43 * 'user': :: |
48 |
44 |
49 CW_INSTANCES_DIR = ~/etc/cubicweb.d/ |
45 CW_INSTANCES_DIR = ~/etc/cubicweb.d/ |
50 CW_INSTANCES_DATA_DIR = ~/etc/cubicweb.d/ |
46 CW_INSTANCES_DATA_DIR = ~/etc/cubicweb.d/ |
51 CW_RUNTIME_DIR = /tmp |
47 CW_RUNTIME_DIR = /tmp |
52 |
48 |
|
49 Cubes search path is also affected, see the :ref:Cube section. |
|
50 |
|
51 By default, the mode automatically set to 'user' if a :file:`.hg` directory is found |
|
52 in the cubicweb package, else it's set to 'system'. You can force this by setting |
|
53 the :envvar:`CW_MODE` environment variable to either 'user' or 'system' so you can |
|
54 easily: |
|
55 |
|
56 * use system wide installation but user specific instances and all, without root |
|
57 privileges on the system (`export CW_MODE=user`) |
|
58 |
|
59 * use local checkout of cubicweb on system wide instances (requires root |
|
60 privileges on the system (`export CW_MODE=system`) |
|
61 |
|
62 If you've a doubt about the mode you're currently running, check the first line |
|
63 outputed by the :command:`cubicweb-ctl list` command. |
|
64 |
|
65 Also, if cubicweb is a mercurial checkout located in `<CW_SOFTWARE_ROOT>`: |
|
66 |
|
67 * main cubes directory is `<CW_SOFTWARE_ROOT>/../cubes`. You can specify |
|
68 another one with :envvar:`CW_INSTANCES_DIR` environment variable or simply |
|
69 add some other directories by using :envvar:`CW_CUBES_PATH` |
|
70 |
|
71 * cubicweb migration files are searched in `<CW_SOFTWARE_ROOT>/misc/migration` |
|
72 instead of `<INSTALL_PREFIX>/share/cubicweb/migration/`. |
|
73 |
|
74 |
|
75 .. _ConfigurationEnv: |
|
76 |
|
77 Environment configuration |
|
78 ------------------------- |
|
79 |
|
80 Python |
|
81 `````` |
|
82 |
|
83 If you installed |cubicweb| by cloning the Mercurial forest or from source |
|
84 distribution, then you will need to update the environment variable PYTHONPATH by |
|
85 adding the path to the forest `cubicweb`: |
|
86 |
|
87 Add the following lines to either :file:`.bashrc` or :file:`.bash_profile` to |
|
88 configure your development environment :: |
|
89 |
|
90 export PYTHONPATH=/full/path/to/cubicweb-forest |
|
91 |
|
92 If you installed |cubicweb| with packages, no configuration is required and your |
|
93 new cubes will be placed in `/usr/share/cubicweb/cubes` and your instances will |
|
94 be placed in `/etc/cubicweb.d`. |
|
95 |
|
96 |
|
97 CubicWeb |
|
98 ```````` |
|
99 |
|
100 Here are all environment variables that may be used to configure |cubicweb|: |
53 |
101 |
54 .. envvar:: CW_MODE |
102 .. envvar:: CW_MODE |
55 Resource mode: user or system |
103 |
|
104 Resource mode: user or system, as explained in :ref:ResourceMode. |
56 |
105 |
57 .. envvar:: CW_CUBES_PATH |
106 .. envvar:: CW_CUBES_PATH |
58 Augments the default search path for cubes |
107 |
|
108 Augments the default search path for cubes. You may specify several |
|
109 directories using ':' as separator (';' under windows environment). |
59 |
110 |
60 .. envvar:: CW_INSTANCES_DIR |
111 .. envvar:: CW_INSTANCES_DIR |
61 Directory where cubicweb instances will be found |
112 |
|
113 Directory where cubicweb instances will be found. |
62 |
114 |
63 .. envvar:: CW_INSTANCES_DATA_DIR |
115 .. envvar:: CW_INSTANCES_DATA_DIR |
64 Directory where cubicweb instances data will be written |
116 |
|
117 Directory where cubicweb instances data will be written (backup file...) |
65 |
118 |
66 .. envvar:: CW_RUNTIME_DIR |
119 .. envvar:: CW_RUNTIME_DIR |
|
120 |
67 Directory where pid files will be written |
121 Directory where pid files will be written |
68 |
122 |
69 .. envvar:: CW_MIGRATION_DIR |
123 |
70 Directory where cubicweb migration files will be found |
124 .. |cubicweb| replace:: *CubicWeb* |
71 |
|
72 |
|
73 :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses |
|
74 """ |
125 """ |
75 __docformat__ = "restructuredtext en" |
126 __docformat__ = "restructuredtext en" |
76 _ = unicode |
127 _ = unicode |
77 |
128 |
78 import sys |
129 import sys |