The following manual installation method is intended for more experienced system administrators, and assumes that you have sudo or root powers on the target server. If ready-made packages of Newscoop are not available for your GNU/Linux distribution of choice, you can install the software manually using the tarball available for download from Sourcefabric:
Before performing a manual installation, you will have to verify that all of the dependency packages that Newscoop requires are already installed and working. These dependencies are:
1. Apache web server (http://www.apache.org) version 2.0.x or newer.
On Debian or Ubuntu GNU/Linux, you can install the apache2 metapackage, which will install all of the web server packages you need.
$ sudo apt-get install apache2
2. MySQL database management system (http://www.mysql.com) version 5.0 or newer.
Two components of MySQL are needed for Newscoop:
- the server
- the client programs
These components are usually packaged separately, because you may prefer to run the MySQL server on another machine from the MySQL client, which must be installed on the same machine as Newscoop. On Debian/Ubuntu, installing the mysql-server metapackage will install the latest versions of both the server and client packages.
$ sudo apt-get install mysql-server
During the installation of MySQL, you should be prompted to set a root password for the MySQL server, which is an important security feature. Make a note of this password and keep it in a secure place, as you will need it shortly.
Note that the MySQL root user is different from the system root user, and should have a different password.
3. PHP scripting language (http://www.php.net) version 5.0 or newer.
The following PHP modules must be installed:
- php5-cli - Command Line Interface module
- php5-mysql - functions for accessing the MySQL database server
- php5-gd - provides a module for handling graphics from PHP scripts
$ sudo apt-get install php5-cli php5-mysql php5-gd
These modules have the same names in the equivalent Debian/Ubuntu packages. You will also need the PHP module for the Apache web server, which has the package name libapache2-mod-php5 in Debian/Ubuntu. This package should be installed automatically as a dependency when installing the PHP packages mentioned above.
4. ImageMagick (http://www.imagemagick.org).
Needed for creating thumbnails of images. Available in Debian/Ubuntu's imagemagick package.
$ sudo apt-get install imagemagick
All of these Newscoop dependencies are available as standard packages in most GNU/Linux distributions. You should be able to find them using your distribution's software package manager, although the exact package names can vary from the examples given above for Debian/Ubuntu.
Setting up the database user and password
An existing Newscoop installation should have a named database already set up on a MySQL server, with access protected by a username and password. For a new installation of Newscoop, you will need to tell the installer to create a database to store your content in. This means you will need a MySQL user account with database creation privileges set up in advance. If you don't already have an account, you can set up a database username and password for the Newscoop installer to use with the following steps.
1. Connect to the database management system using the root account and the password that you set during the MySQL installation.
$ mysql -u root -p Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 34 Server version: 5.1.41-3ubuntu12.8 (Ubuntu) Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.2. The shell prompt will change to a mysql> prompt, which requires a semicolon at the end of each command. Create a user account for Newscoop to connect to the database, limiting it to connecting from the localhost if Newscoop and MySQL are to be installed on the same server. Otherwise, specify the server that Newscoop will be connecting to MySQL from. Make a note of the username (newscoop_user in the example below) and password (newscoop_user_password in the example) that you set, in a secure place. You will need these details during the Newscoop installation.
mysql> CREATE USER 'newscoop_user'@'localhost' -> IDENTIFIED BY 'newscoop_user_password'; Query OK, 0 rows affected (0.04 sec)
4. Grant access privileges to the user you just created. In this example, newscoop.* means all tables of a database called newscoop, which has not yet been created. You will need to provide this database name to the Newscoop installer, so that it can create the database later.
mysql> GRANT ALL ON newscoop.* -> TO 'newscoop_user'@'localhost'; Query OK, 0 rows affected (0.00 sec)
5. Exit from the database management system and return to the shell prompt.
mysql> quit; Bye $
On Debian or Ubuntu, the PHP modules that you have installed should be configured automatically, with an entry for each module added to the /etc/php5/apache2/conf.d/ directory. You can also create your own PHP customization options using files in that directory, which should not be overwritten when the main php.ini file is upgraded.
On other distributions of GNU/Linux, you may need to add a line for each module to the php.ini file, such as /etc/php5/apache2/php.ini or similar. The following extensions should be enabled. If the line is already present but starts with the semi-colon comment ';' you will need to remove this character for the corresponding extension to work.
extension=gd.so extension=mysqli.so extension=mysql.so
On any GNU/Linux distribution, the php.ini file contains some default settings which should be checked or adjusted to enable optimum Newscoop performance and security. You can do this by opening the file in your text editor, such as nano:
$ sudo nano /etc/php5/apache2/php.ini
This is a long file, so use the search tool in nano (Ctrl+W) to find the lines you want. The recommend settings are that you should:
1. Turn off register_globals because it's a potential security hole:
register_globals = Off
2. Set the amount of memory available to at least 128MB:
memory_limit = 128M
3. Turn off magic quotes:
magic_quotes_gpc = Off
4. Allow HTTP file uploads:
file_uploads = On
The values above are the default settings on Debian or Ubuntu. You may wish to adjust the following two settings, which affect the maximum size of media that Newscoop users can upload.
5. The maximum size of POST data that PHP will accept defaults to 8MB on Debian/Ubuntu. You may find that you need to set this higher, for example:
post_max_size = 100M
6. The maximum allowed size for uploaded files defaults to 2MB on Debian/Ubuntu. This is likely to be insufficient for large multimedia attachments, so you may wish to set this value higher. However, it must not be higher than the maximum POST size set above, otherwise large uploads may fail.
upload_max_filesize = 100M
7. You may also wish to disable automatic session garbage collection, which can cause permissions errors to be shown in the browser if your server runs Debian or Ubuntu. These GNU/Linux distributions use a cron job /etc/cron.d/php5 to perform garbage collection instead.
session.gc_probability = 0
The Apache web server's configuration will need to be adjusted to set the path to the Newscoop files and templates. On Debian or Ubuntu, Apache configuration files are usually found in the /etc/apache2/sites-available/ directory.
1. Create a file such as newscoop containing a virtual host definition.
$ sudo nano /etc/apache2/sites-available/newscoop
For a publication with the domain name www.example.com, you could use a virtual host definition like the following:
<VirtualHost *:80> DocumentRoot /var/www/newscoop ServerName example.com ServerAlias www.example.com DirectoryIndex index.php index.html <Directory /var/www/newscoop> Options -Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
Make sure that the DocumentRoot directory that you set in the virtual host definition actually exists, otherwise Apache will complain when it starts up.
$ sudo mkdir -p /var/www/newscoop
If the ServerName or ServerAlias that you are using is not yet set up in DNS for this particular machine's IP address, you can create a temporary hostname in your /etc/hosts/ file which will enable you to test the installation locally.
2. Disable the default Apache configuration, if you aren't using it.
$ sudo a2dissite default Site default disabled. Run '/etc/init.d/apache2 reload' to activate new configuration!
3. Enable the Newscoop configuration that you just created.
$ sudo a2ensite newscoop Enabling site newscoop. Run '/etc/init.d/apache2 reload' to activate new configuration!
4. You may also need to enable Apache's rewrite module. On Debian/Ubuntu, you can do this with the a2enmod command:
$ sudo a2enmod rewrite
The server should respond:
Enabling module rewrite. Run '/etc/init.d/apache2 restart' to activate new configuration!
5. Restart Apache as suggested by the output of the command above, so that the Newscoop configuration and the new modules can be loaded:
$ sudo /etc/init.d/apache2 restart
The server should respond:
* Restarting web server apache2 [ OK ]
1. Extract the Newscoop tarball that you downloaded in your working directory. This action will generate a directory named newscoop.
$ tar -xvzf newscoop-3.5.3.tar.gz
2. Examine the contents of the newscoop directory with the ls command.
$ ls newscoop
The output of this command should appear similar to:
admin-files classes files INSTALL.txt tests admin.php conf get_img.php js upgrade.php admin-style COPYING.txt htaccess plugins UPGRADE.txt attachment.php CREDITS.txt images README.txt videos backup db_connect.php include template_engine bin extensions index.php templates ChangeLog.txt favicon.ico install templates_cache
3. Copy the contents of the newscoop directory into the DocumentRoot directory of the Apache VirtualHost that you set up, such as /var/www/newscoop/
$ sudo cp -r newscoop/* /var/www/newscoop/
If you wish to install Newscoop into a subdirectory of the DocumentRoot, for example /var/www/newscoop/subdirectory/ your Newscoop site will be visible at the http://www.example.com/subdirectory/ URL. This method is useful for adding Newscoop to an existing site without changing the contents of the DocumentRoot directory, which might be static pages or other archived content with permalinks that must be preserved.
4. Change the ownership of the DocumentRoot directory to the username of the web server, for instance www-data on Debian or Ubuntu.
$ sudo chown -R www-data /var/www/newscoop/
5. Open a web browser with the URL of the Apache ServerName or ServerAlias that you set up earlier. If you see the Newscoop installer page, you are ready to proceed through the Installation steps chapter.
This step is optional, but highly recommended for optimum Newscoop performance. On Ubuntu, you can install XCache with the following command:
$ sudo apt-get install php5-xcache
You may wish to adjust the XCache configuration for your particular requirements:
$ sudo nano /etc/php5/conf.d/xcache.ini
On a Debian or Ubuntu server with two processors, example adjustments to the default configuration might be:
; Configure this to use admin pages xcache.admin.user = "my_admin_name" ; xcache.admin.pass = md5($your_password) xcache.admin.pass = "5f4dcc3b5aa765d61d8327deb882cf99" ; to enable : xcache.size=64M etc (any size > 0) and your system mmap allows xcache.size = 32M ; set to cpu count (cat /proc/cpuinfo |grep -c processor) xcache.count = 2 ; for *nix, xcache.mmap_path is a file path, not directory. xcache.mmap_path = "/var/cache/xcache"
The value of xcache.admin.pass shown above is just an example. You should generate your own md5 hashed password using a piped command such as:
$ echo -n "password"|md5sum
You can set up your Apache VirtualHost to allow administrator access to the XCache statistics page from the localhost, or a specific IP address that you determine. Add a stanza like the following to the VirtualHost definition that you created earlier, before the closing </VirtualHost> tag:
# php xcache stats Alias /xcache/ /usr/share/xcache/admin/ <Directory "/usr/share/xcache/admin/"> AllowOverride None Options ExecCGI Order allow,deny Allow from localhost </Directory>
Then reload the Apache configuration again:
$ sudo /etc/init.d/apache2 reload
The xcache statistics page should now be visible under the /xcache/ path on your web server, such as http://localhost/xcache/ if you have enabled access from the localhost only.