How to Install

Requirements Optional Libraries Getting Sycamore Setting Permissions Setting up your database Setting up Sycamore Items you need to change right now Building the base install Setting up your web server Apache with CGI Apache with mod_wsgi — UNTESTED Apache with SCGI Apache with FastCGI Lighttpd with SCGI Stand-alone HTTP server Logging In Post-install Maintenance Installing on a Shared Hosting Plan Installing Sycamore on Shared Hosting Plans Dreamhost Shared Hosting

Requirements

There are some other applications and libraries you will need to install Sycamore.

• Python , version 2.4 or newer
  

• PIL 1.1.5 or newer — Python imaging library. Make sure you have it compiled with JPEG and PNG support!
  

• GNU diffutils or newer 2.8.1 — note that most UNIX-style systems have this installed.
  

• a recent version of Subversion, for downloading the source code.
  

• either MySQL:
  

• MySQL >= 5.0
  

• MySQLdb >= 1.2.1_p2 — python MySQL module¹

• or PostgreSQL:
  

• PostgreSQL >= 7.4
  

• psycopg2 >= 2.0 — python PostgreSQL module

Optional Libraries

• xapian-core >= 0.9.4 and xapian-bindings >= 0.9.4. Xapian provides fast, scalable and flexible search for Sycamore. Your search on your wiki will suck and eat up lots of CPU/disk activity if you don't install this.
  

• Memcached >= 1.1.12. Memcached speeds up Sycamore by allowing it to cache objects in memory. If possible, set up memcache and you'll experience speed and database load improvements.
  

  NOTE: Optional Libraries are ON by default in the configuration file in the repository. Be sure to turn them off in step 6 if you are not using them!

Getting Sycamore

The source code is available via SVN at http://svn.devjavu.com/sycamore/trunk. To do a checkout, do:

svn co http://svn.devjavu.com/sycamore/trunk sycamore_base

If you have no idea what SVN is, go to http://subversion.tigris.org/ first. If you are also a Windows user, TortoiseSVN integrates nicely with Windows Explorer.

Windows users please read How to Install/Windows Tips

Ubuntu 6.06 users, you will need to look at Build mysql-python

Mac OS users, there's a quick install guide for sqlite at /OS X

Setting Permissions

In order to have Xapian and Permission Groups running properly, some files and directories will need to have their permissions changed after you get the files from SVN. Everything under /share/data, including the directory "data", needs to be read and writable by the web server app. How to do that is based on if you have a seperate user for the webapp. The majority of that is related to Xapian, but some is related to having group permissions for different pages/users.

Here's a probable set of commands for doing that:

• cd /hosted/sycamore_base/share
  

• chown -R www-data.www-data data
  

• chmod -R u+rw data

Setting up your database

If you're using MySQL issue the command:

CREATE DATABASE <somename>;

then something like this:

GRANT ALL PRIVILEGES ON my_wiki.* TO "sycamore"@"localhost" IDENTIFIED BY "seekrit"; FLUSH PRIVILEGES; EXIT;

If you're using PostgreSQL issue the command:

CREATE DATABASE <somename> WITH ENCODING='UTF8';

You will also need to set up privileges so that the user who runs Sycamore can access the database. From a security standpoint, it is a good idea to create a separate 'Sycamore' user for this purpose. Because this is specific to particulars of databases and configurations it is hard to provide complete step-by-step information on this step.

Setting up Sycamore

You should open sycamore_base/share/sycamore_config.py in a text editor.

Items you need to change right now

• sitename: Pick something that identifies your wiki.
  

• interwikiname: A shorter version of sitename, one word.
  

• catchphrase: Something catchy, 'yanno.
  

• Uncomment (remove the #'s) tabs_user and tabs_nonuser and list the pages you'd like to appear in the site-wide tabs.
  

• db_type: Pick "mysql" or "postgres"
  

• db_name: This is the name of the database you created using the CREATE DATABASE command earlier.
  

• db_user: This is the user that connects to the database.
  

• db_user_password: This is the password of the user who connects to the database.
  

• db_host: You can leave this set to "localhost" unless your database is on another machine.

If you installed any of the optional items (Xapian, Memcached) you should set them to True in the configuration file. These settings are has_xapian and memcache, respectively.

Building the base install

Go into the Sycamore directory and run python buildDB.py. This will create the required database tables and populate your installation with a set of initial pages.

Setting up your web server

You can run Sycamore through a web server such as Apache or lighttpd. Alternatively, Sycamore can run as a stand-alone process and act as its own web server. How you configure your web server depends on your hosting setup and is, of course, particular to your installation. We will provide a few common configurations here.

There's a few different ways to run Sycamore as a program. It can run as its own webserver (the file index in share/web), it can run as a CGI process (the file index.cgi in share/web), it can run as a SCGI process (the file index.scgi in share/web), or it can run as a FastCGI process (the fie index.fcgi in share/web). CGI is probably the easiest to set up, but it is very slow. SCGI, FastCGI and the stand-alone webserver are all very fast and good. We currently recommend SCGI if you can set it up with your webserver.

Apache with CGI

Open your apache httpd.conf file and add something like the following:

<Directory "/Location/to/your/sycamore_base/share/web">
    Options +ExecCGI
</Directory>

Also make sure that AddHandler cgi-script .cgi appears in the httpd.conf file.

Now open sycamore_config.py and set relative_dir to index.cgi. After restarting apache you should be able to access Sycamore's index.cgi at the location you specified.

You will have to do one of the following:

• Make sure you have rewrite rules in .htaccess or httpd.conf to take out index.cgi from the urls, as described in the FAQ. ...or...
  

• Set the relative_dir configuration option to 'index.cgi' (the default is an empty string).

Apache with mod_wsgi — UNTESTED

Add something akin to the following to your httpd.conf file:

  RewriteEngine On
  WSGIScriptAliasMatch ^/ /location/to/your/sycamore_base/share/web/index.wsgi
  <Directory /location/to/your/sycamore_base/>
    WSGIApplicationGroup %{GLOBAL}
    Order deny,allow
    Allow from all
  </Directory>

Apache with SCGI

Open your apache httpd.conf file and add something like the following, assuming you've installed the apache SCGI module:

SCGIMount / 127.0.0.1:8882
<LocationMatch ((/wiki/.*)|favicon.ico)>
  SCGIHandler Off
</LocationMatch>

Now open sycamore_config.py and set relative_dir to '' (the empty string).

Because you're using SCGI you'll need to start the index.scgi process yourself. First, you need to modify the file.

Open index.scgi (in /path/to/sycamore_base/share/web). Delete line 35, which reads:

    WSGIServer(basic_handle_request, scriptName='/index.scgi', \
                      bindAddress=('localhost', 8882), loggingLevel=NOTSET).run()

Change it to:

    WSGIServer(basic_handle_request, scriptName='', \
                      bindAddress=('localhost', 8882), loggingLevel=NOTSET).run()

./index.scgi -d will start the Sycamore SCGI process as a daemon. You can set up Apache to automatically start the process (not sure how. please add if you know). Or you can start it up in /etc/init.d. After starting the daemon and restarting apache your Sycamore installation should work.

Apache with FastCGI

Open your apache httpd.conf file and add something like the following, assuming you've installed the apache FastCGI module:

AddHandler cgi-script cgi
AddHandler fastcgi-script fcgi
ScriptAlias / /location/to/sycamore_base/share/web/index.fcgi/
RewriteEngine On
RewriteRule ^/wiki/(.*)$ /location/to/sycamore_base/share/web/wiki/$1 [l]

Note: These directions need to be confirmed.

Now open sycamore_config.py and set relative_dir to '' (the empty string).

Because you're using FastCGI you'll need to start the index.fcgi process yourself. ./index.fcgi -d will start the Sycamore FastCGI process as a daemon. You can set up Apache to automatically start the process (not sure how. please add if you know). After starting the daemon and restarting lighttpd your Sycamore installation should work.

Lighttpd with SCGI

Make sure mod_scgi is on. Something like the following should work for you:

$HTTP["host"] =~ "(.*\.|)example\.org" {
    server.document-root        = "/location/to/sycamore_base/share/web"
    url.rewrite = (
      "^/wiki/(.*)$" => "/wiki/$1",
      "^/favicon.ico" => "/favicon.ico",
      "^/(.*)$" => "/index.scgi/$1",
    )
    scgi.server             = ( ".scgi" =>
                               ( "localhost" =>
                                 (
                                   "host" => "127.0.0.1",
                                   "port" => 8882,
                                   "check-local" => "disable",
                                 )
                               )
                            )
}

Now open sycamore_config.py and set relative_dir to '' (the empty string).

The above maps everything at example.org to Sycamore (so make sure you change example.org to your domain/IP!). Because you're using SCGI you'll need to start the index.scgi process yourself. ./index.scgi -d will start the Sycamore SCGI process as a daemon. You can set up lighttpd to automatically start the process (not sure how. please add if you know). After starting the daemon and restarting lighttpd your Sycamore installation should work.

Stand-alone HTTP server

Edit your sycamore_config.py file and set your desired values for httpd_host, httpd_port. Also change relative_dir to '' (the empty string). Then simply run share/web/index and Sycamore should work. You can use index -d to run as a daemon.

Keep in mind that if you set httpd_user to something other than the superuser you will probably not be able to set httpd_port to 80.

Logging In

Once you've installed the database, the instructions are to visit the wiki and create the user. It is a little confusing because during the db install, you are prompted for an admin username. That's OK, you still need to create the user, provide a password, and then login.

Post-install Maintenance

You may later decide to install Xapian or change from CGI to SCGI. Aside from changing your sycamore_config.py file you'll need to work with the maintenance script. See Sycamore maintenance for some information on this.

Installing on a Shared Hosting Plan

If you decide to install on a shared hosting plan through almost any server host these days (Dreamhost, GoDaddy, Apis, etc) then you'll need to change your install just a bit. Here's some tips:

• Before you go through with a host, make sure they have some great tech support to help you out - you'll need it quite a bit, especially if you need their software upgraded.
  

• Make sure you can get proper SSH Access.
  

• Make sure all the needed packages are up to date. Sycamore's dependencies are documented earlier on this page, so just make sure they have versions required of everything. If not, you'll need to get them to upgrade or try and install the needed packages in your home directory on the server.
  

• You'll have to take the /share/web/ directory and place the contents in your main public_html directory. Create an .htaccess file that reads the following:

Options +ExecCGI
Options +FollowSymlinks

RewriteEngine On
RewriteRule ^/wiki/(.*)$ /location/to/your/web/root/wiki/$1 [L]
RewriteCond %{REQUEST_URI} !(index.cgi)
RewriteRule ^(.*)$ /index.cgi/$1 [L]

DirectoryIndex index.cgi

• Make sure you set the CHMOD settings to 755 on your index.cgi file
  

• Your index.cgi file should also read the following (replace with the default, and XXX should just be the directory leading to sycamore_base):

  sys.path.extend([os.path.abspath(os.path.join(__directory__, '..', '..'))]), 
  
  sys.path.extend(['/XXX/sycamore_base'])

  
  

• the directory /sycamore_base/ does not have to be placed in public_html.

That's all I can think of for now. These were just some of the problems I had setting it up on a hosted plan, so e-mail me at morbo.somethingawful@gmail.com if you need to.

Installing Sycamore on Shared Hosting Plans

For people who have been able to get Sycamore working on a shared hosting plan, can you list which hosts (and plans) you use?

Dreamhost Shared Hosting

Sycamore running on a Dreamhost shared hosting plan. Read Installing on Dreamhost for a step-by-step how-to.

Comments:

Note: You must be logged in to add comments

2007-04-15 22:47:37   I tried to get this working under WindowsXP and had problems with some of the characters in the image filenames. After renaming those files, buildDB.py finally ran. Now I want to run it using a stand-alone HTTP server because I have no experience with Apache et al. (it's just for home use anyway). Are there any good options under Windows (like something written in Python?). —StephenDay

I've never tried getting Sycamore running in Windows, so you're entering new territory. With that in mind, there is a stand-alone HTTP server in share/web called 'index' that should work, as it's strictly python. —PhilipNeustrom

Hey, it works! None of the icons are showing though, but that is probably because the windows binary PIL installer doesn't support png(?). —StephenDay

You probably just have a path off (web_dir?) in sycamore_config.py. The icons aren't being served through PIL.

I'm getting an error when the server starts: "Could not run as user root. Terminating." Although it doesn't actually terminate... But perhaps that's why the icons aren't showing. —StephenDay

Yeah, we should check to see if someone is using Windows and if so not try and change to the httpd_user set in the configuration file. If it's showing normal pages then it should be showing icons as well. I think there is an issue in 'index' where it's trying to do some unix-style filename concatination. We should fix that so it's using the python functions for adding paths together, instead. I'm guessing that's the issue. If you view the source of a page that's rendered, where do you see 'info.png' being served from?

Here it is: src="/wiki/eggheadbeta/img/info.png"

I've submitted a patch for this on the mailing list to the sapling branch (Devjavu didn't let me). Hopefully it still works on unix... I don't have a system to test with.—StephenDay

Why are there lots of "_25"'s in the image filenames for the initial pages? It seems to cause problems under windows... why, I don't know yet.


This is the encoded form of the filename. What is the error you see?


I'm planning to have a go at a fresh install tonight. I'll let you now the error message then.

I was getting a IOError: cannot identify image file when running buildDB.py. For some reason the png and jpg files weren't recognized. When I opened and saved all files as jpgs using infranview, buildDB.py worked fine (I couldn't get png to work at all). Maybe this has something to do with my PIL version (PIL-1.1.6-py2.4-win32.egg).


The serving of static files continues to be a problem even though many of the icons are working. For example, when I click edit, the server shows a bunch of errors where the filenames of static images aren't good:

File "C:\Documents and Settings\Stephen\Desktop\sapling\share\web\index", line 53, in handle_request
static_file = open(file_path, 'rb')
IOError: [Errno 2] No such file or directory: 'C:\\Documents and Settings\\Stephen\\Desktop\\sapling\\share\\web\\wikisaplingimg\x08uttons\\plain.png'