Skip to content

Latest commit

 

History

History
530 lines (428 loc) · 22.1 KB

CONTRIBUTING.md

File metadata and controls

530 lines (428 loc) · 22.1 KB

Contributing

Chamilo LMS is a free software learning management platform.

The Chamilo project includes documentation, a mobile app, a terminal console, integrations with other projects and a series of related subprojects that are part of the Chamilo ecosystem.

Chamilo LMS is a LAMP-based e-learning web platform that focuses on providing an easy-to-use environment for teachers to improve both the quality and availability of their educational material and on providing students with an awesome learning platform.

Before you report an issue, please check the official Chamilo documentation (not always up to date).

The Chamilo "editorial" team is small and greatly welcomes any external contribution. We will thoroughly review them before integration to make sure they do not introduce security vulnerabilities or degrade the platform's ease of use, but we do appreciate any sincere effort to help.

Version 3.0 of Chamilo is composed of 2 parts: one (now minor) legacy part located mostly in the "public/main" folder, and the main Symfony-based part located in the "src" folder (with support of a VueJS frontent in assets/vue/).

Any contribution to the project should either strive to convert legacy code to Symfony or to add new features to the Symfony part.

Installing Chamilo

The following instructions are all intended to set a development environment up for Chamilo 3. If you want to install Chamilo on a production server, please refer to the official installation guide in the documentation/ folder.

Requirements

Hardware

We recommend developing Chamilo on a machine with at least

  • 8GB of RAM (or 4GB + 4GB of swap on SSD/NVMe)
  • 2 powerful CPUs
  • about 10GB of disk space

Software

Installing Chamilo for development

Quick step-by-step

You will need PHP8.3, 8.4 or 8.5 and NodeJS v20+ to run Chamilo 2.

On Ubuntu 24.04+, the following should take care of all dependencies (certbot is optional).

Replace 'chamilo' by the database name and user you want, and '{password}' by a more secure password.

sudo apt update && apt -y upgrade
sudo apt install apache2 libapache2-mod-php mariadb-client mariadb-server php-pear php-{apcu,bcmath,cli,curl,dev,gd,intl,ldap,mbstring,mysql,soap,xml,zip} git unzip curl certbot
sudo mysql
mysql> CREATE USER chamilo@localhost IDENTIFIED BY '{password}';
mysql> GRANT ALL PRIVILEGES ON chamilo.* TO chamilo@localhost;
mysql> exit
cd ~
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
sudo corepack enable
cd ~
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer
cd /var/www
git clone -b master --depth=1 https://github.com/chamilo/chamilo-lms.git chamilo
cd chamilo
composer install
sudo a2enmod rewrite ssl headers expires
sudo cp public/main/install/apache.dist.conf /etc/apache2/sites-available/my.chamilo.net.conf
# edit if you want to change the local domain name
sudo a2ensite my.chamilo.net
sudo systemctl restart apache2
yarn set version stable
yarn up && yarn install && NODE_OPTIONS="--max-old-space-size=4096" yarn dev
# The NODE_OPTIONS is to avoid "FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory", use this instead of only "yarn dev"
sudo touch .env
sudo chown -R www-data: var/ .env config/
# load http://my.chamilo.net in your browser and follow the installation wizard
sudo chown -R root: .env config/

Detailed procedure

The following is the section above, but with more details and hedge cases.

sudo apt update
sudo apt -y upgrade
sudo apt install apache2 libapache2-mod-php mariadb-client mariadb-server php-pear php-{apcu,bcmath,cli,curl,dev,gd,intl,ldap,mbstring,mysql,soap,xml,zip} git unzip curl certbot
sudo mysql
mysql> CREATE USER chamilo@localhost IDENTIFIED BY '{password}';
mysql> GRANT ALL PRIVILEGES ON chamilo.* TO chamilo@localhost;
mysql> exit

On older Ubuntu versions (like 22.04), you have to install PHP through third-party sources:

sudo apt update
sudo apt -y upgrade
sudo apt -y install ca-certificates curl gnupg software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install apache2 libapache2-mod-php8.3 mariadb-client mariadb-server php-pear php8.3-{apcu,bcmath,cli,curl,dev,gd,intl,ldap,mbstring,mysql,soap,xml,zip} git unzip curl
sudo mysql
mysql> CREATE USER chamilo@localhost IDENTIFIED BY '{password}';
mysql> GRANT ALL PRIVILEGES ON chamilo.* TO chamilo@localhost;
mysql> exit

(replace 'chamilo' by the database name and user you want, and '{password}' by a more secure password)

NodeJS, Yarn, Composer

If you already have nodejs installed, check the version with node -v Otherwise, install Node.js 20 or above.

Use the following lines to get a static version of Node.js 20 from https://deb.nodesource.com/ (recommended)

cd ~
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

Alternative (not recommended): install Node.js by using NVM (Node Version Manager). You can install it following the instructions here. You can install the desired node version (preferably, the LTS version):

sudo nvm install --lts
sudo nvm use --lts

Once NodeJS is installed, you must enable corepack and then continue with the requirements

sudo corepack enable
cd ~

Follow the instructions at https://getcomposer.org/download/ to get Composer, then add it to the local binaries for easier use:

sudo mv composer.phar /usr/local/bin/composer

Apache tweaks

Apache's rewrite module is mandatory if you use Apache. The rest is optional and depends on your needs.

sudo apt install libapache2-mod-xsendfile #only for optimization if used in the vhost config
sudo a2enmod rewrite ssl headers expires
sudo systemctl restart apache2

When your system is all set, you can use the following:

cd /var/www
git clone -b master --depth=1 https://github.com/chamilo/chamilo-lms.git chamilo
cd chamilo
composer install

We do not recommend running composer as the root user! When asked whether you want to execute the recipes or install plugins for some of the components, you can safely type 'n' (for 'no').

yarn set version stable
# delete yarn.lock if present, as it might contain restrictive packages from a different context
yarn up && yarn install && yarn dev
# you can safely ignore any "warning" mentioned by yarn dev
sudo touch .env
sudo chown -R www-data: var/ .env config/

In your web server configuration, ensure you allow for the interpretation of .htaccess (AllowOverride all or Require all granted), and point the DocumentRoot to the public/ subdirectory. Finally, make sure your PHP config points at Redis for sessions management. This should look similar to the short excerpt below (in your Apache vhost block) if you use SSL. If you do not use SSL, you can remove the first block and change *:443 by *:80 for the second block.

<VirtualHost *:80>
  ServerName my.chamilo.net
  RewriteEngine On
  RedirectMatch 302 (.*) https://my.chamilo.net$1
</VirtualHost>
<VirtualHost *:443>
  DocumentRoot /var/www/chamilo/public/
  ServerName my.chamilo.net
  # Error logging rules...
  # SSL rules...
  RewriteEngine On
  <Directory /var/www/chamilo/public>
    AllowOverride All
    Require all granted
  </Directory>
  <LocationMatch "/.git">
    Require all denied
  </LocationMatch>
  php_value session.cookie_httponly 1
  php_admin_value upload_max_filesize 256M
  php_admin_value post_max_size 256M
</VirtualHost>

Don't forget to reload your Apache configuration after each change:

sudo systemctl reload apache2

Quick updates for development/testing purposes

If Chamilo is already installed in a development environment and you only want to update the code and dependencies, use:

git pull origin master
composer install && php bin/console cache:clear && chown -R www-data: var/cache && yarn install && NODE_OPTIONS="--max-old-space-size=4096" yarn dev && php bin/console cache:warmup && chown -R www-data: var/cache
php bin/console doctrine:migrations:migrate --no-interaction

Note: the double chown in the command above is just to make sure you can use your Chamilo portal in the meantime. In some cases, yarn dev or cache:warmup might take a while to "come back", and in the meantime the changes you have made through composer install might have written some files or created some directories to var/cache as another user, which might prevent Chamilo itself to write its cache there while yarn is running.

If your local clone uses a fork, replace origin with the remote that tracks the official Chamilo repository (commonly upstream).

doctrine:migrations:migrate is the normal way to update the database of an existing development installation. Do not use doctrine:schema:update --force as a replacement: schema updates do not execute the data-processing logic contained in migrations and can result in data loss.

Occasionally a change can add data to a migration that your local database has already marked as executed. In that specific case, re-run the migration explicitly as instructed by the change:

php bin/console doctrine:migrations:execute "Chamilo\CoreBundle\Migrations\Schema\V300\Version[date]" --up

Fixtures for development and testing

Doctrine fixtures are intended for fresh or disposable development/test databases. doctrine:fixtures:load purges existing data by default, so do not run it against a database containing data you want to keep.

For the PHPUnit test database, after creating the schema as described in tests/README.md, load the fixtures with:

php bin/console --env=test doctrine:fixtures:load --no-interaction

Playwright uses additional browser-level seed scenarios. Run them once, in this order, before the main browser test suite:

yarn test:playwright:seed
yarn test:playwright:seed-course
yarn test:playwright:seed-private-course
yarn test:playwright:seed-settings

These seeds create the fixed test users, the TEMP and TEMPPRIVATE courses, and the platform settings expected by the Playwright scenarios. The yarn test:playwright:install command is destructive because it recreates the database and is intended for CI installation testing, not for updating an existing development environment.

Fixture groups are not a substitute for migrations on an existing installation. Changes that must reach already-installed databases should be delivered through the corresponding migration.

If an update causes dependency or cache problems, first retry the normal installation commands (composer install, yarn install, and php bin/console cache:clear) before removing lock files or replacing pinned dependencies.

Refresh configuration settings

In case you believe some settings in Chamilo might not have been processed correctly based on an incomplete migration or a migration that was added after you installed your development version of Chamilo, the /admin/settings_sync URL is built to try and fix that automatically by updating PHP classes based on the database state. This issue rarely happens, though.

Quick re-install

If you have it installed in a dev environment and feel like you should clean it up completely (might be necessary after changes to the database), you can do so by:

  • Removing the .env file
  • Loading the {url}/main/install/index.php page again

The database should be automatically destroyed, table by table. In some extreme cases (a previous version created a table that is not necessary anymore and creates issues), you might want to clean it completely by just dropping the database, but this shouldn't be necessary most of the time.

If, for some reason, you have issues with either composer or yarn, a good first step is to delete completely the vendor/ folder (for composer) or the node_modules/ folder (for yarn).

Development setup (Dev environment, stable environment not yet available)

If you are a developer and want to contribute to Chamilo in the current development branch (not stable yet), then please follow the instructions below. Please bear in mind that the development version is NOT STABLE at this time, and many features are just not working yet. This is because we are working on root components that require massive changes to the structure of the code, files and database. As such, to get a working version, you might need to completely uninstall and re-install from time to time. You've been warned.

First, apply the procedure described here: Managing CSS and JavaScript in Chamilo (in particular, make sure you follow the given links to install all the necessary components on your computer).

Then make sure your database supports large prefixes (see this Stack Overflow thread if you use MySQL < 5.7 or MariaDB < 10.2.2).

Load the (your-domain)/main/install/index.php URL to start the installer (which is very similar to the installer in previous versions).

If the installer is pure-HTML and doesn't appear with a clean layout, that's probably because you didn't follow these instructions carefully. Go back to the beginning of this section and try again.

If you want hot reloading for assets use the command yarn run encore dev-server. This will refresh automatically your assets when you modify them under assets/vue. Access your chamilo instance as usual. In the background, this will serve assets from a custom server on http://localhost:8080. Do not access this url directly since Encore is in charge of changing url assets as needed.

Supporting PHP 7.4 and 8.3 in parallel

You might want to support PHP 8.3 (for Chamilo 2) and PHP 7.4 (for all other things) on the same server simultaneously. On Ubuntu, you could do it this way:

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.3 libapache2-mod-php7.4 php8.3-{modules} php7.4-{modules}
sudo apt remove libapache2-mod-php8.3 php7.4-fpm
sudo a2enmod proxy_fcgi
sudo vim /etc/apache2/sites-available/[your-chamilo-vhost].conf

In the vhost configuration, make sure you set PHP 8.3 FPM to answer this single vhost by adding, somewhere between your <VirtualHost> tags, the following:

  <IfModule !mod_php8.c>
    <IfModule proxy_fcgi_module>
        <IfModule setenvif_module>
        SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
        </IfModule>
        <FilesMatch ".+\.ph(ar|p|tml)$">
            SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"
        </FilesMatch>
        <FilesMatch ".+\.phps$">
            Require all denied
        </FilesMatch>
        <FilesMatch "^\.ph(ar|p|ps|tml)$">
            Require all denied
        </FilesMatch>
    </IfModule>
  </IfModule>

Then exit and restart Apache:

sudo systemctl restart apache2

Finally, remember that PHP settings will have to be changed in /etc/php/8.3/fpm/php.ini and you will have to reload php8.3-fpm to take those config changes into account.

sudo systemctl reload php8.3-fpm

When using 2 versions, you will also have issues when calling composer update, as this one needs to be called by the relevant PHP version. This can be done like so:

/usr/bin/php8.3 /usr/local/bin/composer update
or, for Chamilo 1.11
/usr/bin/php7.4 /usr/local/bin/composer update

If your default php-cli uses PHP7.4 (see ln -s /etc/alternatives/php), you might have issues running with a so-called platform_check.php script when running composer update anyway. This is because this script doesn't user the proper launch context, and you might need to change your default settings on Ubuntu (i.e. change the link /etc/alternatives/php to point to the other php version) before launching composer update. You can always revert that operation later on if you need to go back to work on Chamilo 1.11 and Composer complains again.

git hooks

composer install points git at tests/scripts/git-hooks/, so every clone gets the project hooks without any manual step. If you cloned before that change, or composer ran with --no-scripts, enable them with:

git config core.hooksPath tests/scripts/git-hooks/

An existing core.hooksPath of your own is never overwritten.

The pre-push hook runs ECS (the tool behind composer phpcs-fix) over the PHP files of the commits you push. If it finds a code style problem, it fixes the files in your working tree and stops the push. Add the fix to your commits and push again:

git add -u && git commit --amend --no-edit

The hook uses the php of your machine when it can see vendor/. If it cannot, the hook uses the Docker container chamilo2-php83. Set CHAMILO_PHP or CHAMILO_PHP_CONTAINER if your setup is different. To skip the hook one time, push with --no-verify.

Big changes from 1.x (for developers)

This is a list of structural changes to help developers/maintainers of Chamilo 1.11 find their way in Chamilo 2. It is not a features list (refer to public/documentation/changelog.html for that).

  • in general, the main/ folder has been moved to public/main/
  • a big part of the frontend has been migrated to VueJS + Tailwind CSS (see assets/vue/)
  • app/Resources/public/assets/ moved to assets/
  • main/inc/lib/javascript/ moved to assets/js/
  • main/img/ moved to public/img/
  • main/template/default/ moved to src/CoreBundle/Resources/views/
  • src/Chamilo/XXXBundle/ moved to src/CoreBundle/ or src/CourseBundle/
  • bin/doctrine.php removed, use bin/console doctrine:xyz options
  • plugin images, CSS and JS libs are loaded inside the public/plugin/ folder and the folder names have been renamed to CamelCase
  • plugins templates use the asset() function instead of using _p.web_plugin
  • main/inc/local.inc.php has been removed and main/inc/global.inc.php greatly reduced
  • translations are managed through Gettext, from the translations/ directory for PHP code and from assets/locales/ for VueJS code
  • files in app/config/ have been restructured (to .yaml) and moved to config/
  • app/config/configuration.php has essentially been emptied to the settings table (accessible via the admin page in Chamilo), while the critical settings (database access etc) have been transferred to .env

Libraries

  • Integration with Symfony 7.4
  • PHPMailer replaced with Symfony's Mailer
  • Bower replaced by yarn

Contributing patches or new features

If you'd like to contribute to this project, please read the following documents:

  • Coding conventions: The main conventions document
  • PSR-1: PSR-1 are standard conventions rules we use as a base (conversion of old code still in progress)
  • PSR-2: PSR-2 are more detailed standard conventions rules we use as base (conversion of old code still in progress)

We expect contributions to be sent through Pull Requests, a very clean feature of our versioning control platform. We recommend you follow this guide to understand a little more about the way it works: https://guides.github.com/activities/contributing-to-open-source/

In short, we ask you to send us Pull Requests based on a branch that you create with this purpose into your own repository, forked from the original Chamilo repository (master branch).

Testing new features

As new major features are added, automated tests should be added that ensure that the feature continues to work for the foreseeable future.

In Chamilo, we rely on "Playwright":https://playwright.dev/ (with "playwright-bdd":https://vitalets.github.io/playwright-bdd/, so the scenarios stay plain Gherkin) to do Automated Behavior Testing. You can find the feature files in tests/playwright/features/, the shared step definitions in tests/playwright/steps/, and run them with yarn test:playwright.

Tests are run automatically for every new contribution, courtesy of Github actions, so you can follow your feature in time and see whether something breaks it. Check the Chamilo tests URL here: https://github.com/chamilo/chamilo-lms/actions

Making changes to the database

If your changes require database changes, here are a few instructions on how to proceed. You will then need to submit these changes as explained above.

Database structure changes

If your changes are about structure, you want to follow these steps:

  1. Create or modify an entity in src/somethingBundle/Entity/
  2. Create a new Migration in src/CoreBundle/Migrations/Schema/V{VERSION}/Version{time-stamp}.php

This second step is most easily done by copying one of the current migration files in that directory. For example, if you're doing it on the 14th of July 2019 at noon:

  1. Copy Version20190527120703.php to Version20190714120000.php
  2. Edit the file and change any "20190527120703" you find to "20190714120000"
  3. Check it works by issuing an update command from the command line:
php bin/console migrations:execute 20190714120000 --up --configuration=app/config/migrations.yml

Database data changes

If you only want to change the data in the database, then you don't need to modify or create an entity, but you will still need to follow these two steps:

  1. Modify one of the fixtures in src/CoreBundle/DataFixtures/
  2. Create a new Migration in src/Chamilo/CoreBundle/Migrations/Schema/{version}/

For configuration settings, check https://github.com/chamilo/chamilo-lms/wiki/Add-a-new-Chamilo-setting

Testing through Docker

Coming soon...