SyndeoCMS Installation

Contents

1. Introduction

2. New installation
    2.1 Requirements
    2.2 Installing SyndeoCMS on a Windows 2003 Server with IIS 6.0
    2.3 Unpacking the software
    2.4 Setting ownership of files and directories
    2.5 Taking the 8 steps

3. After the installation: security
    3.1 Linux and security
    3.2 PHP mail function

4. Building your site; some advice

5. Migrate from Site@School 2.4.10
    5.1 Upgrading and your language files

6. Installing modules

7. Installation problems

1. Introduction

This chapter describes the installation of SyndeoCMS on Linux and Windows operating systems. Please study this document completely before asking help.
In this chapter we use an example primary School. The URL of the schools website is http://www.exampleschool.net.
For a new installation goto the next paragraph, for migration goto chapter 5. Migrate from Site@School 2.4.10

(top)

2. New installation

2.1 Requirements

These installation instructions assume certain software to be properly installed and functional on your own or your ISP's server:

2.2 SyndeoCMS on a Windows 2003 Server with IIS 6.0

We received the following info from Charlie Fox:
Required:
PHP 4.3.9
MySQL 3.23.49

In IIS 6.0 you have to create an extra web service extension and just name it for example PHP.
Point it to php.exe and to php4ts.dll.

2.3 Unpacking the software

SyndeoCMS will create the directory 'starnet' and the file 'index.php'.
Unpack the .tgz or .zip file in the document root directory of your webserver.
In Linux the document root directroy will be something like '/home/httpd/html/', or '/home/httpd/htdocs/' or '/var/www/' depending on the distribution and version you use
In Windows the default document root path is: 'C:\Program Files\Apache Group\Apache\'
For Linux and Windows these are the most common places. If you wish, you can select another directory under the document root directory to install SyndeoCMS. See the instruction instructions later on.

To unpack the file in Linux, according to the file you downloaded, do:
tar xzvf syndeocms-<version-number>.tgz
or
unzip syndeocms-<version-number>.tgz.

In Windows, use your favorite unzip program. 7-Zip is a good OSS/GPL zip/unzip program, downloadable at http://www.7-zip.org/.

2.4 Setting ownership of files and directories

This information is only applicable for Linux users. Windows users can skip this section and proceed with '2.5 Take the 8 steps'.

Find out who is the user and group of the Apache webserver. Check the file /etc/httpd/conf/httpd.conf and look for 'User' and 'Group'. It is in 'Section 2 Main Server Configuration'. You find a user and group for the webserver, names like: 'apache' or 'www' or 'nobody'. Let's assume you find the user and group 'www'.

Now go to your document root directory. It will be something like '/home/httpd/html/', or '/home/httpd/htdocs/', or '/var/www/'.
Execute, as user root, the following commands:

# chown -R www.www starnet
# chown -R www.www agenda
# chown www.www index.php
# chown www.www print.php
These commands will recursively change the ownership of the directories and their contents and the two files to user and group 'www'.

NOTICE: Correct ownership of directories and files is a necessity to ensures the correct working of the installation script. Wrong ownership of directories and files is often a cause of errors or unsuccessfull installations.

When you install SyndeoCMS at an ISP (Internet Service Provider), ask them for the correct ownership of your SyndeoCMS files and directories.

2.5 Take the 8 steps

Now you are ready to install the SyndeoCMS on your server. The installation consists of 8 steps:

  1. Go to the correct URL
  2. Choose installation type (new or upgrade)
  3. Read the opening screen
  4. Set the webserver properties
  5. Set the database properties.
  6. Choose the installation type (demo or basic)
  7. Create a user for the system
  8. Log in

We will now explain the 8 steps in detail.

1. Go to the correct URL

Open your browser and go to the URL where you installed SyndeoCMS. In our example it is: http://www.exampleschool.net/starnet/install/. (this URL is fictional, replace it with the URL of your school).
When you have unpacked SyndeoCMS in another directory, for example in /home/httpd/htdocs/cms1/, go to http://www.exampleschool.net/cms1/starnet/install/
You should see now:

[ ]
install_overview.png

2. Choose insallation type

Choose your installation type. In this case it will be 'New installation'. Choose your language by clicking on the 'install.php' of the desired language.
You will now start with the installation of SyndeoCMS.

3. The opening screen

You see (depending on the chosen language; here we only show English):

[ ]
install_opening.png

Here the installation steps are explained. Read them and click on 'Continue'.

4. Set the webserver properties

You see:

[ ]
install_serverproperties.png
Explanation:

Check all the fields and when they are correct, click on 'Continue'.

5. Set the database properties.

You see:

[ ]
install_database.png
Explanation:

Check all the fields and when they are correct, click on 'Continue'.

6. Choose the installation type.

You see:

[ ]
install_type.png
Explanation:

Make your choice and click on 'Continue'.

7. Create a user for the system.

You see:

[ ]
install_create_user.png
Explanation:

Check all the fields and when they are OK, click on 'Continue'.

8. Log in as the created user (with demo data)

You see:

[ ]
install_login_demodata.png

You have successfully performed the SyndeoCMS installation on your system.
Print this page or copy the data and keep it in a safe place.

8a. Log in as the created user (no demo data)

You see:

[ ]
install_login_nodemodata.png

You have successfully performed the SyndeoCMS installation on your system.
Print this page or copy the data and keep it in a safe place.

You can click on 'here' or on the 'Login' button to log into the system.
You see:

[ ]
install_login.png
Explanation:

Now you should see:

[ ]
install_management.png

Prior to this screen you must have seen an unpleasant warning message. For security reasons, read 'After the installation'. After that you can enjoy SyndeoCMS.

(top)

3. After the Installation: security and mailing

At this moment in the installation process, SyndeoCMS is not secure! Both Windows and Linux users should remove the contents of the ./starnet/install directory. If this is not done, someone can do a new installation and ruin your site!
The remainder of this section is only applicable to Linux users or those users who host their schoolsite at an ISP (Internet Service Provider) that uses a *nix server.

3.1 Linux and security

Linux and other *nix systems can be very secure. However, security is completely in your hands. You have to make your SyndeoCMS installation secure. This section describes what measures you can take. Before we come to the practical security measures we start with a small lecture (courtesy of Peter Fokker) on 'Permissions and Ownership'

Permissions and ownership
The concept of permissions is difficult to understand, mainly because the 'x' (execute) bit sometimes has a different meaning:
- for files the 'x' bit indicates that this file is an executable program, that is to say, for the specific user or group.
- for directories the 'x' bit indicates that this directory is searchable for files. Again, by the specific user or group.

When you want to serve files with the webserver Apache, it is only necessary to apply the 'x' bit on directories. When the 'x' bit is set for files, you actually just say that this file is an executable file (on the *nix server). For images etcetera that is not relevant and it is even better not to set the 'x' bit on such files. A cracker can upload a file with a .jpg extension which, in reality, is an executable file. This can not be your intention.

A user on a *nix machine can be member of several groups.
A file or directory has an owner ('user') with the corresponding permissions and is also part of a group ('group'), also with corresponding permissionns.
The webserver runs as a certain 'user', for example 'wwwuser'. The useraccount of the webserver is often also member of a special group, for example 'wwwgroup'.

When a 'normal' user (let's say the user 'mortaluser'; the one with the ftp-client) wants to put something in a place where Apache can also access it, the following minimal possibilities exist. FIXME: fore waht.


  1. File permissions: rw-r----- (0640) and owner mortaluser.wwwgroup.
    Directory permissions: rwxr-x--- (0750) and owner mortaluser.wwwgroup.

    In this case all members of the group wwwgroup can read files and read and search directories. That's good enough to serve files. Condition: 'mortaluser' must be member of group 'wwwgroup'. Which is not always the case.


  2. File permissions: rw-r--r-- (0644) and owner mortaluser.mortalgroup.
    Directory permissions: rwxr-xr-x (0755) and owner mortaluser.mortalgroup.

    In this case the detour via 'world-readable' and/or 'world-executeable' is the only solution because 'world' membership is the only communal property between 'wwwuser' on the one hand (who must be able to read the files) and 'mortaluser' on the other hand (who offers the files, among others to the webserver).


  3. File permissions: rw-r--r-- (0644) and owner wwwuser.wwwgroup.
    Directory permissions: rwxr-xr-x (0755) and owner wwwuser.wwwgroup.

    Here 'mortaluser' can do nothing because he has no rights to write; only 'wwwuser' has write rights. Uploading files with a PHP-script will work, because the PHP-script very probably is executed as 'wwwuser' who may create files in the directory or write in existing directories.


  4. File permissions: rw-rw---- (0660) and owner wwwuser.wwwgroup.
    Directory permissions: rwxrwx--- (0770) and owner wwwuser.wwwgroup.

    Also here 'mortaluser' can do nothing because he has no write rights; only 'wwwuser' has write rights or another user who is member of the group'wwwgroup'.
    Uploading via a PHP-script works, because the PHP-script very probably is executed as 'wwwuser' who is allowd to create files in the directory or may write in existing files. And, in case the PHP=script has no rights on that ground, then membership of the group 'wwwgroup' is also a ground on which write rights can be granted.


  5. File permissions: rw-rw-rw- (0666) and owner wwwuser.wwwgroup.
    Directory permissions: rwxrwxrwx (0777) en eigenaar wwwuser.wwwgroup.

    Here 'mortaluser' may write files, but that is only because everybody is allowed to write. This is the least restrictive to exchange files between 'mortaluser' and 'wwwuser'.

When you want to use one of the options, the best thing you can do is test them. Start with the most restrictive and see if it works; i.e. if you can uplaod files and make them visisble via the webserver. If not, use the next less restrictive option, and so forth. It is a matter of trial and error.
Maybe 'mortaluser' can become a member of 'wwwgroup'; then everything works with permissions 0660/0770 and files/directories owned by group 'wwwgroup'.
Maybe the webserver can run under user 'mortaluser' and/or 'mortalgroup'. Then 'mortaluser' and Apache must have something in common but not permissions on 'world' level. In this case permissions can be 0600/0700 or 0660/0770.

Also with this explanation, the practical side can be difficult. Because of the varyity in *nix-server, the many idffering policies of ISP's and the complexity of the subject. The final answer on the question of the 'right' file permissions and ownership of SyndeoCMS migt very well be: "That depends...". So far the exmplanation.

Maybe we can make the case practical. The following table shows the different file permissions which can be set in SyndeoCMS working environment (configuration) .
Assumption is that the starnet/media directory is owned by the userid of the Apache webserver and not the userid of the user who uploads the files.

Possible file permisssions table

Permission
SyndeoCMS directory
File upload SyndeoCMS
Visible on web
FTP/Plesk
view directory
FTP/Plesk
file delete
File
permision
0700yesyesnono644
0750yesyesnono644
0755yesyesyesno 644
0770yesyesnono644
0777yesyesyesyes644

Plesk = Multi-platform control panel for service providers, often used by users to manage their website.
FTP = File Transfer Protocol

Now, let's be practical. After a successfull installation, as a minimum you have to secure the /starnet/configurationn/database.inc.php file. During the installation this file's permissions were set to 0777. This means that everyone can see the loginname and password of your database.
To ensure the file is not world readable, change its permissions to 0400 (best) or 0640.
As root, go to the ./starnet/configuration/ directory and perform the following command:

# chmod 0400 database.inc.php
Check if your file has the right permissions with the 'ls -l' command. Here are some examples:
-rw-rw-rw-    1 www www     416 2004-10-28 20:13 database.inc.php
This is VERY INSECURE! The content of the database.inc.php file is world readable. A cracker can find yor database password and do bad things.
-r--------     1 www www     416 2004-10-28 20:13 database.inc.php
This is secure. The file where the username and password of the database are kept cannot be seen by the outside world. The permission 0400 indicates that the file is only readable by the user 'www'.
If SyndeoCMS does not function with this tight permission, set it to 0640 and try again.

When you have SyndeoCMS hosted at an ISP, ask them for the securest permissions. By now you we assume you will have understand that a permissions ending on 7, 6, or 4 are absolutely unacceptable for the file database.inc.php. Acceptable are 0640 or 0660.

More security is needed. However, other files and directories need less tight permissions in order to upload files etcetera.
As root, go the document root and perform the following commands:

# chmod -R 0755 ./starnet/* 
# chmod -R 0755 index.php
# chmod -R 0755 print.php
This will give all SyndeoCMS files and directories the reasonalble thight permissions.

To end we give a few tips to get thighter permissions.

NOTICE: It's a good idea to check the ownership of the httpd root directory 'htdocs' for example. IT shouls hve 0750 permissions and be owned by the webserver.

First you set everything to the most restrictive polich, for example:

# chmod -R 0640 ./starnet/* 
# chmod -R 0640 ./agenda/*
# chmod -R 0640 index.php
# chmod -R 0640 print.php
This sets all fiels and directories to 0644. This sets all fiels and directories to 0640. As you will understand SyndeoCMS will not work because the executable bit is missiing on the directories.
The followiing command only sets the directories to 0750 and leaves the files to 0640.
find -type d -print0 | xargs -0 chmod 750 ./starnet

NOTICE. The above procedure is normally only possible on your own server. If you have an ISP, probably not all commands are allowed.

Do not forget to delete the contents of the /starnet/install directory.
And, last but not least, as a final check it's a good idea to run /starnet/syndeo_check.php. See SyndeoCMS check below.

3.2 PHP Mail function

On some servers the PHP mail function can be disabled. You can check this by running the syndeo_check script see: SyndeoCMS check below. At the bottom of the page you find an email send option. You can send the email to yourself to check if sending emails works properly. If you can send the output of the syndeo_check script via email, you can skip to step 4.

If the mailing doesn't work you can use SMTP , then you need to change the file /starnet/core/class.phpmailer.php with the following:

line 109:	var $Mailer      = "smtp";
line 142:	var $Hostname    = "syndeo.user";
line 156:	var $Host        = "mail.ourserver.org";
line 174:	var $SMTPAuth    = true;
line 180:	var $Username    = "john";  // SMTP username
line 186:	var $Password    = "secret"; // SMTP password  
Change the values of $Host, $Username and $Password according to your site , you may have to contact your provider/server administrator.

(top)

4. Building your site; some advice

The best procedure for starting to build your site is:

  1. Have a mental image of the site you want. Make a couple of drawings and show them to colleagues, parents and pupils for comment and discussion. Then start building.

    NOTICE: Take the following steps in this order to prevent many problems!:

Long filenames and SyndeoCMS. SyndeoCMS is picky about filenames.
When uploading material to the server, take care of the following naming conventions of the files:

NOTICE: When things are still not clear, visit our Forum.
When asking questions, please state:

Give a complete and detailed description of your problem. "The news module is not working!", is a description we cannot do anything with.
Give a detailed description of all the steps you took before the problem occurred.
When we receive your problem, the first thing we do is try to recreate your problem. Only in this way we can try to fix it. No guarantees.

(top)

5. Migrate from Site@School 2.4.10

When you want to migrate from Site@School to SyndeoCMS, you need to have version S@S version 2.4.10. If you have a lower version you will need to upgrade to 2.4.10 first

[ ]
install_overview.png

Example:
Click on the 'migrate2.4_2.5.php and follow the instructions on the screen' file. This migration script will upgrade your S@S system to SyndeoCMS version 2.5.10.
The migration is done in three steps. In the final step additional database tables are created or changed.
These simply are to click 'Continue' a couple of times.

Do not forget to delete the contents of the ../starnet/install directory.
And , last but not least, as a final check it's a good idea to run ../starnet/syndeo_check.php, see the SyndeoCMS check script.

5.1 Upgrading and your language files

When you have made changes to your language files, for example to adapt SyndeoCMS for a youth orchestra in stead of a primary school, you have to take measures to prevent your language files getting overwritten when you upgrade to a new version of SyndeoCMS. All your precious work will be lost!

From version 2.4 on you can retain your changes when upgrading. Do as follows:

- When you did not have an older version and are installing version 2.4, there is no need to do anything. When you make changes to your language files, the filenames of the language files will automatically be changed from (for example, when using Dutch as preferred language) NL.php to NL_user.php. Also in future versions, your own changes will be retained.

After the 2.5 upgrade, you will need to load the changed language files once in the translate tool and press 'Save'. By pressing save the newly introduced language items of 2.4 will be added to your NL_user.php file. The same goes for future versions.

(top)

6. Installing modules

At this moment (2.5) there are no additional modules to install. It is possible that additional modules became available after a SyndeoCMS release. These modules can be downloaded at our download section at Sourceforge.

To install new modules run the corresponding install scripts from the directory ../starnet/install.

(top)

7. Installation problems

When problems arise during or after the installation, several helpers are available:

Now we will discusss these options.

Installation chapter

Did you perform all the steps? When installing SyndeoCMS in another directory, did you set the correct directory/ies in the second entry field? Did you give the right MySQL username and passwords, etc. etc.
Furthermore, the chapters of the manual contain detailed info on how to use SyndeoCMS. Many problems can be prevented by reading the manual.

"I changed something in SyndeoCMS management and it's not visible on the site!"
When you have two browser windows open on one computer, i.e. your schoolsite and SyndeoCMS management, it can happen that the changes made are not visible on the site, even after reloading the page. This is due to PHP sessions used in SyndeoCMS.
Remedy:
Just logout of the SyndeoCMS management and press refresh in the other window and the changes will be visible.

Installation check script

The easiest check is the installation check script. The script is called 'syndeo_check.txt' and is located in the ../starnet directory. You have to rename the script to syndeo_check.php. The .txt extension prevents execution of the script. This is a safety precaution. Set the permissions of the script to 660.
Point your browser at http://www.yourschool.org/starnet/syndeo_check.php. The URL is fictional, replace it with the URL of your school. You should see someting like:

[ ]
install_check1.png
[ ]
install_check2.png
[ ]
install_check3.png

Check if all parameters are marked 'OK'.
At the bottom of the page you find an email send option. You can send the email to yourself to check if sending emails works properly.

NOTICE: After using the script, rename it back to 'syndeo_check.txt' and set its permissions to 000. These are safety precautions. You should not give information about your configuration to the world!

PhpMyAdmin

A useful tool for reporting and/or solving problems is the graphical front end to the MySQL database. Its name is 'PhpMyAdmin', and you can find it on the PhpMyAdmin site http://www.phpmyadmin.net/home_page/ site.
Download the program, unpack it in your document root, read the install file and enter necessary data in the config.php file. Now you can see your database and tables, and if necessary, delete or modify them.

NOTICE: Keep in mind that having PhpMyAdmin installed on your site is a security risk! Take measures to prevent unauthorized acces. It can ruin your database. A good security measure is to install phpmyadmin in a directory with a made up name and, after using PhpMyAdmin, set the permisions to to the directory to 0000.

Common problems