Running rebuild-opencore-site

Okay, now we get to the actual meat of the process. The rebuild-opencore-site command newbuild.sh script launches a lengthy build process, which will, after a bit of time, generate a fully working OpenCore OpenPlans installation, ready to be launched and to start accepting requests. You can go get a snack, but you shouldn't wander too far because you will be prompted for a bit more information during the process. Here's how you invoke the command:

$ cd site.domain.com $ rebuild-opencore-site ./newbuild.sh requirements_directory

1. In the above command, requirements_directory is the name of a subversion directory containing files that specify all of the underlying dependencies of the OpenCore software. OpenCore OpenPlans software. OpenPlans has a number of different build configurations, this parameter allows us to easily choose between them. The simplest choice for getting started is the following:

    
   
   rebuild-opencore-site 
   
   $ ./newbuild.sh opencore-maximal/tags/opencore-0.18.0

   If you run it newbuild.sh with no arguments, you will see a list of the available requirements directories. You can also use a full http(s):// URL as the requirements_directory argument, if you have a profile stored outside of TOPP's svn repository.
   
   NOTE: If you want to try out the older Plone 2.5-based OpenPlans stack, you can use the following invocation.

    
   
   rebuild-opencore-site 
   
   $ ./newbuild.sh openplans/branches/plone25

   After executing newbuild.sh, there will be a short delay as initial requirements are downloaded. Eventually you will be prompted for an admin password that will protect your OpenCore OpenPlans installation. You can enter a password of your choosing (twice), or you can simply hit 'Enter' to autogenerate a random password. In either case, the password will be stored in an admin.txt file that you can refer to later.
   
   The next thing you will be prompted for is the MySQL root password. This is needed because OpenPlans will be creating a number of MySQL databases to support some of its services.
   
   There's one more issue that may arise: some of the software is downloaded from the Plone subversion repository, which is protected by an unsigned SSL certificate. If you have never connected to this repository, then you will be prompted about the certificate, and given a chance to accept or reject it. If this happens, we recommend you hit 'p' to 'p'ermanently accept the certificate . Warning: due to a bug, you might not see this prompt. If the build seems stuck, just hit 'p' and see if that gets things moving again :-)
   
   Or you can avoid this prompt altogether by running the following command before running rebuild-opencore-site: newbuild.sh:
   
   

   $ svn ls https://svn.plone.org/svn/plone

   This will also prompt you to accept the certificate, if you haven't already done so; if you choose 'p' at this point, then it will not come up again while running the build.
   
   That's it! Assuming that all of the prerequisites are configured and available to the build process as needed, then your build will complete and you will have a fully functional OpenCore OpenPlans installation. Your build will live within the 'builds' directory, in a subdirectory named after the current date. Let's fire it up!
2. Start the supervisor daemon: OpenCore OpenPlans uses supervisor to manage the various services of which it is comprised. To start the services, OpenPlans, then, you use the following commands:
   
   

   $ cd builds/YYYYMMDD $ ./bin/supervisord

   This starts the supervisor daemon. You can examine the processes that are being managed using:
   
   

   $ ./bin/supervisorctl status

   You would also use 'supervisorctl' to stop, start, and restart the services, either individually (by service name, e.g. 'supervisorctl restart opencore') or as a whole (using 'supervisorctl restart all'). If you want to shut down the entire rig, including the supervisor daemon itself, use:
   
   

   $ ./bin/supervisorctl shutdown

3. Use the OpenCore OpenPlans site: Assuming you haven't stopped or shutdown the services, you should now be able to point a web browser at http://localhost:base_port and immediately start using the OpenCore OpenPlans site. C'est finis. :-)

GraduationLink: #outline-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 save 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.exampleLink: http://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.exampleLink: http://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.exampleLink: http://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.
• db_prefix:Wordpress and some other parts of the system may need to have MySQL databases initialized. The db_prefix will be used as the initial part of the database name. You can override this if you care what your databases are named.
  
• 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.comLink: http://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.

Disabling Mail Confirmation

One thing you may wish to tweak is whether or not new users are required to confirm via email when joining the site. This is turned on by default, but can be annoying when just testing a new build for development purposes. Edit the file etc/opencore/zope_etc/zope.conf, look for a line that says "email-confirmation True", and change that to read "email-confirmation False". Save that file. Then you can restart opencore, by running eg. "bin/supervisorctl restart opencore".

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 

Once you've gotten the whole thing installed, you might want to skim getting ((getting started with the codeLink: /projects/opencore/getting-started-with-the-code code)) for some useful tips about coding in & around OpenCore.

One-Time Tasks

There is some setup that you will need to do manually. Generally you only need to do these things once on a new server, or for a new site.

• Set up initial database structure for WordPress
  

Do this after you have successfully run a build. During the build's wordpress installation, you will get the following error message:

== Delete extra rows in wp_site == Error: (1146, "Table 'my_doman_wordpress.wp_site' doesn't exist") 

Press `c` to ignore this error and continue the build; it will not affect the rest of the build.

Wait for the installation to finish, and then hit wordpress's 'dbsetup.php' script with an HTTP POST request. You will need the shared secret; include it in the POST.

• Install a mail server

You will need a mail server running. It is assumed to be running on the same server as your OpenCore installation. It is assumed to be running on port 25 with no login. If these assumptions are not correct, you will need to edit your build's maildrop configuration.

• Hook up the mail server to the mailing lists

You need to tell your mail server to route incoming messages to the mailing list application (Listen). See http://www.coactivate.org/projects/listen/installation-instructionsfor details - "if you would like to be able to setup arbitrary lists" section.

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 OpenCore developers on IRC, in the #opencore channel of irc.freenode.net. Link: http://irc.freenode.net/

Link: #outline-graduation