Quick-start installation, Getting Started and Frequently Asked Questions guide:
This document specifies filenames using green bold text and notices and warnings in bold red text. These instructions are for either first time installation or upgrading an old installation. Where differences exist between new installations and upgrading, they will be identified in the instructions below.
A note about upgrading: The install scripts are designed to automatically upgrade a previously installed ORS installation without losing any of the existing configuration of the system (including resources, users, and program configuration settings). As such, upgrading only requires that you perform steps 1-4 of this guide. This includes uploading the new files to your server and rerunning the install script. After upgrading, you may want to review the program configuration settings in case new features have been added which you want to customize.
|
Table of Contents:
|
REQUIREMENTS: PHP version 4.0.5 or higher, Apache server (recommended), and approx. 2 Mb of server space.
1) Unzip the ORS zip file this should create three folders: "install", "help" and "jscalendar-1.0". Please read the license.html file before continuing.
2) NEW INSTALLATIONS: Create a new folder on your web site to hold the scheduler. This document will assume the folder is named "scheduling" but it can be named anything you wish. After creating this folder, you should upload (FTP) the "install" and "help" folders and all files contained in them, into your scheduling folder (You should do this using an "FTP" client; if you are unfamiliar with FTP, take a look at http://tutorial.ftpplanet.com/LE/).
UPGRADING: Upload the new ORS files to the existing install folder on your web site. You should overwrite any files in the install folder with these new files.
3) Point a browser to the page: http://www.mysite.com/scheduling/install/index.html ( replace "www.mysite.com/" with your web-site address such as "www.blarg.net/~myname/" ) You should see the initial installation page with a link to start that the first step of the installation. Click on this link. When the first stage is completed, you will see a message that you should click another link to continue the installation. If the first stage completed successfully, continue to the next step of this guide.
TROUBLESHOOTING:
* If you receive the message:Warning: fopen("../test.txt", "w+") - Permission denied in /[some folder name]/install/install.php on line 44
Install FAILED
We were unable to write to the base scheduling folder (/somefolder/scheduling). It is quite possible that you need to set the permissions on the base folder to "world writeable" to install ORS (you can reset them back to standard permissions after installation). Please see the installation instructions for more information.
the problem is that the PHP system is unable to write into the base scheduling folder. You must either (1) determine if your web host allows you to run PHP as a "CGI" and run it that way (As a CGI, PHP which will often be run with your user permissions, and thus will be able to write to the scheduling folder. How you run as a CGI depends on your web host, contact them) OR (2) you must temporarily set permissions on the base scheduling folder to allow the "world" (aka "other" or "everyone") to be able to write to the folder (chmod scheduling 777, You do this in your FTP client; look for help on "chmod" or "file permissions". After installation you must reset the permissions on this folder so that the "world" can only read and execute this folder, chmod scheduling 755).
MORE TROUBLESHOOTING: FAQs at the end of this document.
REMINDER: If you had to set permissions on your scheduling folder to world-writeable, you should now reset that folder back to world read+execute (755)
4) Click on the "continue installation" link. After the second stage is completed, click on the final link and the configuration page will automatically be brought up (normally, this page can be reached using an administrator account and going to the Utilities Menu, selecting "More..." and selecting "Program Configuration"). You MUST select "update configuration" to finish the installation.
TROUBLESHOOTING:
* If you receive the message: Attempt to create root_dir .htaccess file FAILED You must read the FAQ question relating to this issue.* If you are using a Mac running OS X (and maybe some other systems!) and you make it through the previous step without any problems but, upon "Continuing Installation" of the scheduler, you receive the message:
Warning: fopen("[somefolder]/scheduling/data/scheduling.lock", "w") - Permission denied in [somefolder]/scheduling/functions.php on line [some line]
You must read the FAQ question relating to this issue.
NOTE:
* The default administrator password is "letmein" and the default password to change program configuration is "superpass".
5) CHANGE THE ADMINISTRATOR PASSWORD: If you do not do so, anyone who knows the default password can mess with your settings very disastrously!
6) CHANGE THE ADMINISTRATOR PASSWORD!!! We really mean it! (write it down somewhere) You can also make any user an administrator in the User Management page. If you forget this password, see the FAQ question relating to this issue.
7) Consider changing the program configuration password too. The importance of this depends on the security required for your site. Only administrators can modify the configuration settings. Obviously, only those administrators who know the configuration password can modify the configuration settings. If you have only one administrator, then the password could be set to nothing to make it easier to set the configuration.
8) Review the other configuration settings. Take special note of the URL settings such as the e-mail addresses. Set these to something other than the default e-mail address. After modifying settings, click the "Save Changes" button to save the settings.
NOTE:
* Various settings require you to enter very big values in SECONDS (PHP uses units of seconds for time). To make this easier to read by YOU, you can use multiplication symbols. So instead of entering a backup interval of 7 days as 604800 seconds, enter it as 7*24*60*60 (7 days times 24 hours times 60 minutes times 60 seconds).
9) Use the "Resource Management" page to add resources (see notes below)
10) Use the "User Management" page to add users (see notes below)
11) Custom configuration options:
define ("page_background", ""); //image for background of scheduler pages
and uploading your image to the main scheduling folder.
NOTE: Depending on the exact installation settings of PHP on your web site server, there are a variety of ways that the installation of ORS will vary. What we have just described here are the steps which should get ORS working on most systems no matter how secure the PHP installation. See the FAQ at the bottom of this document for more information.
Lists user signups which break rules set in Program Configuration.
Lists what time and date users were logged in and how long they were logged in for (a ~ means that the user did not "log out". These users MAY still be logged in...)
Lists signup actions (signups, changes, deletions, etc) as well as some adminsitrative changes
Shows the primary list of users. The permissions, account restrictions, and permitted resources are listed following each name along with various "action" buttons: [Edit], [Delete], [Restrict].
Edit - Edit user permissions and information (including contact information).
Delete - Delete user after confirmation.
Restrict - Turn on user "restriction" which requires that the user must sign up in conjunction with a "double-bookable" resource (i.e. another resource such as an instructor).
User fields include:
First Name / Last Name : unique name for this user (MUST be unique!)
Ratings : misc information on this user (used for display only). The name of this field can be set in the configuration settings
Home / Work Phone : for informational purposes only
Email1 / Email2 : Used to contact user when another user makes a change to their signups. Note that both e-mail addresses are always used to send user e-mails.Account Expiration : Date after which this user will be restricted from signing up privileges without also signing up for a "double-bookable" resource (i.e. another resource such as an instructor - see Resource Management).
User Activity : after a predefined period of time without the user logging in or being signed up, a user will become "inactive". The administrator may want to remove these users if they are no longer using the scheduler. To mark a user as "active" again, simply click the [reactivate] action button.
User permissions :
User can sign-up resources Self explanatory... User has calendar authority User can modify other people's signups. User is administrator User can modify users, resources, settings, and view logs.
(These are in addition to the default administrator account)User receives e-mailed logs User receives action log and backup e-mails. Permitted Resources: Defines which resources this user may sign up for and which resources the user is a resource monitor for (Resource monitors receive e-mail whenever any change is made to a given resource).
List of resources for which users can sign up. Use [Add New Resource] link to add a new resource and [Edit] and [Delete] buttons on each resource line to modify existing resources. Fields include:
| Order | : | Position of resource in lists (edit a resource to change its order) |
| Long Description | : | Long name of resource |
| Short Desc. | : | Short name (one word/number/etc - used for day & week views) |
| Initials | : | Very short name (a few unique letters - used for month view) |
| New User Access? | : | Do new users have access to this resource by default? |
| Max Signup Time (Hrs) | : | How long can this resource be booked without a warning? (empty = no limit) |
| Double Book? | : | Can this resource be booked along with another without warnings? (also defines resources which are REQUIRED to be signed up for to allow a restricted user to sign up for regular resources) |
| Deny Public View? | : | Should this resource be hidden on the "public" page (when not logged in) |
| Comments | Any comments in this field will be shown to the user when they click on the (?) help link in the calendar. This field can be used to put additional resource information in (e.g. longer listing of features available on resource) | |
| Warnings | Displayed when a user clicks on the ! triangle and optionally (if Show as "Popup" is checked) when the user signs up for a given resource. | |
| Access | : | Whole-list control of access to this resource (see user management for individual user access control) |
Provides access to additional tools:
Edit Announcements - modify announcement message displayed
to users when the log into the system.
Program Configuration - modify program settings (may
require password). The configuration page includes descriptions of all
the settings.
Make Backup File - creates text file to be used for emergency
restoration of schedule. A backup can be automatically e-mailed to
indicated users through settings in the Program Configuration page.
This menu option is to force the program to send a copy.
Restore from Backup - to be used when restoring from emergency
backup.
Unlock Data Folder - allow read and write access to data
folder (NOTE: Use with caution! Relock when done). This is used when
you need to manually make changes to the scheduling/data folder. It
will allow you to check the files for error. Note that, depending on
how your server is set up, doing this may make the files readable and
writeable by any one who is a user of that server.
Lock Data Folder - disallow read and write access to data folder.
In the downloads section of the ORS website (http://ors.sourceforge.net), you can download the "ResetPassword" utility. This function, when uploaded to your main scheduling folder, should safely reset the administrator password. Make sure you delete the resetpassword file after using it! Otherwise, someone else could force the password to be reset and, thus, have access to your administrator account!
Depending on how your web site host is set up, the ORS program might create files which are not readable by you when you FTP into your website.
Short answer: Don't worry about it. If you use the "backup" feature of the ORS, you will not need to manually backup these files. They can all be restored from the e-mailed backup files. If you need to do this, just follow the instructions provided by "restore from backup" in the "more..." maintenance menu.
Long answer: In some installations of PHP (the language ORS is written in), for scripts to write to a file, the file must be owned by the same user who is running the PHP interpreter. On most systems, this user will be something like "web" (not a normal user like you but a sort of "ghost" user which serves the files). ORS deals with this by creating all of its files itself and then setting permissions of these files so that only that user can read them.
If you want to read or modify the files in the data folder, you can temporarily make these files accessible by logging into the scheduler as an administrator, going to the "Maintenance" menu and selecting "Unlock Data Folder". This will unlock the root data folder, allowing you access. Once done, you should relock the root folder by selecting "Lock Data Folder" from the maintenance menu.
If you cannot log into your scheduler to unlock it, the downloads section of the ORS website (http://ors.sourceforge.net) has a "ForceUnlock" utility which performs the same action as the above command.
Alternatively, if you are blessed, your server might be running a special form of PHP which will allow PHP to run under your name. In this mode, the files will all be owned by you and you can read and write them as you wish. You might want to contact your server administrator and ask them if they allow running "PHP as a CGI" (don't worry if you don't know what it means, just ask it and hope they say "yes"!) If so, you should try creating, in your root scheduling folder, a file named ".htaccess" which contains this single line:
AddType php-cgi .php
This will allow ORS to pretend it is you when it is running and all the files it creates will be accessible by you.
Attempt to create root_dir .htaccess file FAILED
For some reason, your data folder was not protected from Internet users browsing your files. You should secure your users' personal information by creating a file named .htaccess containing the lines:
<Limit GET>
Order Deny,Allow
Deny from All
</Limit>
then upload this file (using FTP) to your scheduling/data folder. If you cannot write to this folder, see the unlockroot instructions under the FAQ question: "Why can't I read or modify the ORS files or the data or backup folders?"
Warning: fopen("[somefolder]/scheduling/data/scheduling.lock", "w") - Permission denied in [somefolder]/scheduling/functions.php on line [some line]
The web server doesn't have permissions to modify the files in the scheduling/data folder. Check with your system administrator but you will probably need to change the entire /scheduling folder and all it's contents to be owned by the group "web" or "www" (depending on your system setup). This will make the scheduling files accessable to the web server.
If your web host requires that your PHP files be named something other than ".php" (for example, some require ".php4") there are two options for solving this problem:
Option 1: Create a configuration file which instructs the web server to interpret ".php" as ".php4".
AddType application/x-httpd-php4 .phpThese files should be created in the base scheduling folder and the install folder.
<Files *.php>
AddType exp=*.php type=application/x-httpd-php4
</Files>These files should be created in the base scheduling folder and the install folder.
Option 2: (if option 1 is not possible) Edit the install/default.php file and locate the line which reads:
define("required_php_extension", ".php");
On this line, you can insert the correct extension in place of ".php". Next, rename the install/install.php file to have the correct extension (rename ONLY this file! The others will be renamed automatically) and then repeat step 3 of the installation instructions.
Two methods:
(A) From the Maintenance/More... menu (accessible only as an administrator), select "Restore From Backup". From the Available Backup File list, select "** Uninstall ORS Database **". This will remove all the Data files. The remaining files in the scheduling folder can usually be deleted using any standard FTP program. See note below if you are unable to remove the remaining files.
(B) To uninstall ORS, you should first use the maintenance menu to unlock the data folder (If you can't log in or otherwise access this folder, the downloads section of the ORS website, http://ors.sourceforge.net, has a "ForceUnlock" utility which performs the same action). You can then simply delete the entire scheduling folder as desired.
If you are still unable to remove all the files and folders from the scheduling
folder, contact your system administrator. An administrator can always remove
the folder and its contents. Nothing is stored outside of the base scheduling
folder.