Introduction (wherein we learn the answers to a number of pressing questions)

Reduction (wherein we list the installation steps w/o all of the extraneous mess)

Those instructions seem more daunting than they actually are. If we remove all of the (hopefully) helpful extra information and reduce it to the commands that you need to enter, it looks like this:

$ easy_install-2.4 https://svn.openplans.org/svn/OpenplansBoot/trunk
$ new_openplans_site site.domain.com  base_port  # (<-- enter config svn repo URL)
$ cd site.domain.com
$ ./newbuild.sh openplans/trunk  # (<-- enter admin pw, mysql root pw, possibly 'p' to accept ssl certificate)
$ cd builds/YYYYMMDD
$ ./bin/supervisord

Or, if you want a Plone 3-based installation:

$ easy_install-2.4 https://svn.openplans.org/svn/OpenplansBoot/trunk
$ new_openplans_site --use-plone3 site.domain.com  base_port  # (<-- enter config svn repo URL)
$ cd site.domain.com
$ ./newbuild.sh openplans/branches/plone30  # (<-- enter admin pw, mysql root pw, maybe 'p' to accept ssl certificate)
$ cd builds/YYYYMMDD
$ ./bin/supervisord

Then point your browser at http://localhost:base_port/. Not so bad, eh?

Graduation (wherein we learn about configurability and tweakage)

Chances are good that, if you're going to manage a few different OpenPlans installations, you're going to use a single configuration repository for all of your configuration sets. It's a bit annoying to have to interactively enter the svn repository URL each time you run the new_openplans_site command. Luckily (you can probably see where this is going...) you don't have to. OpenplansBoot provides a bit of configurability to let you specify some specific build parameters ahead of time, and to persist them so that different installations will share certain attributes. This section gives a brief overview of how you can twiddle some knobs.

Creating the newsite.ini file

When you easy_install the OpenplansBoot package, Python installs an "egg" into your Python environment. This egg is really just a directory, containing the package's Python code, as well as certain metadata associated with the package. It's beyond the scope of this document to go into too much detail, but this egg directory can usually be found in your Python environment's lib/python/site-packages directory. It will have a name similar to "OpenplansBoot-0.1dev_r16550-py2.4.egg" (the version number and revision number may vary, obviously). If we call this directory the egg_root, then you should be able to find a sample configuration file at egg_root/openplansboot/newsite.ini.example. This file will contain some sample configuration settings for new builds. The example file has no effect, however; in order to actually impact your builds, you need to 'cp newsite.ini.example newsite.ini' and then tweak the settings in newsite.ini to your liking. If the newsite.ini file exists in this location, it will be used by the new_openplans_site command when bootstrapping the deployments.

What settings can I change?

You should refer to the newsite.ini.example file for a complete description of what settings are available to you and what effects they have. I'll describe a couple of the more useful ones here to get you started:

• base_dir: At TOPP, we keep all of our OpenPlans deployments in a single location on our servers. If the base_dir variable is set, then new_openplans_site will create the deployment skeleton in the specified location, instead of in the current working directory.
• req_user: Similarly, TOPP uses a single user account to manage a single OpenPlans installation. If req_user is set, then both new_openplans_site and the generated newbuild.sh file will check the current user id and will exit with an error if it does not match the specified req_user.
• extra_path: Sometimes certain tools that the OpenPlans build needs access to live in places that are not on a standard user's execution path. Any specified extra_path value will be appended to the current user's execution path for use during the build process. Multiple extra paths should be separated by a colon (":") as is standard for the PATH shell environment variable.
• force_ssl: OpenPlans has support for forcing all logins and password changes to be forced through a secure SSL connection rather than the standard unencrypted HTTP. However, getting this to work depends on having a correctly configured SSL server in front of the OpenPlans installation; OpenPlans itself doesn't handle SSL handshaking. If you know that your deployment will have an SSL front-end and you want to activate this feature, set force_ssl to 'True'. NOTE: It is also possible to change this as a per-build setting later, so don't worry if you want to get started without it, you won't be locked in.
• etc_svn_repo: This is the variable that specifies the configuration repository URL. If this is set, you will not be prompted to enter the URL when you run new_openplans_site.
• etc_svn_prefix: If many developers are sharing a single configuration repository, it's possible that there will be namespace collisions between their installations. If two people use 'test' as the name of their deployment, then the OpenPlans build will get confused and will try to use the same configuration checkout for the two distinct installations. When you set the etc_svn_prefix variable, the OpenPlans build will add the specified string prefix to all of your configuration checkins, greatly reducing the chance of conflicting with someone else.

It should also be noted that ALL of these settings, and any others that are supported by newsite.ini, can also be entered on the command line. For instance, if you want to place one single OpenPlans deployment in a different location than the rest, and to force it to use SSL when usually you do not, then you could use the following invocation:

$ new_openplans_site site.domain.com base_port base_dir=/path/to/special/place force_ssl=True

Any setting that is specified on the command line will override the same setting specified in the newsite.ini file.

What about the MySQL root password?

The only remaining piece of information that you have to enter interactively for a new deployment, but which is unlikely to change very often, is the MySQL root password. Because this is a particularly sensitive piece of information, we did not add support for it in the newsite.ini file, nor do we allow it to be entered on the command line. If you don't want to enter this every time, then you will want to create a file named .mysql-root-pw in the home directory of the user that is running the newbuild.sh command. This file MUST be chmod 600, i.e. not readable by other users on the system. If the file exists but is not chmod 600, then the OpenPlans build will exit with an error.

Dysfunction (wherein we learn what to do if things go horribly wrong)

Despite all of our careful preparation and instruction, it is, alas, an imperfect world, and you may find that things do not work as smoothly as intended. What should you do to recover, and/or to get assistance if you don't understand what's going wrong?

D'oh

We'll start with the easier case. What if you're running a build using newbuild.sh, and it fails for an obvious reason, like (for instance) that you forgot to start the MySQL server before running the build. You start the server up, and aren't sure where to go next. You could re-run the newbuild.sh script... but that would start a new build in builds/YYYYMMDD-1, instead of completing the earlier build. If you want to try to pick up the original build where it left off, you can run the following commands:

$ cd builds/YYYYMMDD
$ source fassembler/bin/activate
$ fassembler missing 

This should restart the build where it left off. When it's complete, use the following commands to reset your Python environment and start up OpenPlans:

$ deactivate
$ ./bin/supervisord 

WTF?!

Unfortunately, some problems may not have an immediately obvious solution. In fact, you may not have any idea at all what's going on. In that case, OpenPlans developers may be able to help you past your hurdles. There are two primary mechanisms for getting support from the OpenPlans developers. The first is via the opencore-dev mailing list. This is a very active mailing list that is used by all of the primary OpenPlans developers. It is strongly recommended that anyone who is using the OpenPlans software be subscribed to this list in order to keep up with what's going on in OpenPlans development. It is also a fine place to ask questions. Please make sure you include lots of information about the specific problem you're having, including your underlying platform and any error messages that you might be seeing. You may find some help with how to formulate a helpful question here.

You can also find the OpenPlans developers on IRC, in the #openplans channel of irc.freenode.net. Again, this is a very active channel that is used almost daily by the OpenPlans developers. Most of us are in the U.S. and are on-line during the workday, so please plan accordingly if you're in another part of the world and are trying to reach us.