• Getting Started

last modified March 17, 2012 by egj

 

There is a build tool that automates most the installation of a full OpenCore stack, with a consistent filesystem layout.  We strongly recommend you use this tool when building an OpenCore site.  On this page we will describe how to use that tool.

If you want to install OpenCore just to try it out or hack on it, there is an experimental buildout that may be easier to use: opencore buildout installation   We do not recommend using this method when deploying OpenCore to a production site.


Requirements

Currently only Unix-like environments are supported by the OpenCore software.

There are some system packages that must be available.  See installing on karmic for a list of packages you should apt-get before beginning; adapt that list to your OS and distribution.

You will also need a mail server like Postfix.  The build will not automate any part of that installation.


Reduction

Here's the bare-minimum set of installation instructions.  This will install OpenCore with tasks, blogs, etc.  Assuming all of the prerequisite dependencies are installed and correctly configured, the process of getting the OpenCore software installed is pretty straightforward. It consists of the following steps:

  1. Install the opencore-fassembler_boot package.
  2. Run the new-opencore-site command to bootstrap a directory structure for managing an OpenPlans deployment.
  3. Run the rebuild-opencore-site script command to launch a build of the OpenPlans software.
$ virtualenv ~/opencore-install --python=python2.4
$ source ~/opencore-install/bin/activate
$ pip install -e git+git://github.com/socialplanning/opencore-fassembler_boot.git#egg=fassembler_boot-dev
$ new-opencore-site ${site.domain.com} ${base_port} --etc_svn_repo=${etc_svn_repo}
$ cd site.domain.com
$ rebuild-opencore-site -w http://dist.socialplanning.org/build/requirements/opencore-maximal/tags/opencore-0.18.0  # (<-- enter admin pw, mysql root pw, possibly 'p' to accept ssl certificate)
$ cd builds/YYYYMMDD
$ ./bin/supervisord
Then point your browser at http://localhost:base_port/. Not so bad, eh?

Note that by default, the server on [base_port] is configured to only listen to requests from localhost; the assumption is that you will run a local proxy (e.g. Apache mod_proxy, with any number of caching layers in between) to expose the application.  If you want to connect directly, or if you are running a remote proxy, edit the {path_to_builds/YYYYMMDD}/etc/deliverance/deliverance.ini file and change the second instance of localhost to 0.0.0.0 to tell it to accept all connections.

 

Parameters to new-opencore-site

­

site.domain.com is the hostname at which you plan on making your OpenCore site available and base_port is the numeric port at which the site will be made available.  etc_svn_repo is the location of a Subversion repository where configuration files will be managed; see the section "A config SVN repository" below for details.

OpenCore actually consists of many interacting HTTP services, all exposed as one integrated site available at the base_port. Each of these services needs its own port, so you should choose a base_port that is followed by a space of available ports. At the time of this writing, OpenCore uses 8 ports, from base_port through base_port+7, although you may want to leave even more available space to support additional services that OpenCore may add in the future.

When you run the new-opencore-site command, it should return almost immediately, having created a directory named after your specified hostname. This directory will contain a sparse OpenCore site deployment skeleton directory structure, as well as an opencore.conf file.  That file contains configuration parameters which will be used by the rebuild-opencore-site command in the next step.

  

A config svn repository (AKA etc_svn_repo)

In addition to retrieving software, the OpenCore build tool uses Subversion to manage the configuration files associated with its various services. You will need to specify the URL of a working Subversion repository that OpenCore can use for this purpose.

WARNING: This configuration will contain sensitive system information, including passwords to some of the OpenCore services. The svn repository you use should NOT be available to untrusted users. If you have a full subversion installed on your deployment machine, it is very simple to use "svnadmin create /path/to/config/repo" to create a repository and then "file:///path/to/config/repo" as your etc_svn_repo URL.

 

**** 


    Running rebuild-opencore-site

    Okay, now we get to the actual meat of the process. The rebuild-opencore-site command launches a lengthy build process, which will, after a bit of time, generate a fully working OpenCore 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 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 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 opencore-maximal/tags/opencore-0.18.0
      If you run it 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 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 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:

      $ 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 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 uses supervisor to manage the various services of which it is comprised. To start the services, 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 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 site. C'est finis. :-)

     

    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 started with the 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.

    • 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 hooking up the mailing lists to postfix for instructions.  (If you have done this with a mail server besides postfix please let us know!) 
    • Set up initial database structure for WordPress -- hopefully you won't need this.  Hopefully the build will do this.  But sometimes it just fails to.

    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.


    WTF?!

    Instructions not working for you?  Let us know.

    You can email the opencore-dev mailing list.

    You can also find OpenCore developers on IRC, in the #opencore channel of irc.freenode.net.