Oscailt logo
An independent media centre content management system

Oscailt Installation and Configuration Guide

Install and Configuration Guide Version 1.0 (draft)

For use with Oscailt 3.8 onwards

1. Introduction

This Installation and Configuration Guide has been created to help make the process easier and to indicate the various options that are available and to explain the many numerous configuration parameters and settings. The installation instructions just cover how to install the files and setup the database and how to import one of the template sites. From that point on is considered configuration and this ranges from the default install configuration to the setting of various parameters to the site configuration which is really more related to the layout and design and much of this is covered in the User Guide.

Some of the information here is repeated in the User Guide where it was first documented and where this document does not provide the information then the User Guide should be consulted as it may well be found there.

1.1 Oscailt Overview

Oscailt is an GPL licensed software system primarily designed for running Indymedia publishing websites. However it can be used by anyone wishing to setup a publishing system whether that be using an 'open publishing' model or not. One of the main advantages of Oscailt is that it can be setup fairly rapidly especially if one of the templates sites is used.

There are quite a number of features in Oscailt but the most important are that it allows stories and comments to be published which are stored in a database. Additionaly stories and comments may also attach images, audio, video, various miscellaneous files like pdfs and embedded video and audio. It can import and export RSS & Atom feeds of stories too.

Different story types can be defined and for story types of 'events', there is an event calendar which can list events in a monthly or weekly format or just a plain listing. For accessing older stories, there is a basic archives page.

Oscailt has the ability to customise the layout and setup different page layouts for different types of pages. This allows for different types of newswires and article view pages and headline boxes. Oscailt also has reasonable multiple language support.

For a full listing of Oscailt features, see Oscailt Feature List.

1.2 Oscailt System Requirements

It is assumed here that Oscailt 3.8 or a later version, is being installed as most web hosting services will only be offering either PHP 5.x or PHP 7.x because versions of Oscailt earlier than v3.7, did not work with PHP 7. In all cases below the software required to be pre-installed is freeware and is usually under the GPL license.

To install and run Oscailt, you need to have the following:

  1. Apache webserver.
  2. MySQL 5.5 database server or later versions.
  3. PHP 5.3 or later installed.

This is often known as a LAMP installation where the acronym stands for: Linux, Apache, MySQL and PHP.

Note: In the case of MySQL you may use the fork of MySQL, the Maria Db but so far Oscailt has not been tested with it, but it should work in theory.

Most web hosting sites offering an Apache webserver will generally come with MySQL and PHP already installed.

To make use of additional options in Oscailt you may need any number of the following:

If you are just installing Oscailt on your laptop, initially to test it out, then you probably do not need an email server nor need to setup a domain name. There are many options to load a LAMP installation on your own laptop or to use a Windows version of the more or less the same thing. One such example but not the only one is Bitnami

1.3 Oscailt Download Page

The software can be downloaded from http://sourceforge.net/projects/oscailt/

1.4 Oscailt Support

For issues related to Oscailt and contact the email list oscailt at lists.indymedia.org You can also raise bugs and feature requests through SourceForge at the Oscailt project page at www.sourceforge.net/oscailt/

1.5 License

Oscailt is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. See the GNU General Public License for more details.

It also includes the MagpieRSS and PHP XMPP Libraries GNU software.


2. Oscailt Installation

There are two parts to the installation. The first is getting the actual files onto the server and the second is running the PHP install script to do the automated part of the install.

Transferring the downloadable release gzip/tar file onto the server can present problems depending on whether you have direct terminal and or ftp access to the server or you are forced to use an web interface like myPhpAdmin. If it is on your own laptop then that process is trivial. Once the file is on the server you need to extract all the Oscailt php files into the appropriate directory.

Therefore these two steps are split out and if the first is second nature to you then skip to the subsequent section.

To install, you must create an empty database and load the Oscailt php files onto your webspace and run the install script. See the README file for more details that comes with Oscailt downloadable zip file. The software can be downloaded from http://sourceforge.net/projects/oscailt/ Oscailt 3.x features and functionality

2.1 Transferring the Download File to the Server and Extracting the Files

If this is done on a laptop it is quite trivial and you can skip to the next section. Otherwise the steps depend on whether you have direct ftp and terminal access to the server where you will host Oscailt and the webserver.

For direct access follow these general steps

2.2 Creating the Empty Database Schema

When the Oscailt installer runs it creates all the database tables. It therefore must have a database user account setup first and an empty database created so that the installer can logon to it and create the tables. If you are using a web host provider, the setup may be that only they can create the database user and empty database for you or they will give you the necessary access to do it.

Important: You must set the database default character set to latin1 and NOT to UTF-8 which will be the default in some installations.

When these steps are complete the oscailt database configuration file needs to be updated with the details.

There are three steps really which are:

You will need database root access or equivalent to logon the database and run the commands. Some services may provide an web interface to do this. Examples of the commands are: Note: You may need to GRANT the correct permission to the database user with a command like:
GRANT ALL ON oscailt_db TO  'oscailt_user1'@'localhost' IDENTIFIED BY 'password';  
You may also after the install want to limit the permissions.

2.3 Running the Oscailt Install.php Script

The Oscailt installer is a PHP file which you run from the web-browser. On the Apache web server side you need to grant temporary external access to this file for the duration of the install. To do this, if you are using a .htaccess file, then this needs to be edited with the following line added:
RewriteCond  %{REQUEST_URI}  !^((.*)install.php)$  
You must remove this after the install for security reasons and preferably either move the install.php file back out of that directory or delete it.

Assuming everything is in place the you should enter the URL to your web-server followed by install.php. For example:

http://www.my-new-oscailt-site.net/install.php 
You will now see the start page of the install.php and it guides you through a number of pages to do various things like create directories and files, check the database connection is valid, create tables, add some default configuration entries, ask you to import a sample or starter site and finally instructs you to go to the admin page where you can login and start setting up the site.

Note: The installer will create an oscailt_install.log file for reference.

There are two main options with the installer and they are:

  1. Import an existing site template.
  2. Do not import any site template -and consequently build your own site layout from scratch
Your choice depends on what you want to do. In recent releases more template sites with different colour schemes were added than the limited set available previously. If you want to get a site up and running very quickly it is probably better to import one of the simpler template site.

Alternatively if you have your own design / layout in mind, then it may make sense to build a site from scratch. However this requires more effort to learn how the object layout of Oscailt works and which is reasonably well documented in the User Guide

Therefore it is recommended to import a simple site and get it running, then through the admin pages see how the site is put together in terms of the object building blocks and that can be a good base to design your new site.

When the install is complete then you need to


3. Configuration Overview

3.1 Configuration Areas Overview

There are many levels to the configuration of Oscailt varying from values hard coded into a number of php configuration files to values configured through the admin web-interface in the admin configuration field to the setup of the layout objects which may or may not be considered configuration to the CSS style sheet files for defining text fonts and colours to the graphics files used and create for site images and banners.

Not all these things need to be configured in advance. For example if you import one of the template sites during the install then you will have default settings for all of the above. Therefore this section is more a guide of where to find things and how to change the configuration.

In summary the different configuration areas are:

Parameter Description
1. Hard coded configuration in php files. The general idea is the less tdkely to be changed the less accessible.
2. Admin Configuration page settings. These are stored in the database.
3. Site related configuration. e.g. languages, story types, topics, regions, notification levels etc.
4. Site layout object configuration. e.g. the buidtdng blocks defining the site pages.
5. Oscailt editors and permissions configuration. e.g. additional oscailt users.
6. Cascading Style Sheets for controltdng, font sizes, weights, colours etc
7. Site graphics and banners used for the public face of the site
8. Language Related Configuration for controlling how many languages can be used in publishing and language specifc layout objects

Each of these areas are described briefly in the following sections and in some cases they will refer to sections in the User Guide to save duplication here.

3.2 Hardcoded General Configuration

There are a further set of configuration parameters which are hardcoded into a number of files which are: And the corresponding files are:
  1. config/dbconfig.php
  2. config/systemconfig.php
  3. objects/systemconfig.inc
  4. config/markupconfig.php
Normally they do not change, but they control some key parameters which probably do not have to change for most sites. The 5.2 Edit Configuration screen allows you to change a subset of these and the 5.2.1 Installation Info screen accessible from the same page shows most of the hardcoded configuration.

3.2.1 Database Credentials Configuration

This is stored in the file config/dbconfig.php and should only need to be setup once and that is before the Oscailt install.php is run. It is important to lower the read permissions on this file for security purposes so that is only readable by the Apache process. The corresponding Linux permission should be set with the command:
chmod 600 dbconfig.php 

3.2.2 Hardcoded Rarely Changed Configuration Parameters

This information is stored in the file config/systemconfig.php and most of the values will not need to be changed but if they do, then it is likely to be only once. The parameters of note in this file are:

3.2.3 Site Related Configuration Parameters

There are a lot of values in this file objects/systemconfig.inc but most of them are configurable through the web-interface via the Edit Configuration page. See section 3.3 below.

However there is a small subset which are hard coded and the ones of note are:

3.2.4 Allowed HTML Tags Configuration

On any website whenever the public are allowed publish they are rarely allowed wish the full set of HTML tags because invariably one of them is not closed properly and it would end up breaking the page display. This is why many sites offer alternative sets of tags which they can parse and control better and therefore detect improper matching. This constraint is implemented in Oscailt by defining in config/markupconfig.php sets of public tags that the public is allowed use in the publish (object) form and then an extended set called basic tags that editors can use in the form. There are also a set of evil tags which are largely JavaScript types of tags that are not allowed at all an these are designed to prevent people inserting JavaScript to carry out hacking.

The type of configuration change here is to either add or remove tags between the public and basic tags arrays to increase or decrease the set of allowed tags during publish. For example all the HTML tags that can be added by any of the Custom Tags in the publish object/page have to be in the basic set and the custom tags available to the public -i.e. non logged-in users has to match in the public set. If either the TinyMCE or OpenWYSIWYG options instead of Custom Tags are configured for publish forms, then this HTML tag may need to be revisited.

3.2.5 Jabber Related Configuration

This section only applies if the Jabber integration is enabled. The information for this is storied in config/systemconfig.php file within the XmpPhpConfig class near the end of the file.

As a pre-requiste you should have pre-installed a Jabber server such as ejabberd from http://www.process-one.net/en/ejabberd and to configured at least two users with passwords. One is the user from which Oscailt will send chat messages and the second user is the one that receives the messages.

These users and passwords then need to be set in the xmp_sender_user and xmp_recipient and related parameters. The host of the site needs to be set. The comments in the file should explain the exact details. The Jabber server will need SSL certs. You can use your own in which case it is important to set the correct value in the peer_name parameter.

Finally when Oscailt is setup there is a special Jabber page where tests can be carried out at sending and receiving chat messages to these users. The link to this test Jabber page can be found in the admin User Status set of pages.

3.3 Admin Configuration Page

The first task to do when the Oscailt installer has completed is to setup the site URL along with a number of other settings. To do this login to the admin.php page and from there click on the Edit Configuration link. Details in the User Guide in section 5.2 Edit Configuration

3.4 Site Related Configuration

This refers to the first steps on building a working site and if a template site was imported then some of this configuration will already be done. To configure these they are all accessible from the main admin page and the details are already covered in the User Guide

A summary of the items to configure would be:

3.5 Site Layout Configuration

Site layout deserves it's own section and is extensively covered in the User Guide and section 4. Designing an Oscailt Website below provides pointers to the relevant sections in the User Guide

3.6 Oscailt Editors and Permissions Configuration

Oscailt can have multiple users with varying levels of access to the site ranging from full administration rights to much more limited actions. If there will be multiple people either running the site or need access either for administration purposes or writing articles then it is worth planning out to some degree a set of roles and defining these first. The installer defines a set of some basic roles to get one started. Then the next step is to create new users. Details of both of these processes are already described in the User Guide in sections 5.6 Edit Editors and 5.7 Edit Roles with some further background in 8. Editor Roles and Permissions

3.7 Cascading Style Sheet Configuration

Creating a set of CSS style sheets for a site tends to be a creative and artistic process and can involve a lot of work to get it right. Oscailt has a set of three CSS files with pre-defined classes and styles. There are two main parts to this process. The first is identifying the style classes in existence and the second is determining when and where they are used in Oscailt.

Oscailt uses three style sheet files and they can be edited from within the Admin area as described in the User Guide in section 5.4 Edit Style Sheets.

There is some previous coverage of what and where the style classes are in section 11. Use of Cascading Style Sheets (CSS) in Oscailt of the User Guide

In Oscailt v3.7 a new admin feature was introduced that allow an editor to select new foreground and background colours for most of the style classes and to re-generate the css files. This is accessible through the style sheet admin pages and is documented in the User Guide in 5.4.1 Generate New Style Sheets

3.8 Oscailt Site Graphics and Banners

The site graphics and banners are the public face of your site and most of the basic graphics can be found in the directory:
 
    html
       
       +---graphics
 
The install comes with a default set of graphics but one is likely to either modify the existing ones or create new ones. Many of the Oscailt object building blocks for the designing the pages have options to include images / graphics but there is one object called the pictureBox object which is designed specifically for displaying images because if you define several language versions it can display the correct one for the current browser language setting. For example you can have a set of banner images named as follows: en_banner.jpg, es_banner.jpg, fr_banner.jpg and de_banner.jpg which would display for English, Spanish, French and German language settings respectively. You could also have regional or even topic versions. The allowed formats of the file naming convention are listed below. And it searchs for fileypes in order of: gif, jpg and png.

 
	region_topic_code_banner    where code is the two letter language code.
	topic_region_code_banner    
	region_topic_banner 
	topic_region_banner    
	region_code_banner
	region_banner
	topic_code_banner
	topic_banner
	code_banner
	banner
 

There is a useful feature in the admin page under the View Objects page and the 5.12.2 View Theme Images tab which will list all the images / graphics that are currently being used by the different site objects and this greatly helps to pin down which images are in use and where.

To change images, one can edit the layout object and simply point to a different image. However if you do not have a lot of access to the server, the problem becomes how and where to upload images. This solved by providing an Uploads File option in the Admin Layout area and the files / images uploaded will be stored in the directory

 
    html
       +---attachements 
                      +---sites
                          +---site_1
 
where site_1 is site with Id = 1. If you create multiple sites you will get other ids, so the files will go to the relevant directory for which admin layout page you are viewing. Then when you want to add an image into an object like PictureBox you provide a relative path to it. For example if the image is called image1.jpg then in the example above for uploads you would enter
 
 attachments/sites/site_1/image1.jpg
 


4. Designing an Oscailt Website

This task could be viewed as configuration but it is really a separate task in it's own right and it is has already been reasonably well covered in the User Guide. Therefore the purpose here is simply to provide pointers to the relevant sections.

Before starting to design a site it is worth reviewing section 3. Display Overview of the User Guide to understand how the basic layout operates in Oscailt and then to read section 2.4. Configuration of Site Layout Then you are ready to read sections 2.6 Overview for Creating an Oscailt Site and 6. Instructions for Configuration of Site Layout


5. Language Translation

Language configuration is already extensively covered in the User Guide in section 7. Language Translation but to summarize there are several different areas that can be configured for language specifics. A list of these are: Since the character set used in the database is Latin1 this means it can only store character sets for European languages and the PHP code itself uses the ISO-8859-1 character set. See Wikipedia for details on the character set itself.

While using the UTF-8 character set would allow all languages to be supported, traditionally the PHP string handling did not handle this very well and the code would need a very large amount of effort to re-work it to use UTF-8 and given there has been no demand for non Latin languages, it does not make sense to devote effort into this task.

For a multi-language site, all of the above are likely to be carried out except the translation of administration layout pages since only a very small set of editors would have access to these and would require them to be in another language.


Back to Table of Contents

Last updated: June 2019