Newscoop 4.4 for Journalists and Editors
Backup and upgrade
If your Newscoop server is hosted by Sourcefabric, routine backups and upgrades will be taken care of by the Newscoop team, so you do not need to read this chapter.
Before upgrading your own 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 sub-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 with the Browse buton.
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/www/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).su
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/www/newscoop/bin/newscoop-backup --default-dir Newscoop Backup Utility ----------------------- Backup script version: 4.4.4 "Richard" 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 videos...done.
* Backing up PDFs...done.
* Backing up configuration files...done. * Creating tarball...done. * Cleaning up...done. Backup saved to file: /var/www/newscoop/backup/backup-newscoop-2015-07-01-13-04-31.tar.gz
The archive file name is backup-newscoop-[date_time].tar.gz and this tarball contains the whole Newscoop instance other than core files: 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/www/newscoop/backup total 26M -rw-r--r-- 1 root root 26M Jul 1 13:04 backup-newscoop-2015-07-01-13-04-31.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/www/newscoop/bin/newscoop-restore -b /var/www/newscoop/backup/backup-newscoop-2015-07-01-13-04-31.tar.gz Newscoop Restore Utility ------------------------ * Initializing... * Temp directory: backup-newscoop-2015-07-01-13-04-31 * 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/www/newscoop/themes /var/www/newscoop/images /var/www/newscoop/public/files /var/www/newscoop/cache
/var/www/newscoop/public/pdf
/var/www/newscoop/public/videos
Are you sure you want to continue? (y/N) y * Removing files in /var/www/newscoop/themes...done. * Removing files in /var/www/newscoop/images...done. * Removing files in /var/www/newscoop/public/files...done. * Removing files in /var/www/newscoop/cache...done. * Removing files in /var/www/newscoop/public/pdf...done. * Removing files in /var/www/newscoop/public/videos...done. * Recreating cache...done.
* Restoring themes...done. * Restoring images...done.
* Restoring videos...done.
* Restoring file attachments...done.
* Restoring PDFs...done.
done. * Restoring the database newscoop...done. * Upgrading (if necessary)... * Upgrading the database from version 4.4.x, roll 2015.05.16...done. * Upgrading templates...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 invoke-rc.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.
Upgrade preparation
After you have completed the backup successfully, you can upgrade Newscoop using the full tarball or zip file package, or git, as shown in the Manual installation method. The existing files in the Apache DocumentRoot folder (such as /var/www/newscoop/) should not be removed first, unless you wish to perform a clean install.
If your current Newscoop installation is version 4.4.5 or later and you installed Newscoop from the tarball or zip file, you can alternatively use an update package, which is a smaller download than the full package. The update packages only upgrade your Newscoop system by one point release at a time, making them suitable for frequent updates on production servers. Update packages are made available in .zip file format on the releases page https://github.com/sourcefabric/Newscoop/releases/
Any changes that you have made to the sample themes supplied with Newscoop may be overwritten on upgrade. For this reason, you should rename the sample theme in the theme.xml file before upgrade and keep a backup copy, if you wish to keep those changes. See the Newscoop Cookbook technical manual for more details on how to create themes.
Upgrade steps
1. Take the site offline using System Preferences on the Configure menu of the adminstration interface, so that a maintenance message will be displayed to your readers.
2. Only if you are using the full install package to upgrade, remove the /var/www/newscoop/vendor directory. (You do not need to remove this directory when using the update package).
sudo rm -rf /var/www/newscoop/vendor
3. If using a full tarball, full zip file or update zip file, unpack the archive and copy the files over the existing installation. For example, for the update package for version 4.4.7:
unzip newscoop-4.4.7-update-2016-02-08.zip
sudo cp -r newscoop /var/www/
4. Check the .htaccess file in the DocumentRoot directory such as /var/www/newscoop, 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.
5. Run the upgrade.php script in your web browser, for example:
http://newscoop.example.com/upgrade.php
Check if there are any instructions in the output of the upgrade script, and if so, follow these extra steps.
6. Clear the cache directory:
sudo rm -rf /var/www/newscoop/cache/*
7. Autoload new classes:
cd /var/www/newscoop/
sudo php composer.phar dump-autoload --optimize --no-dev
8. Install assets:
sudo php application/console assets:install public/
9. Fix subdirectory permissions to make them world-readable, if required:
sudo php scripts/fixer.php
10. Clear the cache folder for the last time:
sudo rm -rf cache/*
Once the upgrade is complete, your publications should be put back online using the administration interface.
Upgrading legacy plugins
If you are upgrading from Newscoop 4.2.x or earlier, you may also need to upgrade legacy plugins. See the document https://github.com/sourcefabric/Newscoop/blob/master/newscoop/docs/UPGRADE_4_3.md#updating-newscoop-legacy-plugins