Merge branch 'master' of github.com:chamilo/chamilo-lms

Author: AngelFQC

public/documentation/installation_guide.html

@@ -10,7 +10,7 @@ <h1>Chamilo 2 installation guide</h1>
   <p>
       This is the official Chamilo installation guide for version 2+.
   </p>
-  <h2>Requirements</h2>
+  <h2>1. Requirements</h2>
   <a id="requirements" class="anchor"></a>
 
   This version of Chamilo requires the following software stack.
@@ -44,22 +44,22 @@ <h2>Requirements</h2>
       <li>redis (optional)</li>
       <li>xapian (optional)</li>
   </ul>
-  <h2>Web-panel installation</h2>
+  <h2>2. Web-panel installation</h2>
   <a id="web-install" class="anchor"></a>
-    <h3>Database</h3>
+    <h3>2.1. Database</h3>
     <a id="web-install-db" class="anchor"></a>
 
       Make sure you have a database available with full permissions.<br>
       Do not share that database with another application as Chamilo might need to create
       a table that has the same name as a table in the other application.
 
-    <h3>Virtual host</h3>
+    <h3>2.2. Virtual host</h3>
     <a id="web-install-vhost" class="anchor"></a>
       Define a new virtual host/subdomain name you will use for Chamilo (Chamilo 2 does *not* work as a sub-folder of an existing website, you need a subdomain like "elearning.yourdomain.com").<br>
       Upload and/or unzip your Chamilo files inside your web folder (usually inside a folder called "public_html/").<br>
       Configure a virtual host pointing at the "public" directory inside your Chamilo directory. For example, this could be "/home/elearning.yourdomain.com/public_html/chamilo2/public/".<br>
 
-    <h3>Files permissions</h3>
+    <h3>2.3. Files permissions</h3>
     <a id="web-install-permissions" class="anchor"></a>
       Make sure the following files and folders are writeable by the web server. Set permissions to 0770 for example:
       <ul>
@@ -74,7 +74,7 @@ <h3>Files permissions</h3>
       ("/home/elearning.yourdomain.com/public_html/chamilo2/"). If you do the whole folder,
       don't forget to write down the permissions it had initially, and return it to its original
       permissions when the installation is over.
-    <h3>PHP settings</h3>
+    <h3>2.4. PHP settings</h3>
     <a id="web-install-php" class="anchor"></a>
 
       Some PHP settings are recommended, but the default values should be enough to get you started.<br>
@@ -89,20 +89,19 @@ <h3>PHP settings</h3>
         <li><a href="https://php.net/manual/ini.core.php#ini.post-max-size">post_max_size</a> >100M</li>
         <li><a href="https://www.php.net/manual/en/ini.core.php#ini.memory-limit">memory_limit</a> >128M</li>
       </ul>
-    <h3>Installation wizard</h3>
+    <h3>2.5. Installation wizard</h3>
     <a id="web-install-wizard" class="anchor"></a>
       You are ready to go. Open your browser on your subdomain (elearning.yourdomain.com in the example above), keep your database credentials at hand, and let the Chamilo installer guide you.
 
-    <h3>Sessions and Redis</h3>
+    <h3>2.6. Sessions and Redis</h3>
     <a id="web-install-sessions" class="anchor"></a>
       In this beta version, there are known issues with sessions not getting updated fast enough, which can be solved (temporarily) by using a Redis server. Check the command line instructions for more about this. This is a temporary situation that we expect to fix before the stable release.
 
-  <h2>Command line installation</h2>
+  <h2>3. Command line installation</h2>
   <a id="cli-install" class="anchor"></a>
 
-    <h3>Software stack</h3>
+    <h3>3.1. Software stack</h3>
     <a id="cli-install-stack" class="anchor"></a>
-
 <p>Assuming you are using a dedicated Ubuntu 24.04 LTS, these commands should help you have the software stack installed in a breeze. Otherwise, please review the requirements above and make sure they are met before moving on to the next section.</p>
 <pre>
 sudo -s
@@ -124,9 +123,8 @@ <h3>Software stack</h3>
 # give a MariaDB root password twice and answer the default "Y" to anything else. The root password is *not* the one you gave above here.
 </pre>
 
-    <h3>Database</h3>
+    <h3>3.2. Database</h3>
     <a id="cli-install-db" class="anchor"></a>
-
 <p>You will need a database user with privilege to fully use (and optionally create) a database.<br>
 Although progress has been made to support multiple database management systems, Chamilo
 currently only supports MariaDB and MySQL.<br>
@@ -143,7 +141,7 @@ <h3>Database</h3>
     <li>[db-host] is the name of the database server (use <em>localhost</em> when using the same machine for web server and database server - if you use a hosted service, your hosting provider will usually give you this name somewhere)</li>
     <li>[db-password] is the password this user will use to connect to this database on this host. Use common sense to not make it too easy to guess (use special characters, lowercase and uppercase, numbers, and a length of *at least* 8 characters)</li>
 </ul>
-    <h3>Web server</h3>
+    <h3>3.3. Web server</h3>
     <a id="cli-install-httpd" class="anchor"></a>
 Chamilo 2+ only requires a working web server setup to work. You can run it on localhost with the default installation of any web server, provided you configure your DocumentRoot as the path pointing to Chamilo's <em>public/</em> subfolder.<br>
 Here is an example Apache vhost configuration file for an installation on the http://my.chamilo.local/ URL (replace all values between brackets, including the brackets, to your custom values).<br>
@@ -179,7 +177,7 @@ <h3>Web server</h3>
   <pre>
 a2ensite [my.chamilo.local]
 systemctl restart apache2</pre>
-    <h3>Files permissions</h3>
+    <h3>3.4. Files permissions</h3>
     <a id="cli-install-permissions" class="anchor"></a>
     Make sure the following files and folders are writeable by the web server. Set permissions to 0770 for example:
     <ul>
@@ -194,74 +192,73 @@ <h3>Files permissions</h3>
 
     Both .env and config/ should be changed back to less permissive permissions after the installation is over.
 
-    <h3>PHP settings</h3>
+    <h3>3.5. PHP settings</h3>
     <a id="cli-install-php" class="anchor"></a>
     Some PHP settings are recommended, but the default values should be enough to get you started.<br>
     See vhost config's "php_value" section above for details.
 
-    <h3>Installation wizard</h3>
+    <h3>3.6. Installation wizard</h3>
     <a id="cli-install-wizard" class="anchor"></a>
     You should now be able to direct your browser to your URL (e.g. <em>[http://my.chamilo.local]</em>).<br>
     Chamilo will pick it up from there and offer the installation wizard to help guide you through the rest of the process.
 
-  <h2>Command line upgrade from 1.11.*</h2>
+  <h2>4. Command line upgrade from 1.11.*</h2>
   <a id="cli-upgrade" class="anchor"></a>
-
-    <h3>Database</h3>
+    <h3>4.1. Database</h3>
     <a id="cli-upgrade-db" class="anchor"></a>
     Before you start, it is *critical* to delete the <em>version</em> table from your Chamilo 1.11.* database.
     Failure to do this will make the command line upgrade fail immediately after starting.
     The <em>version</em> table is not necessary for Chamilo 1.11.* to work, so don't leave it there.
 
-    <h3>Files</h3>
+    <h3>4.2. Files</h3>
     <a id="cli-upgrade-files" class="anchor"></a>
       The files from Chamilo 1.11.* will be used as source but they will be copied and rearranged
       in the new Chamilo 2 installation, so you will have to indicate a source for the files to the (web or CLI) installer.<br>
       Note the extra pages created in 1.11.x and stored under app/home/ are *not* migrated. They will need to be created again in Chamilo 2 using the "pages" feature.
 
-    <h3>PHP settings</h3>
+    <h3>4.3. PHP settings</h3>
     <a id="cli-upgrade-php" class="anchor"></a>
       Make sure no setting is in the way of a command line upgrade.
       Limits such as memory_limit or max_execution_time should be
       vastly increased for the time of the upgrade.
 
-    <h3>E-mail settings</h3>
+    <h3>4.4. E-mail settings</h3>
     <a id="cli-upgrade-email" class="anchor"></a>
       In Chamilo 1.11.*, the e-mail settings were stored in the app/config/mail.conf.php file.<br>
       This is *NOT* the case in Chamilo 2. Instead, the e-mail settings can be configured directly from the
       web panel (Administration &gt; Settings &gt; E-mail).<br>
       Those settings are *NOT* automatically migrated to the new format, so you will have to do it manually in the new, DSN, format. See settings page in your admin panel for more details.
 
-    <h3>Execution</h3>
+    <h3>4.5. Execution</h3>
     <a id="cli-upgrade-exec" class="anchor"></a>
       // To be completed
 
-  <h2>Web panel upgrade from 1.11.*</h2>
+  <h2>5. Web panel upgrade from 1.11.*</h2>
   <a id="web-upgrade" class="anchor"></a>
 
-    <h3>Database, Host, Permissions, Files and PHP settings</h3>
+    <h3>5.1. Database, Host, Permissions, Files and PHP settings</h3>
     <a id="web-upgrade-all" class="anchor"></a>
     For all requirements previous to the installation wizard, see the command line upgrade instructions above.
     Note the installation folder for Chamilo 2 will be different from the installation folder from Chamilo 1, as explained in the "Files" section above.
 
-    <h3>Installation wizard</h3>
+    <h3>5.2. Installation wizard</h3>
     <a id="web-upgrade-wizard" class="anchor"></a>
     On step 2 of the installation wizard, make sure you select "Upgrade from a previous version of Chamilo" and click "Continue".<br>
     Follow the wizard to complete the upgrade.<br>
     Please be aware that upgrading your system might take hours or even days, depending on the size and complexity of your database. Refer to the Chamilo forum or to official providers for help.
 
-  <h2>Installing on Windows</h2>
+  <h2>6. Installing on Windows</h2>
   <a id="windows-install" class="anchor"></a>
-    <h3>Introduction</h3>
+    <h3>6.1. Introduction</h3>
     Although Chamilo does work on Windows, it is not officially supported due to the fact that
     we have limited testing capabilities for this operating system. The following instructions have been
     tested on a Windows 11 (desktop) machine with the WAMP application.
     We do not recommend using Windows for production environments.
 
-    <h3>Installation for validation or production</h3>
+    <h3>6.2. Installation for validation or production</h3>
     <a id="windows-install-env" class="anchor"></a>
 
-      <h4>WampServer</h4>
+      <h4>6.2.1. WampServer</h4>
       <a id="windows-install-wamp" class="anchor"></a>
         <a href="https://www.wampserver.com/">Download</a> and install WampServer (accept default options if in doubt).<br>
         Restart WampServer to make these changes effective.<br>
@@ -287,9 +284,9 @@ <h4>WampServer</h4>
         Note: If you use your Windows machine for development, you might
         get errors related to VisualC++. The error itself will point to
         wampserver.aviatechno.net, which seem to be a valid source to download a VisualC++ patch.
-        We do not take responsibility about software from other sources. Do your own research.
+        We do not take responsibility about software from other sources. Do your own research.<br><br>
 
-      <h4>Database</h4>
+      <h4>6.2.2. Database</h4>
       <a id="windows-install-db" class="anchor"></a>
         Click on the WampServer icon in the status bar (bottom right) and select PhpMyAdmin.<br>
         Choose the MariaDB service and connect to the root user. Enter the root password you set during WampServer installation (probably still empty).<br></br>
@@ -298,17 +295,17 @@ <h4>Database</h4>
         We recommend setting a proper user and password for that specific database,
         but the root account should also be secured with a different password
         if you plan to expose this to the internet.<br>
-        Click "Create".<br>
+        Click "Create".<br><br>
 
-      <h4>Chamilo</h4>
+      <h4>6.2.3. Chamilo</h4>
       <a id="windows-install-files" class="anchor"></a>
         Download the latest install-ready package available for version 2
         from <a href="https://github.com/chamilo/chamilo-lms/releases">https://github.com/chamilo/chamilo-lms/releases</a>.<br>
         Unzip the package in C:\wamp64\www\chamilo2.<br>
         Create a ".env" file at the root of the chamilo2 folder (C:\wamp64\www\chamilo2\.env).<br>
-        If this is not a stable version package, edit the ".env.dist" file and set APP_ENV to "prod".<br>
+        If this is not a stable version package, edit the ".env.dist" file and set APP_ENV to "prod".<br><br>
 
-      <h4>Apache</h4>
+      <h4>6.2.4. Apache</h4>
       <a id="windows-install-apache" class="anchor"></a>
         Open the Apache configuration file at C:\wamp64\bin\apache\apache2.4.*\conf\extra\httpd-vhosts.conf.<br>
         Modify the contents of the file to something like this:<br>
@@ -324,7 +321,7 @@ <h4>Apache</h4>
 &lt;/VirtualHost&gt;
 </pre>
 
-      <h4>Installation wizard</h4>
+      <h4>6.2.5. Installation wizard</h4>
       <a id="windows-install-wizard" class="anchor"></a>
         Open your browser on <a href="http://chamilo.local/">http://chamilo2.local</a>. The installation wizard should appear.<br>
         Follow the instructions to complete the installation.<br>
@@ -334,25 +331,25 @@ <h4>Installation wizard</h4>
         make sure you have properly configured your domain name first.
 
 
-    <h3>Installation for developers</h3>
+    <h3>6.3. Installation for developers</h3>
     <a id="windows-install-dev" class="anchor"></a>
       If you want to *develop* Chamilo, you will need still need to install
       WampServer as detailed above, but you will also need a few additional
-      components to be able to prepare the package from Git.
+      components to be able to prepare the package from Git.<br><br>
 
-      <h4>WampServer</h4>
+      <h4>6.3.1. WampServer</h4>
       <a id="windows-install-dev-wamp" class="anchor"></a>
-        See above.
+        See above.<br><br>
 
-      <h4>Composer</h4>
+      <h4>6.3.2. Composer</h4>
       <a id="windows-install-dev-composer" class="anchor"></a>
         <a href="https://getcomposer.org/download/">Download</a> and install
         Composer (accept default options if in doubt).<br>
         If the installation is correct, you should be able to run
         "composer -V" in a command prompt (PowerShell or CMD) and see the
-        version of Composer appear (probably 2.x).
+        version of Composer appear (probably 2.x).<br><br>
 
-      <h4>Node.js</h4>
+      <h4>6.3.3. Node.js</h4>
       <a id="windows-install-dev-nodejs" class="anchor"></a>
         To install Node.js, you can use the official installer from
         <a href="https://nodejs.org/en/download/">https://nodejs.org/en/download/</a>
@@ -364,13 +361,13 @@ <h4>Node.js</h4>
         Then we need to install Yarn. In a command prompt *as administrator*,
         run "corepack enable".<br>
         Check the installation with "yarn --version", then
-        run "corepack prepare yarn@stable --activate".<br>
+        run "corepack prepare yarn@stable --activate".<br><br>
 
-      <h4>Database</h4>
+      <h4>6.3.4. Database</h4>
       <a id="windows-install-dev-db" class="anchor"></a>
-        See above.
+        See above.<br><br>
 
-      <h4>Chamilo</h4>
+      <h4>6.3.5. Chamilo</h4>
       <a id="windows-install-dev-chamilo" class="anchor"></a>
         In a PowerShell or CMD:<br>
 <pre>
@@ -383,20 +380,20 @@ <h4>Chamilo</h4>
     yarn dev
 </pre>
         Create a ".env" file at the root of the chamilo2 folder
-        (C:\wamp64\www\chamilo2\.env).<br>
+        (C:\wamp64\www\chamilo2\.env).<br><br>
 
-      <h4>Apache</h4>
+      <h4>6.3.6. Apache</h4>
       <a id="windows-install-dev-apache" class="anchor"></a>
-        See above.
+        See above.<br><br>
 
-      <h4>Installation wizard</h4>
+      <h4>6.3.7. Installation wizard</h4>
       <a id="windows-install-dev-wizard" class="anchor"></a>
         Open your browser on <a href="http://chamilo.local/">http://chamilo2.local</a>. The installation wizard should appear.<br>
         Follow the instructions to complete the installation.<br>
 
         Note that it is difficult to change URLs later, so if you plan to publish this service online, make sure you have properly configured your domain name first.
 
-    <h3>Redis</h3>
+    <h3>6.4. Redis</h3>
     <a id="windows-install-redis" class="anchor"></a>
       For better performance in the highly dynamic interfaces of Chamilo, you might
       want to install the PHP Redis extension from the official PHP website, for example (adapt PHP and Redis version numbers)
@@ -433,7 +430,28 @@ <h3>Redis</h3>
 
       Restart the WampServer and you should be able to access Chamilo.
 
-  <h2>Help available</h2>
+  <h2>7. Xapian text indexation</h2>
+
+  Xapian allows you to index texts and documents in Chamilo and search them using a full-text search engine.<br>
+  However, installing Xapian is not trivial and requires a few manual steps.<br>
+  This is probably not supported for Windows setups (untested), but it should work on Linux and macOS.<br>
+  To install Xapian (a requirement to use the internal search engine), follow the instructions below.<br>
+  <pre>
+      sudo apt install libxapian-dev catdoc html2txt unrtf
+      cd /tmp
+      wget https://oligarchy.co.uk/xapian/1.4.25/xapian-bindings-1.4.25.tar.xz
+      # use 1.4.25 because this matches the version of the libxapian-dev package on Ubuntu 25.04
+      tar -xJf xapian-bindings-1.4.25.tar.xz
+      cd xapian-bindings-1.4.25
+      ./configure
+      make install
+  </pre>
+  This should make the Xapian extension available from Chamilo.<br>
+  Next, go to Settings -&gt; Search -&gt; Enable, and follow the instructions there.<br>
+  Once this is done, a checkbox will appear in several tools when uploading, creating or editing different elements, to ask you wether to index these or not.<br>
+  Finally, a search box appears in the "My courses" page, allowing you to search for content through the whole platform.<br>
+
+  <h2>8. Help available</h2>
   <a id="install-help-channels" class="anchor"></a>
   If you are struggling with this guide, don't hesitate to ask for help on
   <a href="https://github.com/chamilo/chamilo-lms/discussions">our community forum.</a><br>