Quam Plures Automated qp_install/Upgrade

Purpose

This document describes how you can automate the installation, or upgrade, of the Quam Plures blog software on a hosting account.

Intended audience

Operating environment

Quam Plures is a PHP + MySQL web application. At this point we strongly recommend the use of PHP 5 as well as MySQL 5 although Quam Plures can work perfectly fine on PHP 4.3 and MySQL 4.0.

Please see our System Requirements page for details.

Basics

Automated installation of web applications such as Quam Plures typically involves these steps:

  1. Place the application files in the destination directory.
  2. Create a MySQL User, Database and privileges of the user on the database.
  3. Write/update a configuration file with the database login information.
  4. Provide details to use when creating admin account
  5. Run the qp_install/setup script of the application.
  6. Delete the installer.

Recommended Auto Install procedure

  1. Place the application files in the destination directory
    We recommend you prompt the user for a directory to install Quam Plures into. If they provide an empty directory, Quam Plures would be installed in their web root. Let's pretend the user chose to install into www/myblog/ .
    Once the destination directory is selected/created, you need to copy all the contents from the Quam Plures package into the destination directory www/myblog/ .
    File permissions
    You should make sure that the contents of the www/myblog/media/ directory are writable by PHP. This is the place where the user can upload pictures to insert in their blog posts, etc.
  2. Create a MySQL database
    You will need to provide Quam Plures with a database where it will create its own tables.
  3. Write the configuration file
    Next you need to create/update the basic configuration file by using www/myblog/qp_config/_main_config.template.php, editing the following values and saving the result as www/myblog/qp_config/_basic_conf.php .
    You need to update the following lines with the database login info:
    $app_db_config = array(
     'user'          => 'demouser',     // your MySQL username
     'password'      => 'demopass',     // ...and password
     'name'          => 'quamplures',  // the name of the database
     'host'          => 'localhost',    // MySQL Server (typically 'localhost')
     );
    and you need to tell Quam Plures that the configuration has been done by replacing
    $app_config_is_done = 0;
    with
    $app_config_is_done = 1;
  4. Provide admin account details
    You also need to write the admin account configuration file by creating www/myblog/qp_install/_automated.php with the following information :
    <?php
    if( !DEFINED( 'QP_IS_INSTALLING' ) ) die( 'Please, do not access this page directly.' );
    $conf_admin_login = 'admin'; // this can be any value except "admin", "demouser" or "ablogger"
    $conf_admin_pass = 'demopass';
    $conf_admin_email = 'account@domain.tld';
    ?>
  5. Run the install script
    You can call Quam Plures' install script through an HTTP GET request (wget, cURL, etc..) of this form:
    http://example.com/myblogs/qp_install/index.php?locale=en-US&action=newdb&create_sample_contents=1
    Check install succeeded
    You can detect that installation has been successful by parsing the output and locating the string <--install completed-->
  6. Delete the install folder
    www/myblog/qp_install/ folder is no longer needed. We recommend you delete it, both to save space and improve security.
    Note : QuamPlures will not run if the admin account file is present. You must delete www/myblog/qp_install/_automated.php at the end of installing
    Note: when upgrading, you will need a new install folder. So there is really no point in keeping it.

Recommended Auto Upgrade procedure

Any newer version of Quam Plures can upgrade its database from any older version. It will also refuse to update if for some reason you try to "downgrade" it.

  1. Detecting which version of Quam Plures is installed
    Open the file www/myblog/qp_inc/_application.php and parse out the line that says:
    $app_version = 'something';
    The version number will always change when a new version is released.
    You can compare this version number with the new one you have available.
    Note: if using PHP, you can use version_compare() which does all the work for you.
  2. Getting confirmation that the user wants to upgrade
    You should warn the user that any customizations he may have added to his existing Quam Plures may not work properly with the new version. This especially applies to custom skins, custom plugins and custom locales (translations).
    Optionally, you may want to provide checkboxes for the following:
    • Reset templates
    • Reset plugins
    • Reset locales (translations)
  3. Replacing the files
    Delete all files & folders from the www/myblog/ except:
    • www/myblog/media/ (where the user has uploaded his content files).
    • If the user hasn't requested a reset of these, also keep:
      • www/myblog/locales/
      • www/myblog/qp_plugins/
      • www/myblog/qp_templates/
    Warning: if the user has installed into the root folder, you may not want to delete "all files & folders"! In this case, the folders you should delete are:
    • www/qp_inc/
    • www/locales/ (if requested)
    • www/qp_install/ (if it's still there)
    • www/qp_plugins/ (if requested)
    • www/qp_rsc/
    • www/qp_srvc/
    • www/qp_templates/ (if requested)
    • www/qp_view_admin/
    After that copy all files and folders from the new Quam Plures' package, except /media/.
  4. Upgrading the database
    At this point you can call Quam Plures' install script through an HTTP GET request (wget, cURL, etc..) of this form:
    http://example.com/myblogs/qp_install/index.php?locale=en-US&action=upgradedb
  5. Delete the install folder
    www/myblog/qp_install/ folder is no longer needed. We recommend you delete it, both to save space and improve security.
    Note: when upgrading again, you will need a new install folder. So there is really no point in keeping it.