Newscoop 4 for Journalists and Editors

Backup and upgrade

Before upgrading a running server to the latest version of Newscoop, it is strongly recommended that you back up your publication database, theme templates, images, file attachments and configuration files. First, log in to the administration interface (see the Getting started chapter in this manual for details). Click on Actions in the main navigation menu. At the lower end of this menu, click Backup/Restore.

Making a backup

On the Backup/Restore page which opens, click the Make new backup link next to the blue plus icon.

A dialog box will ask you if you are sure you want to make the backup.

 

Click the OK button, and a pop-up window will display the progress of the backup.

 

Once the window reports Backup saved to file: you can click the Close link to return to the Newscoop administration interface. On the Backup/Restore page, the backup you just made should be listed, together with any previous backups.

Click on the disk icon in the Download column to save the gzipped backup tarball (with the .tar.gz file extension) from your Newscoop server to your desktop computer.

Restoring from backup

To restore from a previous backup file into another Newscoop system, click the Upload backup file link, and then select the backup from your desktop computer's file system.

Then, click the life preserver icon to restore from one of the listed backups. You will be warned that current publication and theme data will be overwritten by versions in the backup file, so you should make sure you have a backup of current data before continuing.

 

After the restore is complete, you should restart the Apache web server, for example on Debian or Ubuntu using the command:

sudo invoke-rc.d apache2 restart

When moving Newscoop data between servers, you may have to change the default publication alias to match a new domain name. 

Command line backup

Newscoop includes two scripts that can be used for backup and restore on the command line of your server. They are found in the bin/ subdirectory of your Newscoop installation, such as /var/lib/newscoop/bin/ or a similar location. Because these scripts require access to your Newscoop configuration files, they must be run as the root user (with sudo on Ubuntu).

You can create a backup archive using the following command:

sudo /path/to/newscoop/bin/newscoop-backup [--silent] [--default-dir] [--help]

The optional arguments to the newscoop-backup command are:

  • --silent - don't display any message, whether successful or not
  • --default-dir - save the backup archive in the backup directory /path/to/newscoop/backup ; without this argument, the script will create the Newscoop backup archive in the current directory
  • --help - display usage information

The output of the command should resemble the following example:

sudo /var/lib/newscoop/bin/newscoop-backup --default-dir

Newscoop Backup Utility
-----------------------
Backup script version: 4.0
Backing up newscoop

Available disk space is 4.34 GiB.
The actual necessary space depends mostly on size of your database and multimedia files.
If the backup does not succeed, try to create more free space, please.

 * Backing up the database...done.
 * Backing up the themes...done.
 * Backing up images...done.
 * Backing up file attachments...done.
 * Backing up configuration files...done.
 * Creating tarball...done.
 * Cleaning up...done.

Backup saved to file:
  /var/lib/newscoop/backup/backup-newscoop-2012-04-03-14-29-41.tar.gz

The archive file name is backup-newscoop-[date_time].tar.gz and this tarball contains the whole Newscoop instance: the database, theme templates, images, attached files and configuration files. You can find the size of the backup archive with the ls -lh command, for example:

ls -lh /var/lib/newscoop/backup
total 26M
-rw-r--r-- 1 root root 26M 2011-06-22 16:21 backup-newscoop-2011-06-22-16-21-12.tar.gz

To restore from a specific backup archive, use the command:

sudo newscoop-restore -b backup_file [-t destination_database_name] [-e] [-c charset] [-s] [-l] [-f] [-h]

The -b backup_file argument is used to provide the full or relative path to the tarball previously created by the newscoop-backup script. For example:

sudo /var/lib/newscoop/bin/newscoop-restore -b /var/lib/newscoop/backup/backup-newscoop-2011-06-22-16-21-12.tar.gz

Newscoop Restore Utility
------------------------
 * Initializing...
   * Temp directory: backup-newscoop-2011-06-22-16-21-12
   * Initialization done.
 * Extracting files into temp directory...done.
 * Backup database name is 'newscoop'.
 * Destination database name (to be replaced) is 'newscoop'.

 All files in the following directories will be deleted.
 (The backup files will be copied to these locations)
    /var/lib/newscoop/templates
    /var/lib/newscoop/images
    /var/lib/newscoop/files
    /var/lib/newscoop/templates_cache
 Are you sure you want to continue? (y/N) y
 * Removing files in /var/lib/newscoop/templates...done.
 * Removing files in /var/lib/newscoop/images...done.
 * Removing files in /var/lib/newscoop/files...done.
 * Removing files in /var/lib/newscoop/templates_cache...done.
 * Restoring templates...done.
 * Restoring images...done.
 * Restoring file attachments...done.
done.
 * Upgrading templates...done.
 * Restoring the database newscoop...done.
 * Upgrading (if necessary)...
    * Upgrading the database from version 3.5.x...done.
 * Updating plugins (if necessary)...   done.
 * Cleaning up...done.

IMPORTANT!
You must restart the apache server for the changes to take effect!

The optional arguments to the newscoop-restore script are:

  • [-t destination_database_name] If provided, the script will use the database name specified instead of the one specified in the backup file. This is useful for transfer of a Newscoop publication to another server, where database names may be different.
  • [-e] Use the existing configuration files instead of the ones in the backup file. The existing configuration files in the current installation will not be replaced. This argument takes precedence over the -t argument; if both arguments are used together, the database name will be read from the existing database configuration file, not from the -t argument.
  • [-c charset] Convert the data from charset to UTF-8.
  • [-s] Convert the data from the database server character set to UTF-8.
  • [-l] List all available character sets and exit.
  • [-f] Don't prompt, assume 'yes' to questions.
  • [-h] Display usage information.

The newscoop-restore script will replace all existing data with the contents of the backup archive. You must run the script from a directory that you have write access to, because this script needs to create a temporary directory. Note that your backup database and files will automatically be upgraded if they are older than the currently installed version of Newscoop.

Finally, restart Apache as suggested by the message from the newscoop-restore script.

sudo /etc/init.d/apache2 restart
 * Restarting web server apache2
 ... waiting                                                  [ OK ]

With multiple installations of Newscoop on a single server, you must run the newscoop-restore script from the installation where you want to restore the matching data. For example, you may have installed Newscoop in two locations, /var/www/newscoop1 and /var/www/newscoop2. To restore the data for the newscoop1 installation, you must run /var/www/newscoop1/bin/newscoop-restore rather than the /var/www/newscoop2/bin/newscoop-restore script.

Running the upgrade script

After you have completed the backup successfully, update your Newscoop installation using either the automated or manual methods described in the following chapters. If using the manual installation method for an upgrade, the existing files in the Apache DocumentRoot folder (such as /var/lib/newscoop/) should not be removed first, unless you wish to perform a clean install.

Any changes that you have made to the sample themes supplied with Newscoop will be overwritten on upgrade. For this reason, you should rename the theme in the theme.xml file before upgrade, if you wish to keep those changes. See the Newscoop Cookbook technical manual for more details on how to create themes.

When the new files are copied over the existing Newscoop installation, your publications will automatically be taken offline, and a maintenance message will be displayed to your readers.

Next, check the .htaccess file in the DocumentRoot folder, particularly if you have made custom modifications to this file in a previous installation. When upgrading from Newscoop 3.5.x to 4.0.0 or later, you will need to replace the line:

RewriteCond %{REQUEST_URI} !/+templates

with the line:

RewriteCond %{REQUEST_URI} !/+themes

due to the renaming of the templates directory to themes. You should also check that the line:

RewriteCond %{REQUEST_URI} !(/+plugins/[^/]*)?/+javascript

has been replaced by:

RewriteCond %{REQUEST_URI} !(/+plugins/[^/]*)?/+js

due to a directory name change from javascript to js in version 3.5.3.

Then you should run the upgrade.php script in your web browser, for example:

http://www.example.com/upgrade.php

Once the upgrade is complete, your publications will automatically be put back online.