Recent Changes Printable View Page History Edit Page

OpenShift is an IaaS (Infrastructure as a Service) platform with a free tier for development and low-intensity applications. It turns out to be very easy to get OpenBiblio up and running on OpenShift. This makes it ideal for small personal libraries, though not perhaps ready for mainstream since there is an unresolved timezone issue (see below).

Quick guide for experts

Start a new OpenShift gear with the PHP 5.4, MySQL 5.5 and phpMyAdmin cartridges installed. Install OpenBiblio into the gear with the following database_constants.php file:

define("OBIB_HOST",     getenv('OPENSHIFT_MYSQL_DB_HOST'));
define("OBIB_DATABASE", getenv('OPENSHIFT_GEAR_NAME'));
define("OBIB_USERNAME", getenv('OPENSHIFT_MYSQL_DB_USERNAME'));
define("OBIB_PWD",      getenv('OPENSHIFT_MYSQL_DB_PASSWORD'));

The application should just work. Backup and restore can be done with phpMyAdmin.

In more detail

OpenShift provides platforms known as 'gears' for hosting web applications. Each gear has its own domain name composed of the name of the gear chosen by the user and the username, thus for example <gearname>-<username>.rhcloud.com. Components known as 'cartridges' can be added to a gear to give it more functionality. In the free tier, users can deploy up to three basic gears. A gear is actually a virtual Fedora Linux server running on top of Amazon Web Services, albeit with constrained functionality. Users can log into their gears using ssh and transfer files using scp. Alternatively, access and file upload can be handled by rhc, a command-line tool provided by RedHat. The preferred customisation route uses GIT:

  • clone the app into a local copy;
  • make modifications, add and remove files;
  • commit the changes locally, then push the changes into the app.

Note that GIT has a staged commit and upload procedure: changes are first committed locally, then pushed onto the server.

Working with OpenShift presumes some familiarity with unix. In particular I have found that managing an OpenShift application is best done from within a unix environment, such as one of the flavours of GNU/Linux. Also, to execute all the steps below, some kind of authentication is likely to be required. You may need to make sure you have an SSH key pair set up, as described in the OpenShift documentation.

After signing up to OpenShift and sorting out the authentication, the first step to getting OpenBiblio up and running is to launch a new gear. Choose one with an appropriate PHP cartridge installed, and once it is up and running you can add the MySQL and phpMyAdmin cartridges. Now check that you can see your application by pointing a web browser to https://<gearname>-<username>.rhcloud.com/.

The next step is to install OpenBiblio into the gear. To do this, first clone the gear using rhc git-clone <gearname>. From a clean start, this will create a directory on your local machine with the same name as the gear, and containing a placeholder index.php file. Next, download and unpack OpenBiblio into this directory. This will create an openbiblio subdirectory. Edit the database_constants.php file in this directory to match the above. This lets OpenBiblio authenticate to the database using credentials derived from the appropriate OpenShift environment variables. Note that there is only one database per gear that is user-accessible and it has the same name as the gear itself. Now use GIT to add the files, commit and upload the changes: git add -A; git commit -m "openbiblio added"; git push. There is a short wait whilst OpenShift restarts the application.

At this point if you now browse to https://<gearname>-<username>.rhcloud.com/openbiblio/install/ you should be at the database table installation step (there are no tables created yet). Most likely you will also see a complaint about a time mismatch error between PHP and MySQL. This is a reflection of the wider timezone problem (see below). It is not necessary to fix this to proceed.

Adding data

Once you are at the database table installation step, you can simply go ahead and have OpenBiblio create default database tables. However if you want to populate the tables with data from somewhere else, for example from a pre-existing server, it is probably better to add the data first. If you have installed the phpMyAdmin cartridge, this can be done by browsing to https://<gearname>-<username>.rhcloud.com/phpmyadmin/. Be prepared to authenticate with the database credentials that were provided at the time the MySQL cartridge was added. If you did not make a note of these, they can be found by signing into the OpenShift website and browsing to the named gear under the Applications tab. Do a mysqldump of the database you want to copy, and use phpMyAdmin to import the resulting SQL file.

Alternatively, it is possible to use scp to copy the SQL file into the gear itself. It is best to put this kind of thing into ~/app-root/data/. Then use rhc ssh <gearname> to start a login shell in the app itself, do cd app-root/data and run mysql sourcing the SQL file.

Finishing up

At this point if you browse to https://<gearname>-<username>.rhcloud.com/openbiblio/ you should be at the home page of the OpenBiblio installation, and ready to go.

Guests can browse the library through an OPAC at https://<gearname>-<username>.rhcloud.com/openbiblio/opac/

You might want to delete the install directory and associated files from the server. The easiest way to do this is to delete the files from the local directory, and use GIT to commit and push the changes onto the server. It's also possible, if you prefer, to move all the files from the openbiblio subdirectory into the top level directory for the gear. This shortens the above pathnames by removing the openbiblio component of the web addresses.

The timezone problem

In the install step, you might notice that PHP and MySQL are not set to the same timezone (or at least, it's unlikely they will be): PHP is likely set to the GMT timezone (ie UTC, or unix time), and MySQL is likely set to the SYSTEM timezone. The latter depends on where the virtual server thinks it is (it is probably on Eastern time). It's very difficult to access the configuration files in OpenShift to fix this. This arises from the constrained functionality that goes with an IaaS platform. One can access a local timezone variable in MySQL using phpMyAdmin and set it to +0.00 (ie GMT). I'm not sure if this permanently fixes the mismatch problem though, and in any case it doesn't solve the problem that the server is likely in the wrong timezone for the app.

This is all symptomatic of a wider problem. The best solution would be to extend the OpenBiblio Library Settings to include a timezone variable. Then, all internal calculations can use UTC (unix time) and all dates/times reported to the user would be converted at the last moment to the required timezone. The timezone variable can be stored in the library settings table in the database, and the time/date conversions can be done in PHP using existing packages.

Other suggestions of how to handle this are welcomed!

Patrick Warren

SourceForge.net Logo
Edit Page - Page History - Printable View - Recent Changes - Search
Page last modified on April 13, 2014, at 02:05 PM