Compiling From Source

Software is presented here in approximately the order it should be installed. Optional is listed along with required. Instructions are given for compiling the necessary software from source; however, your distribution's packages of this software will likely work just as well, and will likely be a much easier installation! If you do this, be sure not to miss the instructions in the openldap section for setting up slapd.conf.

BerkeleyDB
BerkeleyDB is suggested as the backend for OpenLDAP. The other possibilities (ldbm) do not scale as well and are less stable. Some users on 64 bit systems may have trouble compiling BDB. We assure you it's possible. If you simply can't do it you might try obtaining a precompiled packaged version.

The latest version of BerkeleyDB can be obtained here. As root, untar the contents of the BerkeleyDB tarball into wherever you like to put source. We'll assume that you're putting it in the /usr/local directory.


cd into the unix build directory and run configure, make and make install.


You may also need to add the BDB lib directory to your ldconfig. To do this, add the directory to ld.so.conf and then run ldconfig:


PostgreSQL
PostgreSQL is required for some Caravel applications and is the suggested (and secure) backend for Caravel's (PEAR) sessions. It is also possible to configure PEAR sessions to simply store the data in the filesystem, but this is not a secure option. Currently the RSS, ProjectManager and E-Commerce applications require PostgreSQL to run.

Note that we do not necessarily suggest running PostgreSQL on a different machine from your web server. This is because Caravel does not place much load on PostgreSQL and so the difference (unless you are running a HUGE server) is not noticable. We run PostgreSQL on the same machine as most ofour web servers and it's fine. If you REALLY want to run it on a different machine, you're perfectly welcome to but make sure when you run install.sh that you answer 'n' when it asks if it should configure postgres.

PostgreSQL source can be obtained here.

To install PostgreSQL, you will first need to create a user that postgresql runs as. We'll assume the user "postgres". Then untar the source into a directory you like to put source in and run the standar configure, make and make install. We'll assume you unpacked it into /usr/local


Then go through these steps to set up your initial database and test postgres. Remember we're assuming your postgres user is "postgres".


You will likely want to add PostgreSQL to your startup files. An example startup file is provided in with Caravel under the install directory named rc.caravel. You will also want to add a cronjob that will run the 'vacuumdb' command nightly. This will keep your postgres server running at high efficiency. Edit your root crontab and add the suggested line below. We assume your postgres user is 'postgres'


This will open a text editor, add the following line which will run vacuumdb every night at 12:05, and then save the file.


It appears that newer versions of PHP than 4.3.4 do not actually support connecting to Postgres through unix sockets. Thus, since we suggest running the latest version of PHP, you must turn on tcp/ip sockets for Postgres. You will not need to do anything else, as configuring PHP for unix sockets will work just fine. It just doesn't actually use them. To turn on tcp/ip connections to Postgres, edit /usr/local/pgsql/data/postgresql.conf and change tcpip_socket from 'false' to 'true'. If you can't find any mention of "tcpip_socket" then add the following line to the file:


Also, you will probably want to turn md5 passwords on. To do this follow the steps below as user postgres with postmaster running.


At the prompt, enter the following(where rootpassword is your desired password):


Finally, edit /usr/local/pgsql/data/pg_hba.conf and change "trust" to "md5" except on the localhost line. An example conf file is given below.


Apache
Apache is the only supported web server for Caravel right now. We use Apache's mod_rewrite somewhat extensively and would require similar support from other web servers to support them. This would also of course require someone to rewrite our rewrite code to work with the other server in question. If you do this, we'd love to hear about it.

Caravel works fine under both Apache 1.3 and Apache2. We suggest running Apache2 however and only provide instructions for installing Apache2.

Apache source can be obtained from here.

To install apache2 as root, untar and run configure make and make install.  We need a few modules enabled however so you'll need to do that on the configure line. Note that we also need PHP enabled, but this happens by default these days.


You will probably want to include apache in your startup scripts. Anexample of this is provided in the caravel install directory named "rc.caravel"

IMPORTANT NOTE: you MUST configure apache to run as a user and group other than nobody. This is very easy, simply add a new user and group and then make sure the following two lines are in your httpd.conf.



OpenLDAP
Caravel uses OpenLDAP as its primary method of storing data. The performance of Caravel is closely tied to the performance of OpenLDAP and so it is not a bad idea to run your Caravel OpenLDAP server on a different machine from your web server. Different tweaking options are also possible to improve OpenLDAP's performance. We'll outline a couple at the bottom of this install section.

You can obtain a copy of OpenLDAP here.

Here we assume that BerkeleyDB 4.3 is installed in your /usr/local directory. Notice that OpenLDAP install contains an extra step so you configure, make depend, make and make install.


The file that OpenLDAP uses for its basic configuration is called slapd.conf and is located by default at /usr/local/etc/openldap/slapd.conf

Deciding what your Caravel Base is:
The are two different ways that you can set up your caravel installation. The first way is Domain Mode which is ideal for ISPs. The second is Single Mode which is suggested for organizations or personal users. The default is Single Mode.

Domain Mode: Caravel Base is your domain
Your domain name will be your Caravel base. Whenever you create new sites they will be accessible by their host name. Thus if your base domain is 'example.com' and you create a Caravel site called 'test', it will be
accessible from the url 'test.example.com'.

Please note that if you choose this mode then each time you create a Caravel site you must make sure that DNS is resolving that host name to your webserver, or that DNS is set to resolve '*.example.com' to your webserver.

Single Mode: Caravel Base is your hostname
Your webserver's hostname will be your Caravel base. Whenever you create new sites you will access them as a path on your webserver. Thus if your webserver is 'www.example.com' and you create a new Caravel site called 'test', it will be accessible from the url 'www.example.com/test'. This is beneficial because then the only hostname that DNS must resolve to your webserver is its own hostname.

Caravel requires a number of rules, includes and indexes that need to be added to slapd.conf for basic operation. This is of course in addition to whatever other slapd configuration you may be running. For example the schema files listed here should be IN ADDTION to core.schema. You will also
need to be sure to change 'dc=mydomain,dc=net' to your Caravel base.

Thus if your Caravel Base is www.example.com you would replace

'dc=mydomain,dc=net' with 'dc=www,dc=example,dc=com'.

Further important steps for slapd.conf include setting up your basic domain information and rootdn and rootpw. We suggest using MD5 encryption for the rootpw. Make sure the the user openldap runs as has write access to the specified 'directory'. For performance reasons it is important to list a cachesize. This should be a number larger than the number of entries in your ldap database. You should also list a sizelimit, which is the max number of entries returned by a query. You might want to make this the same as your cachesize. You probably don't want to but could set this to 'unlimited'.

IMPORTANT, you MUST specify a checkpoint directive in slapd.conf if you are using BDB (unless you define txn_checkpoint in a DB_CONFIG file). At least you must if you want any kind of data integrity. Other potential performance tweaks are adding the 'dbnosync' and 'dirtyread' directives. These should not be used with smaller setups, but may be considered with larger ones. A smaller setup has maybe less than 50000 entries. These can increase write performance significantly but can also decrease the consistency of the data your users will see. Use with caution.

An example config is given below.


To start slapd, the openldap daemon, assuming you installed to where we suggested you would type:
/usr/local/libexec/slapd -f /usr/local/etc/openldap/slapd.conf . It is also a good idea (if you're writing a startup script) to run /usr/local/BerkeleyDB.4.3/bin/db_recover -h /usr/local/var/openldap-data/ before you start openldap each time just to ensure data integrity.

Curl and Image Libraries
These are libraries that are required for full Caravel functionality. Curl is required for the E-Commerce applications and the Image Libraries are required for some manipulation done by programs like Folder Viewer. These are not required for Caravel's basic functioning but allow some pretty cool features if they are installed. Curl can be obtained from here. It is a very standard ./configure, make, make install procedure that you should be familiar with by now.


You will also need jpeg and png libraries which can be obtained from here and here.

It is very likely that there are packaged versions of these libraries which you can get from your Linux vendor and may already be installed. It is recommended that you use those packaged versions rather than downloading and compiling these yourself.

PHP
PHP is the language that Caravel is written in. PHP source and information on the PHP language can be obtained here.

PHP is installed with a standard configure, make, make install. However, we need an awful lot of php's options enabled for Caravel to run properly. If you already have PHP installed, but without many of these options, you will probably want to recompile it rather than try to compile everything as a module. You may need to modify some things on command line to fit your system.


PHP doesn't automatically create its config file, php.ini, so we'll have to copy it ourselves.


But wait! We're not completely finished! You still need to set up PHP with Apache. If you've had PHP working with apache before you might not need to do this. Open httpd.conf and make these changes:

First make sure "index.php" is in your DirectoryIndex. The line should look like:


Second make sure the php type is defined. There should be a line that looks like:


PEAR
Assuming PHP installation has gone alright, you should be able to simply do this to install the HTMLSax and DB packages, which pear will automatically download from the appropriate repository.