This is a static copy of the main wikispot.org site, preserved for historical purposes only. Please see this page for more information.

How to Install

 InfoInfo TalkTalk
Search:    

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

Requirements

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

Optional Libraries

Getting Sycamore

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

If you have no idea what SVN is, go to [WWW]http://subversion.tigris.org/ first. If you are also a Windows user, [WWW]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:

Setting up your database

If you're using MySQL issue the command:

then something like this:

If you're using PostgreSQL issue the command:

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

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 [WWW]Apache or [WWW]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 [WWW]SCGI process (the file index.scgi in share/web), or it can run as a [WWW]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:

Apache with mod_wsgi — UNTESTED
This is unverified — if this configuration works for you then please remove this message!

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: 

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

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 

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'
This is a Wiki Spot wiki. Wiki Spot is a 501(c)3 non-profit organization that helps communities collaborate via wikis.