QuickStart

If all you care about is building the OpenPlans stack on your computer and you feel lucky,  you can probably get by with a minimal number of commands

ENV=~/fsm.env
BASEPORT=10000
VAR=${ENV}/var
svn export https://svn.openplans.org/svn/fassembler/trunk/fassembler-boot.py
python fassembler-boot.py ${ENV}
cd ${ENV}
bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR}
bin/fassembler all
bin/supervisord # start all services

For more explanation, please see below.

A more detailed walkthrough geared towards beginners and based on this page is also available here:

http://www.openplans.org/projects/opencore/building-opencores-notes   

Forward

The goal of this HOWTO is to get a fresh openplans stack build using fassembler. Currently, these instructions are incomplete:

 15:15 < magicbronson> oh, k0s, did you remember to set wordpress_uri and
                      blog_uri in the opencore_properties sheet in the zmi???
15:15 < magicbronson> k0s: that's still a manual step. RaFromBRC is working on
                      automating it
15:16 < k0s> magicbronson: no, i sure didn't do that!
15:16 < magicbronson> k0s: that's what's wrong then!

 

Jeff: I just checked something in to address this, see http://trac.openplans.org/openplans/ticket/2083

-- Josh

Currently, this HOWTO expresses only the opinions of its author and may not reflect the intent of the author of fassembler (ianb) or of other members of The Open Planning Project.  I welcome additions and changes that reflect more up-to-date usage of fassembler or associated software, but please do not change things because you believe your methodology is better than mine without consulting with me first (unless [ "$(whoami)" == "ianb" ] ).  I don't have to be right, but please discuss how I'm wrong before editting.  Thanks!

Getting fassembler

The easiest way to get fassembler is to download and run the fassembler-boot script:

ENV=~/fsm.env
svn export https://svn.openplans.org/svn/fassembler/trunk/fassembler-boot.py
python fassembler-boot.py ${ENV}


This will create a fassembler environment in ${ENV}, with the fassembler program at ${ENV}/bin/fassembler and the source at ${ENV}/fassembler/src/fassembler/

 

Using fassembler

Preliminaries:

• make sure you don't have any services running on the ports you will be using!  At the time of this writing this is (by default) base_port to base_port + 7, though up to date info is found in your fassembler source docs/ports.txt file (or should be)
• make sure all the necessary system libraries and applications are installed (e.g. MySQL, etc).  See Platform-specific Notes [below]
  

• make sure old supervisord is stopped
  
   

Building: 

The general format of how to use  fassembler is as follows:

fassembler <project> [project]... [variable=value] [variable2=value2]...

 The first thing that must be built is fassembler:topp, which is kinda a base-line meta-project with configuration for the subsequent builds:

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

base_port and var are both mandatory variable arguments for this build.  base_port tells fassembler the lowest port number to use (other applications will run offset from this port), and var indicates the directory in which to put application configuration.

Other global variables useful for fassembler:topp:

• db_prefix: prepends sql databases created with this 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/
  
• etc_svn_repo: location of the base etc repo
  

fassembler:topp creates a file, ${ENV}/etc/build.ini, that is consumed by subsequently built software.   

Once you have done fassembler:topp, you may build the stack.  The easiest way to do this is

bin/fassembler all

Note: if you don't work at TOPP, and probably don't have commit access to https://svn.openplans.org/svn/ , you need to tell fassembler to put your configuration files in a different svn repository.  You should use:

  bin/fassembler fassembler:topp base_port=${BASEPORT} var=${VAR} etc_svn_repo=file:///home/user/etc-repo

This will put your files in a repository located at /home/user/etc-repo, and will create the repository (with svnadmin) if it doesn't exist yet. 

 

How do I control which branch or tag of a particular component gets built?

Make a branch or tag copy of the requirements files at https://svn.openplans.org/svn/build/requirements , edit the files as necessary, and then use the requirements_svn_repo argument to fassembler as described above.

If you need to revise the requirements later, the build places these files in ${ENV}/requirements. You can edit and commit from there.

Starting the Services:

Services are started and monitored with supervisor.  Launching supervisord starts all the services:

$ bin/supervisord

You can check on the status of the services with

 $ bin/supervisorctl status

 

Stopping the services: 

 To create a completely fresh build with the same ports, it is necessary to stop the running services first:

 $ bin/supervisorctl shutdown

 

Platform-specific Notes:

- on Macintosh make sure you have the latest version of Xcode

- on Ubuntu you need libc6dev; giflib, libtiff, libjpeg, and libpng for PIL; mysql-client and -server, php5, php5-dev, and php-cgi for wordpress; libsqlite3-dev for cabochon.

- on Mac OS X you need a newer version of libxml (grab the latest at xmlsoft.org) for deliverance and opencore's lxml dependency.

WordPress requires PHP 4.2 or greater and MySQL 4.0 or greater, and any web server that supports them (we use Apache).  You must also install the php5-cgi package on Ubuntu (or on another OS, whatever provides the php executable).

PHP: 

- Mac OS X 10.4 comes with Apache 1.3.33 + PHP 4, but its PHP is barebones and does not have a necessary required module (hash) compiled in. You can try installing a better Apache + PHP, but this has not yet been tested.

- Mac OS X 10.5 comes with Apache 2.2.6 + PHP 5.2.4 with a respectable list of modules compiled in. This should just work out of the box.

 

MySQL:
- Ubuntu: You will need to have the dev library for libmysqlclient installed in order to have mysql_config, needed by fassembler-boot.py.  On Jeff's machine, this is libmysqlclient15-dev 

- Mac OS X 10.5: see Installing MySQL on Mac OS X (MySQL AB have not yet released a Leopard-compatible installer so you have to build your own)

- Mac OS x 10.4: just grab the latest MySQL installer from mysql.com

 

Several of our Pylons apps require MySQL-Python. Unfortunately there is a known bug in the code that they have not yet fixed, so easy_installing MySQL-Python on OS X 10.5 will fail. MySQL-Python and Apple OSX 10.5 (Leopard) describes the fix, which has been applied to https://svn.openplans.org/eggs/MySQL-python-1.2.2.tar.gz and built out into https://svn.openplans.org/eggs/MySQL_python-1.2.2-py2.4-macosx-10.3-i386.egg, so "easy_install -f https://svn.openplans.org/eggs MySQL-Python" will fix this on Leopard. OS X 10.4 and I think other platforms are unaffected.