[Summary view] [Print] [Text view]

   1  This file explains the installation of Caravel.  Also see README and FAQ.
   2  
   3  Thanks for downloading the Caravel Content Management System...this file will
   4  help you install it.  Depending on what you already have installed on your
   5  system, your installation may vary.  Some of the software is specified as
   6  optional, but is required for full functionality of Caravel.  Throughout
   7  this document, we will assume the presence of this optional Software.
   8  
   9  As of right now, Caravel only supports *nix platforms.  There is no reason
  10  why Caravel would not run on other platforms, but no one has yet taken the
  11  time to figure out how to configure everything to do this.  If you happen to
  12  get Caravel running on another platform we'd love to hear about it.
  13  
  14  You may notice this file is pretty long.  This is because there is a lot of
  15  stuff that Caravel needs to have installed before it can work properly and
  16  some of this stuff is not easy to install.  It is also because, in the hope
  17  that this can be a useful document, we've been pretty verbose throughout. 
  18  If you want an easier, shorter document, check out QUICK_INSTALL.  You'll
  19  probably have to read parts of this anyway, though.
  20  
  21  Throughout this document, we assume that the Caravel source is in the 
  22  /usr/local/caravel directory.  To obtain a copy of the Caravel source, go to
  23  http://www.caravelcms.org or visit our repository on sourceforge, or for a
  24  copy of the latest stable (usually) source check out from our CVS repository
  25  by running:
  26  
  27  CVSROOT=":pserver:anonymous@cvs.sf.net:/cvsroot/caravel" cvs login
  28  CVSROOT=":pserver:anonymous@cvs.sf.net:/cvsroot/caravel" cvs -z3 co -P caravel
  29  (Note: Do this somewhere other than in /usr/local or else the installation
  30  script will think caravel is already installed.)
  31  
  32  
  33  Sections of this document:
  34  --------------------------
  35  Required and Optional Software
  36  Installation Instructions for Required and Optional Software
  37  Caravel Installation and Setup
  38  Things to Note and Possible Problems
  39  
  40  
  41  Required Software:
  42  ------------------
  43  * OpenLDAP >= 2.2.24
  44  * Apache >= 1.3
  45  * PHP >= 4.3.8 -- note that php 5 support is experimental
  46    - Pear: XML_HTMLSax >= 2.1.2
  47    - Pear: DB
  48    - Pear: HTML_Common
  49    - Pear: HTML_CSS >= 1.0.0RC1
  50  
  51  
  52  Optional But Highly Suggested Software:
  53  --------------------------------
  54  * PostgreSQL >= 7.4     (Suggested (secure) backend for Sessions,
  55              and required for these applications:
  56              RSS, Project Manager, E-Commerce
  57  * BerkeleyDB >= 4.3     (Suggested backend for OpenLDAP)
  58  * Curl and Image Libraries  (Required for some functionality)
  59  
  60  
  61  Installation Instructions for Required and Optional Software:
  62  -------------------------------------------------------------
  63  Software is presented here in approximately the order it should be   
  64  installed.  Optional is listed along with required.
  65  
  66  Instructions are given for compiling the necessary software from source;
  67  however, your distribution's packages of this software will likely work just
  68  as well, and will likely be a much easier installation!  If you do this,
  69  be sure not to miss the instructions in the openldap section for setting up
  70  slapd.conf!
  71  
  72  
  73  ***1. BerkeleyDB:
  74  BerkeleyDB is suggested as the backend for OpenLDAP.  The other possibilities
  75  (ldbm) do not scale as well and are less stable.  Some users on 64 bit
  76  systems may have trouble compiling BDB.  We assure you it's possible.  If
  77  you simply can't do it you might try obtaining a precompiled packaged version.
  78  
  79  The latest version of BerkeleyDB can be obtained at http://www.sleepycat.com
  80  
  81  To compile BerkeleyDB:
  82  As root, untar the contents of the BerkeleyDB tarball into wherever you like
  83  to put source.  We'll assume that you're putting it in the /usr/local directory.
  84  
  85  A. su - root
  86  B. cp /usr/local/caravel/other/db-4.3.27.tar.gz /usr/local
  87  C. cd /usr/local
  88  D. tar -zxvf db-4.3.27.tar.gz
  89  
  90  cd into the unix build directory and run configure, make and make install.
  91  
  92  G. cd build_unix
  93  H. ../dist/configure
  94  I. make
  95  J. make install
  96  
  97  You may also need to add the BDB lib directory to your ldconfig.  To do
  98  this, add the directory to ld.so.conf and then run ldconfig:
  99  
 100  K. echo /usr/local/BerkeleyDB.4.3/lib >> /etc/ld.so.conf
 101  L. ldconfig
 102  
 103  
 104  ***2. PostgreSQL
 105  PostgreSQL is required for some Caravel applications and is the suggested
 106  (and secure) backend for Caravel's (PEAR) sessions.  It is also possible to
 107  configure PEAR sessions to simply store the data in the filesystem or to use
 108  MySQL or Oracle databases.  Currently the RSS, ProjectManager
 109  and E-Commerce applications require PostgreSQL to run.
 110  
 111  Note that we do not necessarily suggest running PostgreSQL on a different
 112  machine from your web server.  This is because Caravel does not place much
 113  load on PostgreSQL and so the difference (unless you are running a HUGE
 114  server) is not noticable.  We run PostgreSQL on the same machine as most of
 115  our web servers and it's fine.  If you REALLY want to run it on a different
 116  machine, you're perfectly welcome to.
 117  
 118  PostgreSQL source can be obtained from http://www.postgresql.org
 119  
 120  To install PostgreSQL, you will first need to create a user that postgresql runs
 121  as.  We'll assume the user "postgres".  Then untar the source into a
 122  directory you like to put source in and run the standard configure, make and
 123  make install.  We'll assume you unpacked it into /usr/local
 124  
 125  A. su - root
 126  B. cd postgresql-7.4.5
 127  C. ./configure --with-openssl
 128  D. make
 129  E. make install
 130  
 131  Then go through these steps to set up your initial database and test
 132  postgres.  Remember we're assuming your postgres user is "postgres".
 133  
 134  F. chown -R postgres /usr/local/pgsql
 135  G. su - postgres
 136  H. /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
 137  I. /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >/usr/local/pgsql/logfile 2>&1 &
 138  J. /usr/local/pgsql/bin/createdb test
 139  K. /usr/local/pgsql/bin/psql test
 140  
 141  You will likely want to add PostgreSQL to your startup files.  An example
 142  startup file is provided in with Caravel under the install directory named 
 143  rc.caravel
 144  
 145  You will also want to add a cronjob that will run the 'vacuumdb' command
 146  nightly.  This will keep your postgres server running at high efficiency. 
 147  Edit your root crontab and add the suggested line below.  We assume your
 148  postgres user is 'postgres'
 149  
 150  A. crontab -u root -e (this will open a text editor)
 151  B. (add the line which will run vacuumdb at 12:05 each night):
 152  05 00 * * * /usr/local/pgsql/bin/vacuumdb -a -U postgres >/dev/null 2>&1
 153  C. (save the file)(in the default editor vi hit 'esc' then ':wq' then 'enter')
 154  
 155  It appears that newer versions of PHP than 4.3.4 do not actually support
 156  connecting to Postgres through unix sockets.  Thus, since we suggest running
 157  the latest version of PHP, you must turn on tcp/ip sockets for Postgres. 
 158  You will not need to do anything else, as configuring PHP for unix sockets will 
 159  work just fine.  It just doesn't actually use them.
 160  
 161  To turn on tcp/ip connections to Postgres, edit
 162  /usr/local/pgsql/data/postgresql.conf and change tcpip_socket from 'false'
 163  to 'true'.  In Postgres version 8 this parameter has been replaced by 
 164  'listen_addresses'
 165  If you can't find any mention of "tcpip_socket" then add the
 166  following line to the file:
 167  
 168  tcpip_socket=true
 169  
 170  Also, you will probably want (we suggest) to turn passwords on.  To do
 171  this follow the steps below.
 172  
 173  A. As postgres, with postmaster running, run "/usr/local/pgsql/bin/psql template1" 
 174     and, at the prompt, enter (where rootpassword is your desired password):
 175       ALTER USER postgres with password 'rootpassword';
 176  B. then edit /usr/local/pgsql/data/pg_hba.conf and change "trust" to "password" 
 177      An example of this is given below.
 178  C. restart postmaster / pgsql
 179  
 180  ------------------------pg_hba.conf---------------------------
 181  local   all         all                                             password
 182  host    all         all         1.2.3.4         255.255.255.0       password
 183  host    all         all         127.0.0.1       255.0.0.0           password
 184  
 185  ------------------------pg_hba.conf---------------------------
 186  
 187  
 188  ***3. Apache
 189  Apache is the only supported web server for Caravel right now.  We use
 190  Apache's mod_rewrite somewhat extensively and would require similar support
 191  from other web servers to support them.  This would also of course require
 192  someone to rewrite our rewrite code to work with the other server in
 193  question.  If you do this, we'd love to hear about it.
 194  
 195  Caravel works fine under both Apache 1.3 and Apache2.  We suggest running
 196  Apache2 however and only provide instructions for installing Apache2.
 197  
 198  Apache source can be obtained from http://www.apache.org
 199  
 200  To install apache2 as root, untar and run configure make and make install. 
 201  We need a few modules enabled however so you'll need to do that on the
 202  configure line.  Note that we also need PHP enabled, but this happens by
 203  default these days. 
 204  
 205  A. su - root
 206  B. ./configure \
 207  --with-layout=Apache \
 208  --enable-so \
 209  --enable-ssl \
 210  --enable-rewrite
 211  C. make
 212  D. make install
 213  
 214  You will probably want to include apache in your startup scripts.  An
 215  example of this is provided in the caravel install directory named
 216  "rc.caravel"
 217  
 218  IF you've already got Apache installed, and it doesn't support something and
 219  you REALLY don't want to recompile it, then you can compile them as Dynamic 
 220  Loadable Modules and include them in httpd.conf/apache2.conf
 221  
 222  To compile a Dynamic Loadable Module, cd to the directory that contains the
 223  module code, and compile it using apache's apxs program.  Then install it
 224  using the same program.  An example is given below with mod_rewrite.
 225  
 226  A. su - root
 227  B. cd /usr/local/httpd-2.0.50/modules/mappers
 228  C. /usr/local/apache2/bin/apxs -c mod_rewrite.c
 229  D. /usr/local/apache2/bin/apxs -i -a -n rewrite mod_rewrite.la
 230  
 231  Then restart Apache.
 232  
 233  IMPORTANT NOTE: you MUST configure apache to run as a user and group other
 234  than nobody.  This is very easy, simply add a new user and group and then change 
 235  your httpd.conf/apache2.conf so that it uses them.  Example:
 236     User apache
 237     Group apache
 238  
 239  
 240  ***4. OpenLDAP
 241  Caravel uses OpenLDAP as its primary method of storing data.  The
 242  performance of Caravel is closely tied to the performance of OpenLDAP and so
 243  it is not a bad idea to run your Caravel OpenLDAP server on a different
 244  machine from your web server.  Different tweaking options are also possible
 245  to improve OpenLDAP's performance.  We'll outline a couple at the bottom of
 246  this install section.
 247  
 248  You can obtain a copy of OpenLDAP at http://www.openldap.org
 249  
 250  Here we assume that BerkeleyDB 4.3 is installed in your /usr/local
 251  directory.  Notice that OpenLDAP install contains an extra step so you
 252  configure, make depend, make and make install.
 253  
 254  A. su - root
 255  B. env CPPFLAGS="-I/usr/local/BerkeleyDB.4.3/include" \
 256  LDFLAGS="-L/usr/local/BerkeleyDB.4.3/lib" \
 257  ./configure
 258  C. make depend
 259  D. make
 260  E. make install
 261  
 262  The file that OpenLDAP uses for its basic configuration is called slapd.conf
 263  and is located by default at /usr/local/etc/openldap/slapd.conf
 264  
 265  Deciding what your Caravel Base is:
 266  
 267  The are two different ways that you can set up your caravel installation.
 268  The first way is Domain Mode which is ideal for ISPs. The second is Single
 269  Mode which is suggested for organizations or personal users. The default is
 270  Single Mode.
 271  
 272  Domain Mode: Caravel Base is your domain
 273  Your domain name will be your Caravel base. Whenever you create new sites
 274  they will be accessible by their host name. Thus if your base domain is
 275  'example.com' and you create a Caravel site called 'test', it will be
 276  accessible from the url 'test.example.com'.
 277  Please note that if you choose this mode then each time you create a Caravel
 278  site you must make sure that DNS is resolving that host name to your
 279  webserver, or that DNS is set to resolve '*.example.com' to your webserver.
 280  
 281  Single Mode: Caravel Base is your hostname
 282  Your webserver's hostname will be your Caravel base. Whenever you create new
 283  sites you will access them as a path on your webserver. Thus if your
 284  webserver is 'www.example.com' and you create a new Caravel site called
 285  'test', it will be accessible from the url 'www.example.com/test'. This is
 286  beneficial because then the only hostname that DNS must resolve to your
 287  webserver is its own hostname.
 288  
 289  Caravel requires a number of rules, includes and indexes that need to be
 290  added to slapd.conf for basic operation.  This is of course in addition to
 291  whatever other slapd configuration you may be running.  For example the
 292  schema files listed here should be IN ADDITION to core.schema.  You will also 
 293  need to be sure to change 'dc=mydomain,dc=net' to your Caravel base.
 294  Thus if your Caravel Base is www.example.com you would replace
 295  'dc=mydomain,dc=net' with 'dc=www,dc=example,dc=com'.
 296  
 297  If you used your distribution's package of OpenLDAP, then be sure to include
 298  the schema files from the proper location!
 299  
 300  --------------------------- slapd.conf------------------------------------
 301  
 302  include        /usr/local/etc/openldap/schema/cosine.schema
 303  include     /usr/local/etc/openldap/schema/inetorgperson.schema
 304  include     /usr/local/etc/openldap/schema/nis.schema
 305  
 306  include        /usr/local/caravel/conf/caravel.schema
 307  
 308  #change dc=mydomain,dc=net to your Caravel base
 309  access to filter="(objectClass=mennoAccount)" by self write by dn="ou=users,dc=mydomain,dc=net" write by * read
 310  
 311  #change dc=mydomain,dc=net to your Caravel base
 312  access to * by self write by "dn=uid=root,ou=users,dc=mydomain,dc=net" write by * read
 313  
 314  -------------------------- end slapd.conf---------------------------------
 315  
 316  Further important steps for slapd.conf include setting up your basic domain
 317  information and rootdn and rootpw.  We suggest using MD5 encryption for the
 318  rootpw.  Make sure the the user openldap runs as has write access to the
 319  specified 'directory'.  For performance reasons it is important to list a
 320  cachesize.  This should be a number larger than the number of entries in
 321  your ldap database.  You should also list a sizelimit, which is the max number 
 322  of entries returned by a query.  You might want to make this the same as your 
 323  cachesize.  You probably don't want to but could set this to 'unlimited'.  
 324  
 325  IMPORTANT!!! you MUST specify a checkpoint directive in slapd.conf if you are 
 326  using BDB (unless you define txn_checkpoint in a DB_CONFIG file).  At least you 
 327  must if you want any kind of data integrity.
 328  
 329  Other potential performance tweaks are adding the 'dbnosync' and 'dirtyread'
 330  directives.  These should not be used with smaller setups, but may be
 331  considered with larger ones.  A smaller setup has maybe less than 50000
 332  entries.  These can increase write performance significantly but can also
 333  decrease the consistency of the data your users will see.  Use with caution.
 334  
 335  An example config is given below:
 336  
 337  -------------------------- slapd.conf ------------------------------------
 338  
 339  #sets the backend to BerkeleyDB
 340  database    bdb
 341  
 342  #change this to your Caravel base
 343  suffix      "dc=mydomain,dc=net"
 344  
 345  #and this to your Caravel base as well
 346  rootdn      "uid=root,ou=users,dc=mydomain,dc=net"
 347  
 348  #MD5 hash of password
 349  rootpw      {MD5}secret-hash
 350  
 351  #where the data goes - make sure that this dir exists and ldap can write to it
 352  directory   /usr/local/var/openldap-data
 353  
 354  #if you have less than 200000 entries
 355  cachesize    200000
 356  
 357  #again, more than what you have
 358  sizelimit    200000
 359  
 360  #checkpoints every 128k written or 10 mins
 361  checkpoint    128 10
 362  
 363  #dbnosync                    #if you have a very large site consider this
 364  #dirtyread                    #this one too (very large == >100000 entries)
 365  
 366  #these are the indexes that caravel needs.  These MUST be in slapd.conf
 367  index objectClass,mennoEmailAlias,uidNumber,gidNumber,mennoOtherDomain pres,eq
 368  index mnTB,mnTS,member,mennoOrganizationType,mnF,mnOD,mnTSS,mnSC pres,eq
 369  index o,cn,uid,memberUid pres,sub,eq
 370  index cvPriv pres
 371  
 372  -------------------------- end slapd.conf ---------------------------------
 373  
 374  To start slapd, the openldap daemon, assuming you installed to where we
 375  suggested you would type:
 376  
 377  /usr/local/libexec/slapd -f /usr/local/etc/openldap/slapd.conf
 378  
 379  it is also a good idea (if you're writing a startup script) to run
 380  /usr/local/BerkeleyDB.4.3/bin/db_recover -h /usr/local/var/openldap-data/
 381  before you start openldap each time just to ensure data integrity.
 382  
 383  ***6. Curl and Image Libraries
 384  These are libraries that are required for full Caravel functionality.  Curl
 385  is required for the E-Commerce applications and the Image Libraries are
 386  required for some manipulation done by programs like Folder Viewer.  These
 387  are not required for Caravel's basic functioning but allow some pretty cool
 388  features if they are installed.
 389  
 390  Curl can be obtained from http://curl.haxx.se it is a very standard
 391  ./configure, make, make install procedure that you should be familiar with
 392  by now.
 393  
 394  You will also need jpeg and png libraries which can be obtained from 
 395  http://www.ijg.org/files/jpegsrc.v6b.tar.gz 
 396  and
 397  http://download.sourceforge.net/libpng/ 
 398  respectively.
 399  It is very likely that there are packaged versions of these libraries which
 400  you can get from your Linux vendor and may already be installed.  It is
 401  recommended that you use those packaged versions rather than downloading and
 402  compiling these yourself.
 403  
 404  
 405  ***5. PHP
 406  PHP is the language that Caravel is written in.  PHP source and information
 407  on the PHP language can be obtained at http://www.php.net
 408  
 409  PHP is installed with a standard configure, make, make install.  However, we
 410  need an awful lot of php's options enabled for Caravel to run properly.  If
 411  you already have PHP installed, but without many of these options, you will
 412  probably want to recompile it rather than try to compile everything as a
 413  module.  You may need to modify some things on command line to fit your
 414  system.
 415  
 416  A. su - root
 417  B. cd php-4.3.8
 418  C. ./configure --with-apxs2=/usr/local/apache2/bin/apxs \
 419  --with-config-file-path=/usr/local/apache2/conf
 420  --with-ldap \
 421  --enable-mailparse \
 422  --enable-trans-sid \
 423  --with-regex=system \
 424  --with-pgsql \
 425  --with-openssl \
 426  --with-pear \
 427  --with-expat-dir=/usr \
 428  --with-zlib \
 429  --with-curl=/usr/local/curl \
 430  --with-gd --with-jpeg-dir=/usr --with-png-dir=/usr
 431  
 432  At this point (assuming the configure step went well) you will need to run
 433  make and make install.
 434  
 435  D. make
 436  E. make install
 437  
 438  PHP doesn't automatically create its config file, php.ini, so we'll have to
 439  copy it ourselves.
 440  
 441  F. cp php.ini-recommended /usr/local/apache2/conf/php.ini
 442  
 443  But wait!  We're not completely finished!  You still need to set up PHP with
 444  Apache.  If you've had PHP working with apache before you might not need to
 445  do this.  Open httpd.conf / apache2.conf and make these changes:
 446  
 447  First make sure "index.php" is in your DirectoryIndex.  The line should look
 448  like:
 449      DirectoryIndex index.html index.htm index.cgi index.php
 450  Second make sure the php type is defined.  There should be a line that looks
 451  like:
 452      AddType application/x-httpd-php .php
 453  
 454  
 455  ***6. PEAR
 456  Assuming PHP installation has gone alright, you should be able to simply do
 457  this to install the HTMLSax and DB packages, which pear will automatically 
 458  download from the appropriate repository.
 459  
 460  su - root
 461  pear install XML_HTMLSax
 462  pear install DB
 463  pear install HTML_Common
 464  pear config-set preferred_state beta
 465  pear install HTML_CSS
 466  pear config-set preferred_state stable
 467  
 468  
 469  Caravel Installation and Setup:
 470  -------------------------------------------------------------------------
 471  Congrats!  Assuming you've gotten everything working, you are ready to do
 472  the final setup for Caravel.  It gets easier from here on out.  Just like
 473  before we assume that caravel is installed in /usr/local/caravel.  If you
 474  didn't do a CVS checkout, you probably have an outdated version and we urge
 475  that you consider updating.  We change the CVS tree almost every day.
 476  
 477  1. RUN THE INSTALL.SH SCRIPT:
 478  ---------------------------------
 479  First things first, you need to run the install.sh script located in the
 480  directory where you untarred Caravel.  If for some reason you need to
 481  wipe your caravel install at a later date, you can run the script with the
 482  'clean' option and it will revert your settings to the defaults.  If you are
 483  concerned about what it is doing you might want to open it up and check it
 484  out.
 485  
 486  Be sure to run the script as root.
 487  
 488  2. COMPLETE THE ONLINE CONFIGURATION:
 489  -------------------------------------
 490  Once it has completed successfully, you just need to go to your Caravel
 491  domain in a web browser to perform the final setup steps.  Once this is
 492  complete, you should be able to go to your default-caravel site and begin
 493  using Caravel for what you were hoping to the whole time you've been
 494  installing things.
 495  
 496  Things to Note and Possible Problems:
 497  ----------------------------------------------------------------------------
 498  There are lots and lots of potential problems people have during the install
 499  process.  Most are due to other programs and not Caravel.  If you've gotten
 500  most of the way through this and can access something provided by Caravel in
 501  a web browser then the first thing you should check when you encounter a
 502  problem is Apache's error_log file, probably in /usr/local/apache2/logs. 
 503  Look at the bottom of it and it should provide some clues.  Ignore all the
 504  php notices Caravel is generating.  In general, actually, caravel throws a 
 505  lot of warnings and notices.  If you have a sane production environment this
 506  should be fine.  We're working on reducing them.
 507  
 508  Make sure you read README as there is important information there as well.
 509  All questions and answers have been moved to the FAQ.
 510  Please, I beg you, consult the FAQ if you have questions before emailing
 511  someone.  It is very likely your questions will be there.
 512  If your questions are not, then write info@mennonite.net, your message will
 513  be probably be forwarded to someone who may be able to help you.
 514  
 515  -----------------
 516  -seanmk 4/27/05
 517  -davidig 8/19/05