Installation

Contents

2. New installation
    2.1 Requirements
    2.2 Installing S@S 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. Installing the manual

6. Upgrading to a newer version
    6.1 Password encryption
    6.2 Upgrading and your language files

7. Installing modules

8. Installation problems

1. Introduction

(top)

2. New installation

2.1 Requirements

• A version of the webserver Apache (1.3.23 or higher, or 2.0.48-1 or higher)
• A version of the database server MySQL (3.23 or higher or 4.0.16-1 or higher)
• A version of the web programming language PHP (version (4.2.1 or higher).
  PHP must be configured to enable session support.

2.2 S@S on a Windows 2003 Server with IIS 6.0

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

To unpack the file in Liunx, according to the file you downloaded, do:
tar xzvf siteatatschool-<version-number>.tgz
or
unzip siteatschool-<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

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

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 Site@School at an ISP (Internet Service Provider), ask them for the correct ownership of your Site@School files and directories.

2.5 Take the 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

install_overview.png

In your browser you see also 'Modules' and 'Manual'. We come to that later.

2. Choose insallation type

3. The opening screen

install_opening.png

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

4. Set the webserver properties

install_serverproperties.png

• Website title: Put in a title. You can change this title later on when necessary.
• Server path: In the left input field, put in the document root path of your server. Do not forget the trailing slash.
  In Linux it will be /home/httpd/html/ or /home/httpd/htdocs/ or /var/www/, depending on the Linux distribution.
  In Windows it is: C:/Program Files/Apache Group/Apache/htdocs/.

  The right input field is reserved for the directory where Site@School is located. There is no leading or trailing slash!
  Examples of entries in the right field:

  • Single installation on your own Linux server: Put in 'starnet' without leading or trailing slash. Omit the single quotes.
  • Single installation on your own Windows server: Put in 'starnet' without leading or trailing slash. Omit the quotes.
  • Multiple installations on your own Linux server: Specify a directory for each installation of Site@School, for example 'cms1/starnet', 'cms2/starnet'. Omit the leading and trailing slash, just a slash in the middle. Omit the quotes.
  • Multiple installations on your own Windows server: The same procedure as with Linux.

  NOTICE: The server path, i.e. the combination of the document root path and the starnet directory must yield a valid path.

• URL of the site: The URL of your site is in the entry field. When you have more CMS's, put the directory behind the URL and end with a slash.
• Security code: Enter a number of characters here. These characters are used as a 'salt' when setting up sessions. This field can not be empty!

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

5. Set the database properties.

install_database.png

• MySQL server address: Most times it is 'localhost'. Omit the quotes. When you have S@S hosted at an ISP, ask them for the correct address.
• MySQL username: Most times it is 'root'. Omit the quotes. When you have S@S hosted at an ISP, ask them for the correct username.

  NOTICE: It is considered a security risk to have 'root' as the MySQL user. Better choose another username.

• MySQL password: Put in the password for your MySQL database server. When you have S@S hosted at an ISP, ask them for the correct password.
• MySQL database name: Leave in 'sas' or put in another name. Do not start the name with a digit. When you have multiple installations of S@S, you can give each installation its own database name. When you have S@S hosted at an ISP, ask them for the correct database name.

  NOTICE: When every S@S user uses the same database name, you make life a bit easier for an eventual cracker. Better use another name. Keep it short.

• Tablename prefix: Leave in 'sn_' or put in another name.When your ISP has given you only one database, you still can have multiple installations of S@S by giving them different prefixes. For example: cms1_, cms2_, etc. The underscore is useful as a separation. Do not use spaces and do not start with a digit.

  NOTICE: When every school that uses S@S uses the same database prefix, you make life easier for an eventual cracker. Better use another prefix. It's easy to separate your prefix and the table name with an '_' (underscore, omit the quotes). Do not start the table name with a number. MySQL does not allow this.

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

6. Choose the installation type.

install_type.png

• Do you want demo data: Yes No:
  When choosing 'Yes', a demo teacher and pupil will be created as well as a couple of demo pages. All modules will be installed and ready for use.
  

  NOTICE: Your installation will end in step [8].

  When choosing 'No', a basic installation will be done without 'anything'.
  

  NOTICE: Your installation will end in step [8a].

  The first one (Yes) is the right one when you are testing Site@School. The second one is advisable when you want to start your site 'from scratch'.
  Ofcourse it is possible to choose 'Yes', test S@S and then remove all data, modules and sections and start building the site.

Make your choice and click on 'Continue'.

7. Create a user for the system.

install_create_user.png

• Full name: Put in your full name, for example Mary Smith.
• User name: Put in a username, for example, marys.
• Password: Choose a password that's easy to remember for the one that uses it and difficult to guess for others. A good password consists of at least 8 characters, upper and lower case and special characters.
  An example: ma0!Ry29 (Mary's name and the birth year and month of her youngest daughter).
• E-mail address: Put in a valid e-mail address. The address is used to send a lost password. S@S has no spyware and does not send this password to us.

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

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

install_login_demodata.png

You have successfully performed the Site@School 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)

install_login_nodemodata.png

You have successfully performed the Site@School 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

• Username: Enter the username you used in step [7]. You can use the 'Tab' key on your keyboard to go to the next field.
• Password: Enter password you used in step [7]. The password you enter is shown in asterisks. This is a security measure.
• |Forgot password?:
  On pre 2.4 sites when you have forgotten your password and you have given a valid email address in step [7], the password will be mailed to you when you click on the link.

  On 2.4 sites passwords are encrypted in the mysql database and therefore a different procedure is followed:

  • An email is send to your email address with a link to your site.
  • When you go to that link a new initial password is emailed to your email address
  • You can use this password to login again and you are forced to change this password immediately.

  For further details, see Password encryption.

• Login: Click on the button, or hit the 'Enter' key on your keyboard to login to Site@School management.

Now you should see:

install_sas_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 Site@School.

(top)

3. After the Installation: security and mailing

3.1 Linux and security

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 Site@School 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 S@S 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.

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

-rw-rw-rw-    1 www www     416 2004-10-28 20:13 database.inc.php

-r--------     1 www www     416 2004-10-28 20:13 database.inc.php

When you have Site@School 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 ./agenda/*
# chmod -R 0755 index.php
# chmod -R 0755 print.php

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

find -type d -print0 | xargs -0 chmod 750 ./starnet

And, of course, the same goes for the agenda directory.

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/sas_check.php. See S@S check below.

3.2 PHP Mail function

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    = "sas.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  

(top)

4. Building your site; some advice

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!:

   • Start adding sections, pages to sections and adding modules to pages.
   • Then make the classes.
   • Add the teachers, giving them their classes.
   • Fill the classes with pupils.
   • Give the pupils their pages (or not), either in the 'Pupils' pages' module or as teacher via the site.

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

• Do not use spaces in filenames and directories. See also below.
• Do not use diacritical characters like ', ~, ^, ", etc.
• Do not use characters like !, \, /, @, #, $, %, ;, :, etc. Make long filenames and directories with the underscore, example: 'bustrip_spring_2002_class2b_johnny.png'.
• Do not use the ' (apostrophe) in login names of users, teachers and pupils, in classes, in files, etc.

NOTICE: We strongly recommend that you download and install the manual. It can be found at our Sourceforge site. Install it (see below).
Thank you very much for reading it. Site@School has a lot of possibilites. Save yourself and us time and RTFM (read the fine manual).
When things are still not clear, visit our Forum.
When asking questions, please state:

• Operating system and version (Linux or Windows).
• Site@School version.
• Apache, MySQL version and PHP versions.

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. Install the manual

NOTICE: When things are still not clear, visit our Forum. When asking questions, state S@S version, OS version, Apache version, MySQL version and PHP version. Give a full description of your problem.
Give a detailed description of all the steps you took.
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.
Good luck with Site@School!
The S@S Team.

(top)

6. Upgrading to a newer version

• We urge you to carefully read the CHANGELOG.txt, the README.txt and MIGRATE.txt texts in ../starnet/install. These texts contain the latest information on changes, on last issues and on how to upgrade.
• Determine the version number of your current installation. This number can be found in Site@School management, in the upper left corner above your login name. In older versions it can be found in the upper right corner.
• Determine the version number of the installation you want. We assume you want the latest version.
• Download the program from our Sourceforge site.
• Unpack the download as described in 'news installation' above. So, the new verion will be copied over your existing version. Your own made changes in language files will be overwritten. See below how you can prevent this.
• Go the the correct URL, as described under 'new installation'. You should see:
  
  install_overview.png

Example:
You have version 2.0 and you want to migrate to version 2.4.
You first have to run the script to upgrade to version 2.1 and then run the second script to upgrade to version 2.2. Then you have to migrate to version 2.3.
That is, the migration is not done in one step, but in three steps. In each new version new database tables are created so you cannot skip versions.
Click on 'migrate2.0_2.1.php' and follow the instructions on the screen. These simply are to click 'Continue' a couple of times. This will upgrade your system to version 2.1.
Now repeat the above steps with the 'migrate2.1_2_2.php' file. This will upgrade your system to version 2.2.
Again, repeat the steps to migrate to version 2.3.
And finally, repeat the steps to migrate to version 2.4.

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/sas_check.php, see the S@S check script.

6.1 Password encryption

In version 2.4 passwords can be stored encrypted in the users table for better security.
When you do a new 2.4 install this is done automatically, when you are migrating from version 2.3 your users table needs to be migrated to be able to store the passwords encrypted, a seperate starnet/install/install_encryption.php must be run.

Because on 2.4 sites passwords are encrypted in the mysql database a different procedure is followed, if you click "forget password" (3):

guidtour_login.jpg

• An email is send to your email address with a link to your site.
• When you go to that link a new initial password is emailed to your email address
• You can use this password to login again and you are forced to change this password immediately.

6.2 Upgrading and your language files

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.

- When you have an older version of S@S you must save your changed language files in the following way. Let's say you have modified your NL language files.

• Descend into ../starnet/languages/media/NL/
• Rename all modified language files from NL.php into NL_user.php.
• Upgrade to the 2.4 version.

After the 2.4 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)

7. Installing modules

NOTICE: Version 2.4 has all available modules installed.

To install new modules run the corresponding install scripts from the HTML page in the ../starnet/install directory:

install_overview._modulesjpg

For example, to install the 'Forum' module, click on 'install_forum.php' and follow the steps on screen. I.e. click on 'Continue' a few times and you are done.
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/sas_check.php, the S@S check sript.

NOTICE: Installing the module does not mean it is functional on your site. The module has to be connected to a page and has to be configured. See the Module manager chapter in the manual on how to connect a module to a page and see the corresponding module chapter to configure the module.

(top)

8. Installation problems

• Read the installation instructions and the manual chapters!
• Use the Site@School check script
• Install PhpMyAdmin
• Ask help

Now we will discusss these options.

Installation manual

"I changed something in s@s management and it's not visible on the site!"
When you have two browser windows open on one computer, i.e. your schoolsite and S@S 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 S@S.
Remedy:
Just logout of the S@S management and press refresh in the other window and the changes will be visible.

Installation check script

install_sas_check1.png

install_sas_check2.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 'sas_check.txt' and set its permissions to 000. These are safety precautions. You should not give information about your configuration to the world!

PhpMyAdmin

TIP: When you have an installation problem and you cannot find its solution, try reinstalling S@S from scratch. Delete /starnet, /agenda, index.php, print.php and the database and start from scratch. In our humble opinion it's the quickest and safest way.

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

• When your login and you are thrown back to the login screen after any action, session support might not be enabled.
  One of the things to look for is in your 'PHP.ini' file:

  session.use_cookies    = 0
  

  It should be set to:

  session.use_cookies    = 1
  

  You can check session support by renaming sas_check.txt to sas_check.php. Point your browser to http://yourschool.org/starnet/sas_check.php (fictional URL, replace with your URL) and look for this entry:
  'Check if server has session management.'
  It has to produce: Check OK! and 'OK!'.
  Reset the sas_check.php to sas_check.txt and its permissions to 000.
• The main error for Linux users: you did not perform the 'chown' command to change owner and group of the S@S directories and files to the owner and group of the webserver. The error you see is:
  
  install_error1.png

  To solve this problem, reead the installation instructions '2.4 Setting ownership of files and directories'.

• Many installation errors occur in 'Step 1: Webserver properties', at the 'serverpath input' fields.
  In the first field should only be the document root, in the second should only be the path to the starnet directory without a leading slash.
• In conjuction with the above problem: When you have more installations of Site@School, you not only have to take care of the correct path to the starnet directory, but also to the database name in the step 'Set the database properties'.

  TIP: Give the directory and the database the same name.

• When you get error messages during the installation process, the best thing to do is to start all over again.
  Remove the starnet and agenda directories and the index.php and print.php file, remove the database (here you use PhpMyAdmin) and start from scratch. It's the easiest, fastest and safest way to obtain an errorfree installation.

Ask help

When asking for help, please state:

• Operating system and version (Linux or Windows).
• Site@School version.
• Apache, MySQL version and PHP versions.

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 request, the first thing we do is try to recreate your problem. Only in this way we can try to fix it. No guarantees.
Good luck with Site@School!
The S@S Team.

(top)