• please leave feedback here!
   

Conventions used in this walkthrough 

Generally, instructions will be written in this font.

$ # Commands to type into your terminal will be written like this.
$ # Note the dollar sign ($) at left - that's your shell prompt, don't type that!
$
$ echo 'The output of your commands is also shown.'
The output of your commands is also shown.
$
$ # If the output is too long or is irrelevant,
$ # we'll cut it and replace it with <output> or <moreoutput>.
$ cat a-tale-of-two-cities.txt
It was the best of times, it was the worst of times...
<moreoutput>
It is a far, far better thing that I do, than I have ever done;
it is a far, far better rest that I go to than I have ever known.
$
$ # In general, when an input or output can be anything,
$ # we'll note that using <angle brackets>. For instance,
$ echo 'My favorite color is <color>'
$ # means that it's fine to type whatever color you want instead of <color>.

If you're supposed to type something specific in a textbox that isn't your terminal, we'll tell you where to type it first, then what to type. For instance, typing the following in your openplans.org search box (top right of your screen):

building openplans notes

This should get you right back to this page.

Prerequisites

 

Ubuntu

Since these are the Ubuntu install instructions, we assume you've already installed Ubuntu. Many TOPP developers do their work on Ubuntu, actually.

Notes on the terminal (for novice Linux users)

The terminal is a screen for typing in commands that is usually available on most operating systems, heavily used in Unix-based ones, and something we're going to be using a lot for this installation. You can usually get a terminal in Ubuntu by going to the menu bar and accessing Applications > Accessories > Terminal.

Note that if you're a first-time Linux user, this installation process (and later configuration and administration of the software) can be somewhat bewildering. It's definitely worth going through a good book or tutorial (Running Linux is a good one) and getting comfortable with the conventions and terminology used. The Ubuntu community is also generally very helpful to new users.

Python 2.4.4

Openplans must be built with python2.4.3 or python2.4.4 because of Zope. Python 2.4.4 is recommended. You can either change your settings so that your entire machine is set to use python2.4.4 (kind of destructive, but if you want to use python2.4.4 for everything else as well, you could) or create a new user specifically for building, running, and developing openplans and change the settings just for that user (recommended, especially for deployment builds - and actually easier). Instructions for both are given below.

Python 2.4.4 for all users (destructive but potentially convenient)

1. Check your python version. Open a terminal and type:
   
   

   $ python -V
   Python 2.4.4

2. If you get exactly the output shown above, you're almost set. Skip to the last step in this section.
   
3. If you get a message like "Python 2.5.X" or "SyntaxError: invalid syntax" or something other than "Python 2.4.4" check to see if you have python 2.4.
   
   

   ­$ python2.4
         ­Python 2.4.4 (#2, Oct  4 2007, 23:56:01)
         [GCC 4.1.3 20070929 (prerelease) (Ubuntu 4.1.2-16ubuntu2)] on linux2
         Type "help", "copyright", "credits" or "license" for more information.
         >>> ­

4. If you don't have python 2.4 (you'll get error messages instead of the output above), get it, using whatever installation mechanism you choose.
   
   In Ubuntu, Debian, and other systems that use apt-get:
   
   

   $ sudo apt-get install python2.4
   

   In Fedora, Yellow Dog, and other systems that use yum:
   
   

   $ sudo yum install python2.4

   In Gentoo, or if you're using emerge:
   
   

   $ sudo emerge python2.4

   
   For other operating systems and installation procedures, see http://python.org/download/releases/2.4.4 for downloads and installation notes.
   
   In the future, we'll use the term <installation-command> to refer to "apt-get install," "yum install," "emerge," and their equivalents in various distros and operating systems.
   
   
5. Now change your /usr/bin/python symlink to point to python2.4.
   
   
   

   $ sudo rm /usr/bin/python­
   $ sudo ln -s /usr/bin/python2.4 /usr/bin/python
   $ python -V
   Python 2.4.4 

6. Finally, make sure you change your default python version to 2.4 in debian_defaults (or the equivalent for your operating system).
   
   In Ubuntu, Debian, or other Debian-based distros: (I'm using gedit here for newbie-accessibility, but you could replace "gksudo" with just "sudo" in a terminal, and "gedit" with "emacs" or "vim" or whatever your favorite editor is.­
   
   
   

   $ gksudo gedit /usr/share/python/debian_defaults

   
   In other distros and operating systems (if you know the filepath in a different OS, please list it here!) the above will generally be this instead:
   

   $ sudo <text-editor> /usr/share/python/<default-config-filename>

   Whichever command you type to open the file, the first three lines will look something like this.

   [DEFAULT]
   # the default python version
   default-version = python2.5

   And you should edit the third line so it looks exactly like this instead:

   [DEFAULT]
   # the default python version
   default-version = python2.4
   

   Save and close the file, and you're done.
   

Python 2.4.4 for openplans user (recommended)

1. Create a new user called openplans (or whatever you like, but that's what we'll use for the rest of this tutorial). Log out and log back in as that user (you'll do the rest of the install as this user).
   
2. Check your python version. Open a terminal and type:
   
   

   $ python -V
   Python 2.4.4

3. If you get exactly the output shown above, you're done.
   
4. If you get a message like "Python 2.5.X" or "SyntaxError: invalid syntax" or something other than "Python 2.4.4" check to see if you have python 2.4.
   
   

   ­$ python2.4
         ­Python 2.4.4 (#2, Oct  4 2007, 23:56:01)
         [GCC 4.1.3 20070929 (prerelease) (Ubuntu 4.1.2-16ubuntu2)] on linux2
         Type "help", "copyright", "credits" or "license" for more information.
         >>> ­

5. If you don't have python 2.4 (you'll get error messages instead of the output above), get it, using whatever installation mechanism you choose.
   
   In Ubuntu, Debian, and other systems that use apt-get:
   
   

   $ sudo apt-get install python2.4
   

   In Fedora, Yellow Dog, and other systems that use yum:
   
   

   $ sudo yum install python2.4

   In Gentoo, or if you're using emerge:
   
   

   $ sudo emerge python2.4

   
   For other operating systems and installation procedures, see http://python.org/download/releases/2.4.4 for downloads and installation notes.
   
   In the future, we'll use the term <installation-command> to refer to "apt-get install," "yum install," "emerge," and their equivalents in various distros and operating systems.
   
   
6. Now make your own /bin directory...
   
   

   $ mkdir ~/bin

   
   
7. ...and export the system path there. The system looks in your user's personal /bin for the $PATH before it looks in the system-wide $PATH.
   
   

   $ export PATH=/home/openplans/bin:$PATH

   
   
8. Now create a symlink in your personal path to point to python2.4.
   
   

   $ ln -s /usr/bin/python2.4 ~/bin/python

svn and wget

Both subversion (SVN) and wget have to be in your execution path.

$ sudo apt-get install subversion wget 

 

installing with fassembler

 

Fassembler is the (custom, TOPP-written) software we use to build openplans. It could be general-purpose build software a la GNU Make, Buildit, et al. but is developed specifically for the build and deployment needs of the software that runs Openplans.org.

 

more prerequisites 

You'll need a lot of packages to use fassembler.

• libc6-dev
  
• libgif-dev
  
• libtiff4
• libjpeg62
• libpng3
• mysql-client
• mysql-server
  
• php5
• php5-dev
• php5-cgi (for wordpress)
• libsqlite3-dev (for cabochon)
• libmysqlclient15-dev
• libxml2-dev
• libxslt1-dev
• python-all-dev
• python-dev
• python2.4-dev (probably included in python-all-dev)
• python2.5-dev (also probably included in python-all-dev)
• python-qt3
  

1. Since mysql-server makes you set a mysql root password when it installs, we'll do that separately first.

   
   

   $ sudo apt-get install mysql-server
   

   
   You can set the root password to whatever you want, or leave it blank.
   
   

2. And then other dependencies... (warning, long paste! get the whole line and run it.)
   
   

   $ sudo apt-get install libc6-dev libgif-dev libtiff4 libjpeg62 libpng3 mysql-client python-qt3 php5 php5-dev php5-cgi libsqlite3-dev libmysqlclient15-dev libxml2-dev libxslt1-dev python-all-dev python-dev python2.4-dev       

setting up fassembler

Run the following (replace <folder-to-build-in> with where you want all the files to go. Anything you have sufficient privs for will be all right, be it /var/www/openplans or some other location of your choice.

As a side note, "/usr/local/topp/build/<date>" is the path TOPP coders typically use for development, where <date> is yyyymmdd of the present moment (for instance, April 1, 2008 is 20080401). This isn't particularly helpful unless you're doing development yourself, though.

$ ENV=<folder-to-build-in>
$ BASEPORT=10000
$ VAR=${ENV}/var 
$ svn export https://svn.openplans.org/svn/fassembler/trunk/fassembler-boot.py
$ python fassembler-boot.py ${ENV}
$ cd ${ENV}

This will fetch and install fassembler, and put you in the right directory to build.

Note the BASEPORT and VAR variables. These are both mandatory variable arguments for this build that, respectively, tell fassembler the lowest port number to use (other applications will run offset from this port - 8 ports in total) and the directory in which to put application configuration. You can change the values of these variables when running the above commands if you like.

running fassembler:topp

We must first run fassembler:topp. This creates a file (${ENV}/etc/build.ini) that is consumed by subsequently built software.

If you have commit access to the TOPP svn repository (mostly people who work at TOPP), run:

$ bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR}

If you don't have commit access to the TOPP svn repository, or want to do things locally anyway, run:

$ bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR} etc_svn_repo=file:///home/<username>/<reponame>­

This will put your files in a local SVN repository. Replace <username> with your username and <reponame> with the name you want your repository to have ("etc-repo" is usual) first. This command will create the repository (with svnadmin) if it doesn't exist yet. (You can change the location, of course - including pointing it to a svn repository hosted on another server.)

Advanced users may want to use other global variables when running fassembler:topp. (It is safe to skip the rest of this section and continue to running fassembler all if you wish.)

• db_prefix: prepends sql databases created with this prefix, as in

$ DBPREFIX=myprefix
$ bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR} db_prefix=${PREFIX}

• requirements_svn_repo: point to requirements files for each project;  e.g. https://svn.openplans.org/svn/build/requirements/releases/0.9.7.7/, as in

$ REQUIREMENTS=https://svn.openplans.org/svn/build/requirements/releases/0.9.7.7/
$ bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR} requirements_svn_repo=${REQUIREMENTS}

• etc_svn_repo: location of the base etc repo, used above in the "if you don't have commit access to the TOPP repository or want to do things locally" section.
  

(And of course instead of setting ${VARIABLES} you can just type your desired values directly into the fassembler:topp command itself, but I feel that this way is more reusable if you need to get to the same variables later on in your install.) 

 

running fassembler all

If you have commit access to the TOPP svn repository, run

$ bin/fassembler all

If you don't have commit access to the TOPP svn repository, or are doing things locally, run this (remembering to swap out <username> for your username first):

$ bin/fassembler all etc_svn_repo=file:///home/<username>/<reponame>­

The build will automatically be started. You should choose the same option (TOPP svn repository or not) that you did for fassembler:topp.

Under some circumstances, this is all you'll need. However, you may be interrupted halfway through your build by:

1. Cabochon asking for a root password - it will look something like this before it asks you for a password: cannot connect to cabochon@localhost, will try to create. If you get this message and hitting enter (effectively giving it a blank password) fails to resolve things, follow these steps to set your mysql root password as blank:
   
1. Halt the installation (Ctrl-C <enter>, then q <enter>)
2. Create a file somewhere (let's call this /path/to/my/textfile/mysql-temp-password) with the following line in it:
   
   

   SET PASSWORD FOR 'root'@'localhost' = PASSWORD('');

3. Stop mysql, start it with the file you just created as the init-file (so it will run the password creation command), stop mysql again, and restart it. You can remove the file you've created (mysql-temp-password) afterwards.
   
   

   $ sudo /etc/init.d/mysql stop
   $ sudo /usr/sbin/mysqld --init-file=/path/to/my/textfile/mysql-temp-password
   $ sudo /etc/init.d/mysql stop
   $ sudo /etc/init.d/mysql start
   $ rm /path/to/my/textfile/mysql-temp-password # optional, but a good idea.
   

4. Re-run the installation command (bin/fassembler all... etc - see above).
   
2. Further down the line, you may also get a warning that the server certificate for plone has expired. It will look something like this: 

 

          Error validating server certificate for 'https://svn.plone.org:443':
           - The certificate is not issued by a trusted authority. Use the
             fingerprint to validate the certificate manually!
          Certificate information:
           - Hostname: *.plone.org
           - Valid: from Mon, 14 Jan 2008 08:35:24 GMT until Wed, 13 Jan 2010 08:35:24 GMT
           - Issuer: Plone Foundation, Houston, Texas, US
           - Fingerprint: 39:6e:42:08:44:65:aa:7b:cb:55:85:9a:0c:0c:13:95:16:aa:38:48

Due to a bug, the last line in this warning message isn't printed out. It is actually asking you whether you want to continue or not, so at this point you should type 'p' (no quotes) and then hit Enter (to permanently accept the certificate) and your build should complete as normal.

If you get an "Installation successful" message, congratulations! You're done. 

Running openplans

Now that you've completed the installation, it's time to verify it works by starting it up.

supervisord

Openplans has a lot of components - wordpress, zope, cabochon, deliverance, fassembler, twirlip, tasktracker, transcluder, and more. (This is why we need so many ports open at once.) The program that shepherds all of these separate running processes is called supervisord. To use it, type (from within your ${ENV} directory):

$ bin/supervisord
$

That's it. If it returns with no errors, openplans is running on your machine.

 supervisorctl

To see the running processes (and start/stop them as you wish), type (again, from within your ${ENV} directory)

$ bin/supervisorctl 

and you should get something like this:

$ bin/supervisorctl
cabochon                         RUNNING    pid 508, uptime 1:11:02
deliverance                      RUNNING    pid 513, uptime 1:11:02
opencore                         RUNNING    pid 509, uptime 1:11:02
opencore-zeo                     RUNNING    pid 515, uptime 1:11:02
scripttranscluder                RUNNING    pid 514, uptime 1:11:02
tasktracker                      RUNNING    pid 562, uptime 1:10:59
twirlip                          RUNNING    pid 510, uptime 1:11:02
wordpress                        RUNNING    pid 512, uptime 1:11:02
supervisor> 

The last "supervisor> " is a prompt. You can type "help" at the prompt to see the various options available.

­

supervisor> help
Documented commands (type help <topic>):
========================================
EOF    exit  maintail  quit    restart   start   stop  version
clear  help  open      reload  shutdown  status  tail
­
supervisor> 

supervisord and supervisorctl are generally useful things when you're developing, installing, or administering an openplans stack. However, for the purposes of installation, we only care that all the components are listed as RUNNING here.

viewing your new site

The moment of truth arrives. Open up your web browser and type the following into your browser bar:

http://localhost:<baseport>

where <baseport> is the baseport you specified back in the "setting up fassembler" section (the default is 10000, or http:/localhost:10000).

(Note that http://127.0.0.1:<baseport> will sometimes not work whereas http://localhost:<baseport> will.)

You should see your shiny, newly-built site.



Congratulations.  You're done.

After your install: fine-tuning

There are several things you may want to modify in your new installation (for advanced users).

set email-confirmation False

If you're using your build for test or development, you may want to modify your settings so that your inbox will not be hammered with log messages. In your ${ENV} directory, open up etc/opencore/zope_etc/zope.conf in your favorite text editor (vim, emacs, pico, nano, or whatever you like).

$ sudo <text-editor-command> ${ENV}/etc/opencore/zope_etc/zope.conf

Look for a line that says this (towards the bottom - line 78 in the current version)

email-confirmation True

Edit it so that it look like this:

email-confirmation False

Note that you'll have to re-edit this back to "email-confirmation True" before running unit and flunc tests (only relevant if you're doing development).