1 .. -*- coding: utf-8 -*-

     2 

     3 .. _SetUpEnv:

     4 

     5 ===================================================

     6 Installation and set-up of a `CubicWeb` environment

     7 ===================================================

     8 

     9 Installation of `Cubicweb` and its dependencies

    10 -----------------------------------------------

    11 

    12 `CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source

    13 using a tarball or the Mercurial version control system.

    14 

    15 .. _DebianInstallation:

    16 

    17 Debian and Ubuntu packages

    18 ```````````````````````````

    19 

    20 Depending on the distribution you are using, add the appropriate line to your list

    21 of sources (for example by editing ``/etc/apt/sources.list``).

    22 

    23 For Debian Lenny::

    24 

    25   deb http://ftp.logilab.org/dists/ lenny/

    26 

    27 For Debian Sid::

    28 

    29   deb http://ftp.logilab.org/dists/ sid/

    30 

    31 For Ubuntu Hardy::

    32 

    33   deb http://ftp.logilab.org/dists/ hardy/

    34 

    35 

    36 You can now install the required packages with the following command::

    37 

    38   apt-get update 

    39   apt-get install cubicweb cubicweb-dev

    40 

    41 `cubicweb` installs the framework itself, allowing you to create

    42 new applications.

    43 

    44 `cubicweb-dev` installs the development environment allowing you to

    45 develop new cubes.

    46 

    47 There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.

    48 

    49 

    50 Install from source

    51 ```````````````````

    52 

    53 You can download the archive containing the sources from our `ftp site`_ at::

    54 

    55   http://ftp.logilab.org/pub/cubicweb/

    56 

    57 .. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/

    58 

    59 or keep up to date with on-going development by using Mercurial and its forest

    60 extension::

    61 

    62   hg fclone http://www.logilab.org/hg/forests/cubicweb

    63 

    64 See :ref:`MercurialPresentation` for more details about Mercurial.

    65 

    66 Postgres installation

    67 `````````````````````

    68 

    69 Please refer to the `Postgresql project online documentation`_.

    70 

    71 .. _`Postgresql project online documentation`: http://www.postgresql.org/

    72 

    73 You need to install the three following packages: `postgres-8.3`,

    74 `postgres-contrib-8.3` and `postgresql-plpython-8.3`.

    75 

    76 

    77 Then you can install:

    78 

    79 * `pyro` if you wish the repository to be accessible through Pyro

    80   or if the client and the server are not running on the same machine

    81   (in which case the packages will have to be installed on both

    82   machines)

    83 

    84 * `python-ldap` if you plan to use a LDAP source on the server

    85 

    86 .. _ConfigurationEnv:

    87 

    88 Environment configuration

    89 -------------------------

    90 

    91 If you installed `CubicWeb` by cloning the Mercurial forest, then you

    92 will need to update the environment variable PYTHONPATH by adding  

    93 the path to the forest ``cubicweb``:

    94 

    95 Add the following lines to either `.bashrc` or `.bash_profile` to configure

    96 your development environment ::

    97   

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

    99 

   100 If you installed the debian packages, no configuration is required.

   101 Your new cubes will be placed in `/usr/share/cubicweb/cubes` and

   102 your applications will be placed in `/etc/cubicweb.d`.

   103 

   104 To use others directories then you will have to configure the

   105 following environment variables as follows::

   106 

   107     export CW_CUBES_PATH=~/lib/cubes

   108     export CW_REGISTRY=~/etc/cubicweb.d/

   109     export CW_INSTANCE_DATA=$CW_REGISTRY

   110     export CW_RUNTIME=/tmp

   111 

   112 .. note::

   113     The values given above are our suggestions but of course

   114     can be different.

   115 

   116 

   117 Databases configuration

   118 -----------------------

   119 

   120 

   121 

   122 .. _ConfigurationPostgres:

   123 

   124 Postgres configuration

   125 ``````````````````````

   126 

   127 .. note::

   128     If you already have an existing cluster and postgres server

   129     running, you do not need to execute the initilization step

   130     of your Postgres database.

   131 

   132 * First, initialize the database Postgres with the command ``initdb``.

   133   ::

   134 

   135     $ initdb -D /path/to/pgsql

   136 

   137   Once initialized, start the database server Postgres 

   138   with the command::

   139   

   140     $ postgres -D /path/to/psql

   141 

   142   If you cannot execute this command due to permission issues, please

   143   make sure that your username has write access on the database.

   144   ::

   145  

   146     $ chown username /path/to/pgsql

   147 

   148 * The database authentication can be either set to `ident sameuser`

   149   or `md5`. 

   150   If set to `md5`, make sure to use an existing user

   151   of your database.

   152   If set to `ident sameuser`, make sure that your

   153   client's operating system user name has a matching user in

   154   the database. If not, please do as follow to create a user::

   155     

   156     $ su

   157     $ su - postgres

   158     $ createuser -s -P username

   159 

   160   The option `-P` (for password prompt), will encrypt the password with

   161   the method set in the configuration file ``pg_hba.conf``. 

   162   If you do not use this option `-P`, then the default value will be null

   163   and you will need to set it with::

   164     

   165     $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"

   166 

   167   This login/password will be requested when you will create an

   168   instance with `cubicweb-ctl create` to initialize the database of

   169   your application.

   170 

   171 .. note::

   172     The authentication method can be configured in ``pg_hba.conf``.

   173 

   174 

   175 .. FIXME Are these steps really necessary? It seemed to work without.

   176 

   177 * Installation of plain-text index extension ::

   178 

   179     cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1

   180 

   181 * Installation of plpythonu language by default ::

   182 

   183     createlang -U pgadmin plpythonu template1

   184 

   185 MySql configuration

   186 ```````````````````

   187 Yout must add the following lines in /etc/mysql/my.cnf file::

   188 

   189     transaction-isolation = READ-COMMITTED

   190     default-storage-engine=INNODB

   191     default-character-set=utf8

   192     max_allowed_packet = 128M

   193 

   194 Pyro configuration

   195 ------------------

   196 

   197 If you use Pyro, it is required to have a name server Pyro running on your

   198 network (by default it is detected by a broadcast request).

   199 

   200 To do so, you need to :

   201 

   202 * launch the server manually before starting cubicweb as a server with

   203   `pyro-nsd start`

   204 

   205 * edit the file ``/etc/default/pyro-nsd`` so that the name server pyro

   206   will be launched automatically when the machine fire up

   207