Main repo of the ShiftSpace 1.0 project
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1878 commits behind ShiftSpace:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
builder
builds
client
config
docs
externals
images
jvm
manual
plugins
sandalphon
sandbox
scripts
server
spaces
styles
tests
.gitignore
README.txt
license.txt

README.txt

ShiftSpace (http://shiftspace.org/)
An open source layer above any website

Installation Guide
------------------

This is a text-only version of the installation guide available at:
http://shiftspace.org/manual/install.html

The same documentation should also be included with this ShiftSpace
software release inside the 'manual' directory.

This document will explain how to configure your own ShiftSpace
server. This will enable you to develop your own Spaces or hack on the
core platform itself.  If you have any difficulties along the way,
please consult one of our email discussion lists
(http://community.shiftspace.org/). If you just want to install
ShiftSpace (the client userscript) you don't need to follow these
directions, just go to ShiftSpace.org and click the install button.

For the Impatient
-----------------

   1. Unpack the files into a public web directory.
   2. Load shiftspace.php and follow directions on the page.
   3. Install the developer userscript and disable any other
      ShiftSpace userscripts.

Prerequisites
-------------

   All Systems
   -----------
   * Apache web server
   * PHP 5
       - sqlite extension
       - pdo extension
       - pdo_sqlite extension
       - json extension
   * Firefox web browser
       - Greasemonkey extension
       - Firebug extension (highly recommended)
   * Python 2.5 (untested on 3.0)
       - simplejson (http://pypi.python.org/pypi/simplejson/)

   Windows
   -------
   * Cygwin (http://www.cygwin.com/)


1. Set up your environment
--------------------------

This section will explain how to set up a development environment for
ShiftSpace on your computer. We currently have instructions for Mac OS
X and Windows. If you run Linux, or some other Unix variation, you're
kind of on your own as far as setting up your environment. But then
again you probably know what you're doing! Maybe some day we'll have
instructions for Linux too.

   Mac OS X 10.4 “Tiger” 
   ---------------------

   Mac OS 10.4 already has Apache installed -- it's just a matter of
   enabling it.  Go to the Sharing pane of the System Preferences. In
   the Services tab, enable the checkbox for "Personal Web Sharing".

   Now you just need to get PHP installed and configured. We prefer a
   pre-compiled distribution by Marc Liyanage:
   
       http://www.entropy.ch/software/macosx/php/#install
    
   Download the latest PHP module for Apache 1.3. Marc recommends
   avoiding Stuffit Expander when unpacking the installer, so
   ctrl-click it and choose "Open With" and then
   "BOMArchiveHelper.App". Double-click the file entropy-php.mpkg and
   follow the steps to install PHP.
    
   In order to get PHP running on Apache, you'll need to change its
   configuration file. Open the Terminal and enter the following:
    
       sudo nano /etc/httpd/httpd.conf

   You will be prompted for your password since you'll be editing this
   file as root. Jump to the last line of the file with the keyboard
   command ctrl-W and then ctrl-V. Add this to the very bottom of the
   file:

       Include /usr/local/php5/entropy-php.conf

   Exit from nano by pressing ctrl-X, choosing Y to save the file,
   then pressing enter to accept the previous filename.

   In order for the new PHP software to take effect you will need to
   restart Apache. You can either do this by unchecking the "Personal
   Web Sharing" checkbox from earlier and then checking it back on, or
   issuing the following command from the Terminal:

       sudo apachectl restart

   Mac OS X 10.5 “Leopard”
   -----------------------

   Mac OS 10.5 already has all the software you need. Just go to the
   Sharing pane of the System Preferences. In the Services tab, enable
   the checkbox for "Personal Web Sharing". That's it!

   Windows
   -------
    
   Currently we only have documentation for Windows XP, with service
   pack 2 installed. We'd love to hear if somebody gets ShiftSpace
   running on Windows Vista or another version of Windows, but
   (un)fortunately we currently only have access to an XP machine.

   First, go to the Apache website and click on the link "from a
   mirror" that appears below Download!. Next, scroll down the page
   and click "Other files".  Next choose "Binaries" and then
   "win32". You should see a directory listing of Windows Apache
   installers. Choose the latest 2.0.x MSI file (no SSL is fine) and
   save it to your disk.
    
   Next, go to the PHP website and click on the Downloads link. Click
   on the link for the the latest Windows installer of version 5.2.x
   and click on a suggested mirror to download from.

   Double click on the Apache installer and choose the following:

     1. Click next past the introduction
     2. Accept the license agreement and click next past the readme
     3. Accept the default settings, along with port 80
     4. Choose the "typical" settings
     5. Accept the default install folder
     6. Click the install button, then finish

   Launch the PHP installer and choose the following:

     1. Click next past the introduction
     2. Accept license and click next
     3. Accept the default install folder
     4. Choose "Apache 2.0.x module" and click next
     5. Click the browse button and find the configuration directory
        where you just installed Apache, probably 
	C:\Program Files\Apache Group\ Apache2\conf, then click next
     6. Expand the "Extensions" install option, scroll down to PDO,
        expand it, then enable the "PDO driver for SQLite". Click
        next.
     7. Click install, then finish
     
   Now you need to restart Apache so that it will be configured to
   use PHP.  From your Start menu choose All programs -> Apache HTTP
   Server 2.0.x -> Control Apache Server -> Restart.
   
   Now you should be all set up with a local Apache + PHP
   development environment, which is serving files from C:\Program
   Files\Apache Group\Apache2\htdocs.

   You will also need to install Python, we recommend a version 2.5 or
   greater. We haven't yet tested our Python scripts with version 3.0.
   You will also need to install Cygwin in order to run the shell
   scripts.
    
   Checking your installation
   --------------------------

   When you're done with those steps, load up the URL
   http://localhost/ in your browser and you should see a message
   confirming that Apache is running. To make sure you have PHP
   installed correctly, you'll want to create a new file called
   info.php in your web root. Where is your web root?

     * On Mac OS X, the web root is /Library/WebServer/Documents. You
       can also use a folder in your home directory called Sites
       (which translates to http://localhost/~your username/ in the
       browser)
     * On Windows, the web root is C:\Program Files\
       Apache Group\Apache2\htdocs.

    Once you've created the file in your public web root, add the
    following contents to it:
    
        <?php phpinfo(); ?>

    Load up the file in your browser (it should be at
    http://localhost/info.php). If PHP is working, you should see a
    bunch of configuration information and the current version of
    PHP. You'll want to look for pdo_sqlite with a SQLite version 3.x
    driver and also make sure the json extension is available.

2. Download source code
-----------------------

You have two options to download the ShiftSpace source code -- either
get the latest nightly release zip file or use Subversion to get the
files files and keep them up-to-date. The latter option is more
flexible and will allow you to commit changes back to the repository
once you've been granted a Subversion account.

    The nightly build
    -----------------

    Download a zip file of the most recent nightly snapshot from
    http://shiftspace.org/releases/nightly.zip. When you unzip the
    archive you should have a directory called shiftspace with
    everything you need inside it.

    Using Git
    ----------------

    Git is source control software that allows you to easily download
    files and, once you have them, keep them up-to-date with updates
    from other developers. It also lets you contribute code back into
    the repository and merge your changes with those of other people.

    There is a very good manual on Subversion basics available at
    http://git.or.cz/#documentation. To install the Git software,
    choose an installation package from their available packages:
    http://git.or.cz/#dowload

    By default Git is controlled through the command-line
    (terminal). There are various GUI interfaces for Subversion, which
    may make it easier to get started. Some links to several packages
    and utilities are availiable in the link above.

    Once you have Git installed, here is the repository URL that you
    can use to check out the ShiftSpace repository:
    git://github.com/ShiftSpace/shiftspace.git. To download the latest
    files with Git, here's the command to use:

        git clone git://github.com/ShiftSpace/shiftspace.git

    You should see a list of files being downloaded. If you want to
    update them in the future, just issue this command from the source
    code directory:
    
        git pull

    If you need help with Subversion, you can always use this command:

        git help

    Move files
    ----------

    Move the ShiftSpace source code directory to your public web root
    (see step 1 if you don't know where that is). You should be able
    to load up the contents of the directory in your web browser, such
    as http://localhost/shiftspace/ or http://localhost/~your
    username/shiftspace/.

3. Setting up ShiftSpace
------------------------

The final steps are as follows:

    setup.sh    
    --------
    Open up a terminal, change directories into the ShiftSpace root
    directory.  Once there run the following commands:

    > cd scripts
    > ./setup.sh

    You will be asked to give the url that you'll use when developing
    your Space.
    
    change permissions
    ------------------
    Two directories should be readable/writable by PHP. From the
    ShiftSpace root directory run the following from your Terminal.
    
    > chmod 777 builds
    > chmod 777 builds/*
    > chmod 777 client/compiledViews
    > chmod 777 client/compiledViews/*
    
    These security settings are only safe for local development
    environments. You should not run these commands in a production
    setting.
    
    These permissions will allow your interface modifications
    to appear when you refresh the sandbox page as well make it easy
    to install the developer userscript.
    
    Security
    --------
    
    There are some risks involved with leaving this directory wide
    open permissions-wise. Once you get ShiftSpace running, you should
    consider tightening up the permissions to a level where PHP can
    write to the database but that is less permissive than "777". One
    solution is to add the Apache user (usually something like "www")
    to your user's group and only allow for group write permissions.
    
    For public-facing servers, you should definitely move the
    ShiftSpace database file,
    $SHIFTSPACE_DIR/server/working/shiftspace.sqlite3, to a non-public
    directory. On Unix-like systems, it might make sense to create a
    directory /var/shiftspace that is owned by the Apache user and
    make that the location of your database file.  To change the
    location of your database file, edit the file server/config.php.

4. Developing in the sandbox
----------------------------

To start developing point your browser to the URL you used in Step 3:

   http://url/to/shiftspace/sandbox

As we are currently developing a complete overhaul of the ShiftSpace
platform the userscript will probably not work consistently for a
couple of months. However the sandbox should be adequate to develop a
space. Also, if you have an existing space that is compatible with the
current stable ShiftSpace release, the sandbox is a great way to
check that your space will be compatible with the next version. The
main source of incompatability will be with MooTools- the Subversion
branch of ShiftSpace uses MooTools 1.11, while the Git branch is on
1.2.2.

If you would like to target the current stable version of ShiftSpace,
please do a checkout of the Subversion branch.