INSTALL.txt 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333
  1. *****************************************
  2. Dokeos 1.8 INSTALLATION
  3. *****************************************
  4. Thank you for downloading Dokeos! This text will guide you through the
  5. basics of installing Dokeos 1.8. Please read this fully
  6. before proceeding with the installation.
  7. This is only a short installation guide. We are writing a manual with more
  8. info on installation, but this was not ready at the time of writing. When
  9. ready, this manual will be accessible through the Dokeos documentation
  10. page:
  11. http://www.dokeos.com/documentation.php
  12. You can also read the work in progress manual on our web writing area:
  13. http://www.dokeos.com/wiki/index.php/Manual
  14. Contents
  15. 1. Requirements
  16. 2. Installing a new version of Dokeos
  17. 3. Upgrading from a previous version of Dokeos
  18. 4. Troubleshooting
  19. 5. Administration section
  20. 6. Ldap (optional)
  21. =================
  22. 1. Requirements
  23. =================
  24. Dokeos is a web application which requires some other software to function:
  25. a web server, PHP, and the MySQL database server. These software packages
  26. have to be installed on the computer where you will install Dokeos.
  27. You can install all these software packages separately, which often gives
  28. the best results. However, beginning users who want to test Dokeos can use
  29. a combination package that installs all these software packages in one
  30. simple install. If you want to use a combination package, we recommend
  31. Wamp (you also need the PHP4 add-on for WAMP) or XAMP.
  32. WAMP5 website: http://www.wampserver.com/en/index.php
  33. WAMP PHP4 add-on: http://www.wampserver.com/en/add-ons.php
  34. XAMP: http://www.apachefriends.org/en/index.html
  35. 1.1. A web server
  36. The Apache web server is recommended, and Dokeos is configured to use some
  37. Apache security enhancements if possible. However, other web servers will
  38. work too. For best security results, you need to have the Apache module
  39. mod_rewrite activated. The mod_rewrite rules for Dokeos are read from a
  40. .htaccess file in the courses folder, so Apache needs to allow this
  41. (AllowOverride FileInfo in httpd.conf).
  42. Download Apache web server:
  43. http://httpd.apache.org/download.cgi
  44. 1.2. PHP
  45. You need PHP version 4.3.2 or later (4.x versions), configured with the
  46. following modules : mysql, zlib, preg, xml. PHP versions 5 or later are not
  47. supported by Dokes yet. You need the ldap module too if you want to use ldap
  48. with Dokeos. Most of the PHP4 compiled distributions are provided with these
  49. modules. Their presence is also checked by the Dokeos install script.
  50. Download PHP:
  51. http://www.php.net/downloads.php
  52. Some users could meet problems if their PHP setting doesn't fit these ones:
  53. short_open_tag = On
  54. safe_mode = Off
  55. magic_quotes_gpc = On
  56. magic_quotes_runtime = Off
  57. Past Dokeos versions required register_globals to be set to On. This is no
  58. longer necessary, this can be set to Off and Dokeos will work fine.
  59. BSD users:
  60. these php libraries have to be included during php installation:
  61. - php-mysql The mysql shared extension for php
  62. - php-pcre The pcre shared extension for php
  63. - php-session The session shared extension for php
  64. - php-zlib The zlib shared extension for php
  65. - (optional) php-ldap if you want to be able to use LDAP authentication
  66. 1.3. The MySQL database server
  67. And a login/password allowing to administrate and create at least one
  68. database. By default, Dokeos will create a new database for each course
  69. created. It means your host should allow you to create and administrate
  70. several databases. If you want to use Dokeos on a 'single database host'
  71. you have to select this option during the installation.
  72. Download MySQL server:
  73. http://dev.mysql.com/downloads/
  74. Note:
  75. It seems the backticks characters (`) inserted inside most of the Dokeos SQL
  76. queries since version 1.3 don't work with MySQL versions before 3.23.6.
  77. 1.4. Permissions
  78. Furthermore, you need web Write access to web directory where Dokeos has
  79. been moved or unzipped to. On a Windows machine locally, this is not a
  80. problem. Remotely, you need to be allowed to CHMOD through FTP, telnet or
  81. any means.
  82. =======================================
  83. 2. Installing a new version of Dokeos
  84. =======================================
  85. 2.1. Download the Dokeos 1.8 install package (.zip for Windows users
  86. or .tar.gz for all others) from the Dokeos download page:
  87. http://www.dokeos.com/download.php
  88. 2.2. Unzip or untar the downloaded install package. Most current operating
  89. systems can do this with a built-in graphical application, if this doesn't
  90. work you can open a commandline, go to the download directory and type
  91. tar -zxvf dokeos-1.8.tar.gz
  92. 2.3. Move by any means (FTP, SCP, local file copy) the contents of the
  93. Dokeos install package to your website on your webserver (whether webroot
  94. or subdirectory). Your webserver can also be your local computer. Be sure
  95. to copy all the folders (archive, home, claroline, courses) as well as all
  96. the .php files.
  97. For Windows users: If you use e.g easyphp locally (http://www.easyphp.org),
  98. just drag and drop the contents of the Dokeos install package into
  99. C:\Program Files\easyphp\www\
  100. 2.4. The following files need to be readable and writeable for everyone:
  101. dokeos/main/inc/conf/claro_main.conf.php (if present)
  102. dokeos/home/*.html
  103. On Linux, Mac OS X and BSD operating systems you can use the CHMOD 666
  104. command for this. In Windows, you may need to check the properties of
  105. the folders.
  106. NOTE:
  107. Do not modify the home_*.html files directly. Instead, choose "Configure
  108. the homepage" in the Dokeos administration section.
  109. 2.5. The following directories need to be readable, writeable and executable
  110. for everyone:
  111. dokeos/main/inc/conf/
  112. dokeos/main/garbage/
  113. dokeos/main/upload/
  114. dokeos/archive/
  115. dokeos/courses/
  116. dokeos/home/
  117. On Linux, Mac OS X and BSD operating systems you can use the CHMOD 777
  118. command for this. In Windows, you may need to check the properties of
  119. the folders.
  120. 2.6. Open a web browser and go to
  121. http://www.yourserver.org/yoursite/dokeos/index.php
  122. For Windows users locally, with e.g easyphp or another combination package,
  123. open http://localhost/dokeos/index.php
  124. 2.7. Click on the install button and follow instructions. Windows: with
  125. combination packages like easyphp, out of the box, login and password for
  126. MySQL should probably remain empty.
  127. 2.8. Security after installation
  128. Protect your configuration file
  129. make sure no one can overwrite it. You can find the config file in (dokeos
  130. folder)/main/inc/conf/claro_main.conf.php. Make it read-only
  131. (windows/xwindows: right-click the file to edit the properties.
  132. linux/bsd/macosx: use the chmod 444 command).
  133. Protect your installation folder
  134. if the (dokeos folder)/main/install folder is still accessible,
  135. someone could install over your existing version (you could lose your data
  136. that way). Move the folder somewhere out of the web directories so it is
  137. not accessible, change its name, or edit its properties so no one can read
  138. or execute it.
  139. ===============================================
  140. 3. Upgrading from a previous version of Dokeos
  141. ===============================================
  142. Before upgrading we heavily recommend you do a full backup of the previous Claroline or Dokeos directories and databases. If you are unsure how to achieve this please ask your hosting provider for advice.
  143. 3.1. Download the Dokeos 1.8 install package (.zip for Windows users
  144. or .tar.gz for all others) from the Dokeos download page:
  145. http://www.dokeos.com/download.php
  146. 3.2. Unzip or untar the downloaded install package. Most current operating systems can do this with a built-in graphical application, if this doesn't work you can open a commandline, go to the download directory and type tar -zxvf dokeos-1.6.beta.tar.gz
  147. 3.3. Move the Dokeos directory to a different path from the previous version
  148. WARNING:
  149. Do not delete the previous Dokeos installation directory before installing the new one. When the update is successfully finished, you can remove the old path.
  150. TIP:
  151. If you want Dokeos 1.8 to be installed in the same directory as the previous version :
  152. move the old directory to a new location (e.g. move dokeos/ to dokeos_old/)
  153. uncompress Dokeos 1.8 to the old version directory (e.g. uncompress Dokeos 1.6 to dokeos/)
  154. go to next step
  155. 3.4. The following files need to be readable and writeable for everyone:
  156. dokeos/main/inc/conf/claro_main.conf.php (if present)
  157. dokeos/home/*.html
  158. On Linux, Mac OS X and BSD operating systems you can use the CHMOD 666 command for this. In Windows, you may need to check the properties of the folders.
  159. NOTE:
  160. Do not modify the home_*.html files directly. Instead, choose "Configure the homepage" in the Dokeos administration section.
  161. 3.5. The following directories need to be readable, writeable and executable for everyone:
  162. dokeos/main/inc/conf/
  163. dokeos/main/garbage/
  164. dokeos/main/upload/
  165. dokeos/archive/
  166. dokeos/courses/
  167. dokeos/home/
  168. On Linux, Mac OS X and BSD operating systems you can use the CHMOD 777 command for this. In Windows, you may need to check the properties of the folders.
  169. 3.6. Open a web browser and go to http://www.yourserver.org/yoursite/dokeos/index.php Windows locally, with e.g easyphp or another combination package, open: http://localhost/dokeos/index.php
  170. 3.7. Click on the install button, then click on "Update from Dokeos 1.5 | 1.5.4 | 1.5.5" and follow the instructions.
  171. 3.8. This part is optional!
  172. Since after version 1.5.5, the following tables in the dokeos_main database can be removed when upgrading from a 1.5.5 version or lower, provided that you don't use them for a customisation of your Dokeos system:
  173. `todo`
  174. `pma_bookmark`
  175. `pma_column_comments`
  176. `pma_pdf_pages`
  177. `pma_relation`
  178. `pma_table_coords`
  179. `pma_table_info`
  180. These tables can be removed by connecting to the database as the Dokeos user and executing this query: DROP TABLE dokeos_main.my_table; where dokeos_main is the main dokeos database name and my_table is each of the preceding tables (repeat query for each)
  181. A clean-up of the useless fields has also influenced some code: The main_db.cours.cours_id has been removed, as all references to that field throughout the official Dokeos code. The course code (literal) is used instead. Please update your custom code if any.
  182. Under the same circumstances as tables removal, the following fields can be removed if not used by your code, using a query similar to: ALTER TABLE database.table drop column abc where database is the database name (dokeos_main? or code of a course) table is the table name (cours?) abc is the name of the field to drop You can thus drop the following fields:
  183. `_dokeos_main_`.`cours`.`versionDb`
  184. `_dokeos_main_`.`cours`.`versionClaro`
  185. `_dokeos_main_`.`cours`.`cahier_charges`
  186. `_dokeos_main_`.`faculte`.`bc`
  187. # the table `faculte` has been renamed to `course_category` since 1.6
  188. `_cours_`.`announcement`.`code_cours`
  189. `_cours_`.`course_description`.`upDate`
  190. ===========================
  191. 4. Troubleshooting
  192. ===========================
  193. In the future we will also provide instructions on how to do a "manual"
  194. install of Dokeos, by creating the database tables yourself. If you have
  195. any problems, go to the Dokeos website and ask a question on our support
  196. forum. Please read the previous messages first to see if there is already
  197. an answer to your question. We also maintain a list of Frequently Asked
  198. Questions (FAQ).
  199. Dokeos website: http://www.dokeos.com/
  200. Support forum: http://www.dokeos.com/forum/
  201. Frequently Asked Questions: http://www.dokeos.com/wiki/index.php/FAQ
  202. ===========================
  203. 5. Administration section
  204. ===========================
  205. To access the Dokeos administration section, open browser, go to your Dokeos adress and log in with the admin user. Then you will see a "Platform admin section" link in the header of the web page.
  206. ===========================
  207. 6. LDAP
  208. ===========================
  209. This part is optional, only organisations with an LDAP server will need to read this.
  210. An LDAP module is already provided in Dokeos, but it has to be configured to make it work.
  211. 6.0. Compiling
  212. Linux servers: It's possible that you have to recompile php with ldap support.
  213. Newer distributions also allow downloading rpms for additional packages.
  214. 6.1. Activating
  215. In main/inc/conf/claro_main.conf.php, around line 90, you see
  216. //for new login module
  217. //uncomment these to activate ldap
  218. //$extAuthSource['ldap']['login'] = "./main/auth/ldap/login.php";
  219. //$extAuthSource['ldap']['newUser'] = "./main/auth/ldap/newUser.php";
  220. remove the // from the last two lines to activate LDAP.
  221. 6.2. Settings
  222. Ask the LDAP server admin for the settings:
  223. - ldap server name
  224. - ldap server port (usually 389)
  225. - ldap dc
  226. You must enter these in
  227. main/auth/ldap/ldap_var.inc.php
  228. //parameters for LDAP module
  229. $usesLDAP = TRUE;
  230. $usesCurriculum = FALSE;
  231. $ldaphost = "myldapserver.com"; // your ldap server
  232. $ldapport = 389; // your ldap server's port number
  233. $ldapDc = "dc=xx, dc=yy, dc=zz"; //domain
  234. 6.3. Teacher/student status
  235. If you wish, you can give teacher/student status to dokeos users according to settings in the ldap server.
  236. This is not a standard field however, so you'll have to change some code.
  237. main/auth/ldap/ldap_var.inc.php
  238. around line 189, function putUserInfoInClaroline ($login, $infoArray)
  239. if (<your criterium>)
  240. {
  241. $statut = STUDENT;
  242. }
  243. else
  244. {
  245. $statut = COURSEMANAGER;
  246. }
  247. If this seems too difficult, the simplest solution is to just put
  248. $statut = STUDENT;
  249. and give course manager rights through the admin panel.
  250. 6.4. Some LDAP servers do not support anonymous use of the directory services.
  251. In this case, you need code that binds with a name and password - this code has already been provided,
  252. just ask on a forum or email for this.
  253. ==========================================================================
  254. Contact address: Dokeos, 44 rue des palais, B-1030 Brussels, Belgium
  255. Mail: info@dokeos.com
  256. May 2005
  257. ================================== END ===================================