Oscailt logo
An independent media centre content management system

Oscailt Installation and Configuration Guide

Install and Configuration Guide Version 1.4

For use with Oscailt 4.3.1 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 7.x or PHP 8.x because versions of Oscailt earlier than v3.7, did not work with PHP 7. The latest version of Oscailt 4.3 works with PHP 8.2.8 although the latest version will still work with PHP 7.x

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 7.x or later installed.

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

For a table of compatible PHP and MySQL versions for the most recent Oscailt release see: Features List: Section 3. Software Requirements

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/ and a list of the features at Oscailt 4.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

If you are doing an install with bitnami virtual VM on debian, the apache server may run as user 'daemon' and you could end up with a mixture of file ownerships. The reason is that during the install any directories and cache files created will be under the apache user. So this woul need to be resolved. It is possible the files are initially given ownership as "root" but that would need to be changed.

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 your host provider 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 four steps really which are:

You will need database root access or equivalent to logon the database and run the commands. Some services may provide a web interface to do this. Examples of the commands are:

2.2.1 Granting Privileges To the Database Username

To use the database, Oscailt must login with a MySQL database username and password as described above. This username then needs to be granted permissions or privileges so that it can access the database and make changes to it. Do NOT use the database root user for normal Oscailt operation. This is why a separate database user for it, is created.

Note: You may need to GRANT the correct permission to the database user with a command like: 

GRANT ALL PRIVILEGES ON oscailt_db.* TO  'oscailt_user1'@'localhost' IDENTIFIED BY 'password';
or this might be sufficient 
GRANT ALL PRIVILEGES ON oscailt_db.* TO  'oscailt_user1'@'localhost';
You may also after the install want to limit the permissions because once the install is done, the database user will not need the permissions any more for creating, modifying or deleting tables since it will only be dealing with records from that point on. Thus it is a security risk from that point onwards to allow it to have too many permissions. An ideal solution is to create two separate users one with the higher level permissions and to start off with the higher level one for the install and then update the config/dbconfig.php after with the lower level permission user.

You can check the privileges for the user with this command: 

SHOW GRANTS FOR 'oscailt_user1'@'localhost';

2.3 Running the Oscailt Install.php Script

2.3.1 Setting up Access to the Install 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.

2.3.2 Starting the Install

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:

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

There are two main options to choose from 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 or you could install the simplest template site and then modify it and built out from it.

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. Most of the template or starter sites are fairly basic and the idea is to keep them single so it is relatively easy to figure out how they are put together. They can be made a lot more complex by building up side menus, headers, footers and sets of links and static pages. You can even create RSS or Atom objects for importing things like favourite blogs etc.

2.3.3 Post Installation Tasks

When the install is complete then you need to

2.4 TroubleShooting the Install

2.4.1 Install Page Displays Nothing

There can be many reasons for this but a frequent once is due to the default PHP settings. If you have access to the webserver error logs then there may be some information in that to indicate the problem. This should be found at /var/log/httpd/error_log

The PHP settings are controlled by the php.ini file. The location of this tends to be server dependent but the first place to look is to look for where PHP itself is installed on the server. Then to check this file and look for the setting for short tags. If it is off or disabled then you must enable them. This may or may not require a restart of the server.

If after that the problem persists then one should check the permissions for read access on the PHP files and the read access of directories too.

2.4.2 Installer Cannot Create Directories

This is always a permissions problem and the first thing is to determine the username that the web server is running as and the user owner of the underlying Oscailt files and directories. If they are different this can lead to problems. You should ensure at least that both users are in the same Unix group. One solution is to change ownership (if you have permission) of the files and directories to that of the webserver user. See steps on how to do this in sec 2.1 above.

You should never use the setting 0777 (see above) on the directories as it is a major security risk but if it is used in order to get the initial directories created then you should use the chmod command to restrict permissions on all files and directories. Again see examples of how to use the command above as with the combination of the find and chmod command

2.4.3 Cannot Connect to the Database

Check the settings for the database name, host (i.e. server), username and password and ensure these match with the user name setup in the database AND that the database privileges have been granted. The host will in most cases be set to localhost but if the database is running on another server then you will have to enter the ip address for it.

2.5 TroubleShooting Post Install

2.5.1 Tasks To Do Post Install

Whenever the installation is complete, the installer will lead you to login into the new site and one of the first tasks should be to follow the step below.

2.5.2 Tasks To Do When Using an Imported Template Site

If you have carried out the install and imported one of the template sites then there are a few basic steps you need to do and these are listed below. Not doing them may cause problems.

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.2.6 FFmpeg Related Configuration


This feature is available in Oscalt v4.1 onwards

This section only applies if the ffmpeg integration is enabled. ffmpeg is a command line tool for use with video files. As part of the integration with Oscailt, it is necessary to configure the path to the ffmpeg binary by setting the value of the variable $oscailt_basic_config['ffmpeg_path'] in the file. config/systemconfig.php and it is also required to check that from the main configuration page the Installed ffmpeg checkbox is ticked.

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. And in the latest release, version 4.0, there is a new sub-page from this section that displays multiple colours and allows one to play around with various combinations to help settle on selecting a colour which is probably a useful aid when redesigning 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

3.9 Switch to new Date Format System in Oscailt 4.2

In the Oscailt 4.2 release, the code has been updated to no longer use the strftime function to format the display of dates and now uses the date() function instead, because sttrfime is deprecated in PHP 8.1.0. The old style date format is described here whilst the new format is described here. Oscailt allows the date format to be configured in any of these object types: newswire, article, feature, headlinebox, feedimport, imageimport. However to make this easy the viewobjects.php admin page has been updated and under the View Obj Date Formats subage, it will scan all the objects and display all the instances of the date format where configured and automatically suggests conversion strings in the new format. Additionally when the object types shown in filtered mode, there is an otion to automatically update the date formats to the new format.

Once all the objects are convered then the objects should be rebuilt by going to the ClearCache admin page and selecting the Rebuild Objects option.

A final check should be made on the main configuration admin page to ensure the system default date format is also updated. This should also have an automatic suggested conversion.

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

Then section 10. General How To Section should cover most of the specific scenarios one is likely to encounter when adding more complex options and features into a site layout.

It would also be instructive to do a few initial installs of one of the template sites and examine how each site is built out of the various objects and are linked together before perparing to build your own site.

A useful tool for examing the overall set of objects one has built already is to use the Admin View Objects which is briefly described in section 5.12 View Object Usage

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.

6. Appendix A

This section very briefly covers installing other software.

6.1 Installing Apache

Unless you are starting from scratch it is very likely your server already has Apache Web Server installed. There are lots of websites already covering how to download and install an Apache webserver. This section simply lists some items that you may forget configure.

Firstly the Apache configuration files on your server are generally under the directory: /etc/httpd/

6.2 Installing PHP

In most cases where you are using a webserver from a hosting firm, PHP will be pre-installed. For details of installation of PHP itself there are many resources for this on the Internet. However this section is present here so as to highlight some key configuration parameters that may arise if you are encountering problems.

Configuration in PHP is controlled through a file called: php.ini which has many values, most of which are defaulted. The short_open_tag may arise if the code is not executing or generating syntax errors and controls the classic opening / closing PHP tags. The next two parameters display_errors and html_errors should be possibly switched off on a production system and switched on in a development or testing system.

If your system is not communicating with the database then next parameter mysqli.default_port may have an incorrect value. You will need to find out what the setting is on MySQL itself.

If you are using for example the Bitnami LAMP/WAMP install for development, it is useful to disable the operations cache by setting it to zero in parameter opcache.enable. 


short_open_tag = on

display_errors = on
html_errors = on

mysqli.default_port = <port>

When you have installed Oscailt, then from the Edit Configuration page under the option System Installation Info tab or link, many of the other PHP settings important to Oscailt are displayed.

6.3 Installing Jabber

Generally Jabber will NOT be pre-installed and is only needed if you want to use that feature. It is only useable from Oscailt v3.8 onwards. Therefore you must find a Jabber server, download it and install it. The difficult part is configuring it and the list below gives a few tips since there are already numerous sites covering jabber installation.

When complete and the Jabber server has been started then from the Jabber tab in Oscailt Admin Users Logged In & Msgs page, there is an option to send a test message to ensure it is all working.

6.4 Installing ffmpeg

This command line tool can be used for extracting cover images from video files (e.g. mp4 files) or can be used for reducing the size of the video for example from 1280x720 to 640x360. It has numerous other features. Within Oscailt the Admin image manager makes use of the tool.

You will need access to the server to install this tool. If you are using a hosting service they may not permit it. There are many websites explaining how to install ffmpeg on the various different flavours of Linux.

For information and documentation about ffmpeg itself, visit it's website at: https://ffmpeg.org/

6.5 Installing curl

On many Linux servers this command line tool will be already installed. It is a tool for sending http requests and receiving the response. It is a highly versatile tool. There are many resources found online describing how to install it. In the case of Oscailt it can be used for retrieving imported RSS feeds.

However PHP has an inbuilt curl API library which was not available in earlier versions, so this negates the need to install it these days.

6.6 Oscailt Support

For issues related to Oscailt, you can raise bugs and feature requests through SourceForge at the Oscailt project page at http://sourceforge.net/projects/oscailt/

Unfortunately the former Oscailt list oscailt at lists.indymedia.org is no longer operating.

Back to Table of Contents

Last updated: Mar 2024