Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
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.