Skip to content

updated the install.md for ILIAS 10 #11194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rfalkenstein wants to merge 1 commit into
base: release_10
Choose a base branch
from
+79 −80
Open

updated the install.md for ILIAS 10 #11194

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 79 additions & 80 deletions docs/configuration/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,15 +132,15 @@ Composer may be optional when using the prepacked ILIAS from [Download & Release
apt install apache2 libapache2-mod-php php php-gd php-xsl php-imagick php-curl php-mysql php-xmlrpc php-soap php-ldap composer
```

Create a directory for the html sources (e.g. `/var/www/ilias`) which is referenced in the apache2 vhost and also a directory outside the web servers docroot (e.g. `/var/www/files`) for files stored by ILIAS.
Make sure that the web server is the owner of the files and directories that were created by changing the group and owner to www-data (on Debian/Ubuntu) or apache (on RHEL).
Create a directory for the html sources (e.g. `/var/www/ilias`) which is referenced in the apache2 vhost (the apache2 vhost will use `/var/www/ilias/public`) and also a directory outside the web servers docroot (e.g. `/var/www/files`) for files stored by ILIAS.
Make sure that the web server user is the owner of the files and directories that were created by changing the group and owner to www-data (on Debian/Ubuntu) or apache (on RHEL).

In addition to the file folder, ILIAS also needs a place to create the log files
(e.g. `/var/www/logs`). The 'ilias.log' can be viewed there later, as well as all
error_log files, which are created in case of errors and are referenced in ILIAS by
an errorcode.
an error code.

Also, to store the ILIAS configuration, which is later used to configurate ILIAS, we create the folder /var/www/config. To prevent future issues with npm we create /var/www/.npm with webowner rights.
Also, to store the ILIAS configuration, which is later used to configure ILIAS, we create the folder /var/www/config. To prevent future issues with npm we create /var/www/.npm which belongs to the web server user.

```shell
mkdir /var/www/ilias
Expand All @@ -155,7 +155,7 @@ chown www-data:www-data /var/www/.npm
```

Usually Apache ships with a default configuration (e.g. `/etc/apache2/sites-enabled/000-default.conf` on Debian based
systems). A minimal configuration for ILIAS may look as follows:
systems). A minimal configuration for ILIAS may look like this:

```apacheconf
<VirtualHost *:80>
Expand Down Expand Up @@ -184,7 +184,7 @@ a2enmod rewrite
systemctl restart apache2.service
```

To check if the installation was successfull create the file `/var/www/ilias/phpinfo.php` with the following contents:
To check if the installation was successful create the file `/var/www/ilias/public/phpinfo.php` with the following contents:

```
<?php
Expand All @@ -194,7 +194,7 @@ phpinfo();
Then point your browser to ```http://example.com/phpinfo.php```.
If you see the content of the file as shown above, your configuration is **not** working.
If you can see details of your PHP configuration, everything works fine.
Search for the entry ```Loaded configuration file``` as we now made some changes to it (e.g. `/etc/php5/apache2/php.ini`).
Search for the entry ```Loaded configuration file``` as we now make some changes to it (e.g. `/etc/php8.3/apache2/php.ini`).
Delete the file `phpinfo.php` afterwards.

We recommend at least the following settings for your php.ini:
Expand Down Expand Up @@ -228,7 +228,7 @@ allow_url_fopen = 1
max_input_vars = 10000
```

Restart the apache webserver after you installed and configured your dependencies.
Restart the apache2 webserver after you installed and configured your dependencies.

```shell
systemctl restart apache2.service
Expand All @@ -239,7 +239,7 @@ Please see [Hardening and Security Guidance](#hardening-and-security-guidance) f
Remember to reload your web server configuration to apply those changes.

Please ensure that PHP is compiled with `libargon2`.
This is mostly the case for common distributions, but if you compile PHP yourself, it must be build with `--with-password-argon2[=DIR]` (see: https://www.php.net/manual/en/password.installation.php).
This is mostly the case for common distributions, but if you compile PHP yourself, it must be built with `--with-password-argon2[=DIR]` (see: https://www.php.net/manual/en/password.installation.php).

<a name="install-database"></a>
## Database Installation/Configuration
Expand Down Expand Up @@ -292,19 +292,19 @@ which is the development branch of the repository.
We recommend to clone from GitHub and use git to update the code, since this simplifies
the update to future releases and versions.

Clone the code to the web servers docroot (e.g. `/var/www/html`) with the following
Clone the code to the web servers docroot (e.g. `/var/www/ilias`) with the following
commands:

```shell
cd /var/www/ilias/
sudo -uwww-data git clone https://github.com/ILIAS-eLearning/ILIAS.git . --single-branch -b release_10
cd /var/www
sudo -u www-data git clone --single-branch -b release_10 https://github.com/ILIAS-eLearning/ILIAS.git ilias
```
<details>
<summary>If you use tags to directly reference ILIAS versions</summary>

```shell
cd /var/www/ilias/
sudo -uwww-data git clone https://github.com/ILIAS-eLearning/ILIAS.git . --single-branch -b v10.X
cd /var/www
sudo -u www-data git clone --single-branch -b v10.X https://github.com/ILIAS-eLearning/ILIAS.git ilias
```
</details>

Expand All @@ -314,20 +314,21 @@ sudo -uwww-data git clone https://github.com/ILIAS-eLearning/ILIAS.git . --singl
Download the file from the [Download & Releases](https://docu.ilias.de/go/lm/35) page.

```shell
sudo -uwww-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -uwww-data tar -xzf ILIAS-10.X.tar.gz -C /var/www/ilias --strip-components=1 ILIAS-10.X/
sudo -u www-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -u www-data tar -xzf ILIAS-10.X.tar.gz -C /var/www/ilias --strip-components=1 ILIAS-10.X/
```
</details>

The GitHub repository of ILIAS doesn't contain all code that is required to run. To download the required PHP-dependencies and
to create static artifacts from the source, run the following in your ILIAS folder:
The GitHub repository of ILIAS doesn't contain all code that is required to run. To download the required dependencies and
to create static artifacts from the source, run the following in your ILIAS directory (the directory that contains composer.lock and package-lock.json).
This will create a new directory called public which is the root directory for your webserver:
```shell
sudo -uwww-data npm clean-install --omit=dev --ignore-scripts
sudo -uwww-data composer install --no-dev
sudo -u www-data npm clean-install --omit=dev --ignore-scripts
sudo -u www-data composer install --no-dev
```

> [!IMPORTANT]
> We recommend restricting the rights of the ILIAS code in the production system so that the web server only has
> We recommend restricting the permissions of the ILIAS code in the production system so that the web server only has
> read access to the code. For this and other important security considerations, please refer to the security
> instructions in the [Security Guide](./secure.md).
Expand All @@ -346,7 +347,7 @@ and add the fields that your environment and installation requires.
cp /var/www/ilias/components/ILIAS/setup_/minimal-config.json /var/www/config/ilias.json
```

A typical configuration might look like this afterwards:
A typical configuration might look like this:

```json
{
Expand All @@ -372,9 +373,9 @@ A typical configuration might look like this afterwards:
},
"systemfolder" : {
"contact" : {
"firstname" : "Richard",
"lastname" : "Klees",
"email" : "richard.klees@concepts-and-training.de"
"firstname" : "Lucy",
"lastname" : "Snowe",
"email" : "lucysnowe@ilias.de"
}
},
"utilities" : {
Expand All @@ -393,24 +394,18 @@ Run the ILIAS command line setup from within your ILIAS folder with your configu
file (located outside your doc-root!) as a parameter:

```shell
sudo -uwww-data php cli/setup.php install /var/www/config/ilias.json
sudo -u www-data php cli/setup.php install /var/www/config/ilias.json
```

The installation will display what currently happens and might prompt you with
questions. You might want to have a look into the [documentation of the command line setup](../../components/ILIAS/setup_/README.md)
or into the help of the program itself `php cli/setup.php help`. It is the tool
to manage and monitor your ILIAS installation.

If you are installing from Git, it is possible that ILIAS will already require a few migrations to the initial
database. Run the setup migration and follow the steps shown. This is also necessary whenever you update your code.

```shell
php cli/setup.php migrate
```

Now that you have ILIAS installed, you can start by logging in as root. Go to your http path and log in with the
Now that you have ILIAS installed, you can start by logging in as root. Go to your http path and log in with the
username `root` and password `homer`. ILIAS will ask you for a new password after the first login.


<a name="install-further"></a>
## Install Further Components

Expand Down Expand Up @@ -443,7 +438,7 @@ A variety of free plugins is provided from our community via the [ILIAS Plugin R
To develop plugins, you can get started in our [Development Guide](https://docu.ilias.de/go/pg/27030_42).

Custom styles are the way to modify the look of your ILIAS installation. Have
a look in the [documentation of the System Styles and Custom Styles](../../templates/Readme.md)
a look at the [documentation of the System Styles and Custom Styles](../../templates/Readme.md)
to learn how to build and install them.

<a name="backup-ilias"></a>
Expand All @@ -453,17 +448,17 @@ There are three places where the ILIAS core system stores data that needs to be
system in case of failure.
* Internal data within your webroot `<ILIAS-root-folder>/public/data` in our case `/var/www/ilias/public/data`.
* External data, configured in `ilias.json` within `filesystem.data_dir`, in our case `/var/www/files/ilias`.
* The database, which can easily be done by running `mysqldump'.
* The database, which can easily be dumped by running `mysqldump'.
```shell
mysqldump --lock-tables=false -u<database user> -p <database name> > /path/to/your/backup/folder/ilias-backup.sql
mysqldump --lock-tables=false -u <database user> -p <database name> > /path/to/your/backup/folder/ilias-backup.sql
# Prompt for password
```

When restoring the ILIAS files to the designated folder, remember to set the correct permissions and ownership of your
web server. To restore the database, drop the old database with `DROP DATABASE <database-name>;`, create an empty
database according to [Database Installation/Configuration](#install-database) and write the database dump to this database:
```shell
mysql -u<database-user> -p <database-name> < /path/to/your/backup/folder/ilias-backup.sql
mysql -u <database-user> -p <database-name> < /path/to/your/backup/folder/ilias-backup.sql
# Prompt for password
```

Expand All @@ -474,7 +469,7 @@ The easiest way to update ILIAS is using Git. Please note that this is only poss
if you installed ILIAS via Git as advised in this document. If Git wasn't used you
can also [download](https://docu.ilias.de/go/lm/35) new releases.

Before you start you should consider to [backup](#backup-ilias).
Before you start we strongly advise you to make a [backup](#backup-ilias).

<a name="minor-upgrade"></a>
## Minor Upgrade
Expand All @@ -483,19 +478,19 @@ To apply a minor update (e.g. v10.1 to v10.2) execute the following command in
your ILIAS basepath (e.g. `/var/www/ilias/`):

```shell
sudo -uwww-data git pull origin release_10
sudo -uwww-data npm clean-install --omit-dev --ignore-scripts
sudo -uwww-data composer install --no-dev
sudo -u www-data git pull origin release_10
sudo -u www-data npm clean-install --omit-dev --ignore-scripts
sudo -u www-data composer install --no-dev
```

<details>
<summary>If you use tags to directly reference ILIAS versions</summary>

```shell
sudo -uwww-data git fetch origin v10.X:v10.X
sudo -uwww-data git checkout v10.X
sudo -uwww-data npm clean-install --omit-dev --ignore-scripts
sudo -uwww-data composer install --no-dev
sudo -u www-data git fetch origin v10.X:v10.X
sudo -u www-data git checkout v10.X
sudo -u www-data npm clean-install --omit-dev --ignore-scripts
sudo -u www-data composer install --no-dev
```
</details>

Expand All @@ -505,17 +500,17 @@ sudo -uwww-data composer install --no-dev
Download the archive of the newest ILIAS minor version on the [Download & Releases](https://docu.ilias.de/go/lm/35) page.

```shell
sudo -uwww-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -uwww-data mkdir /tmp/ilias_update
sudo -uwww-data tar -xzf ILIAS-10.X.tar.gz -C /tmp/ilias_update --strip-components=1 ILIAS-10.X/
sudo -uwww-data rsync -av --exclude='/public/' --exclude='/Customizing/' --exclude='/data/' --exclude='ilias.ini.php' /tmp/ilias_update/ /var/www/ilias/
sudo -u www-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -u www-data mkdir /tmp/ilias_update
sudo -u www-data tar -xzf ILIAS-10.X.tar.gz -C /tmp/ilias_update --strip-components=1 ILIAS-10.X/
sudo -u www-data rsync -av --exclude='/public/' --exclude='/Customizing/' --exclude='/data/' --exclude='ilias.ini.php' /tmp/ilias_update/ /var/www/ilias/
rm -rf /tmp/ilias_update
```
If you have plugins installed, you will need to rebuild the classmap, including all plugins. You will need to call
`composer du` to do this.

```shell
sudo -uwww-data composer du
sudo -u www-data composer du
```
</details>

Expand All @@ -536,15 +531,15 @@ layout templates. Then execute the following commands in your ILIAS basepath
(e.g. `/var/www/ilias`).

```shell
sudo -uwww-data git fetch origin release_10:release_10
sudo -uwww-data git checkout release_10
sudo -u www-data git fetch origin
sudo -u www-data git checkout release_10
```
<details>
<summary>If you use tags to directly reference ILIAS versions</summary>

```shell
sudo -uwww-data git fetch origin v10.X:v10.X
sudo -uwww-data git checkout v10.X
sudo -u www-data git fetch origin v10.X:v10.X
sudo -u www-data git checkout v10.X
```
</details>

Expand All @@ -554,39 +549,38 @@ sudo -uwww-data git checkout v10.X
Download the archive of the newest ILIAS minor version from the [Download & Releases](https://docu.ilias.de/go/lm/35) page.

```shell
sudo -uwww-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -uwww-data mkdir /tmp/ilias_update
sudo -uwww-data tar -xzf ILIAS-10.X.tar.gz -C /tmp/ilias_update --strip-components=1 ILIAS-10.X/
sudo -uwww-data rsync -av --exclude='/public/' --exclude='/Customizing/' --exclude='/data/' --exclude='ilias.ini.php' /tmp/ilias_update/ /var/www/ilias/
sudo -u www-data wget https://github.com/ILIAS-eLearning/ILIAS/releases/download/v10.X/ILIAS-10.X.tar.gz
sudo -u www-data mkdir /tmp/ilias_update
sudo -u www-data tar -xzf ILIAS-10.X.tar.gz -C /tmp/ilias_update --strip-components=1 ILIAS-10.X/
sudo -u www-data rsync -av --exclude='/public/' --exclude='/Customizing/' --exclude='/data/' --exclude='ilias.ini.php' /tmp/ilias_update/ /var/www/ilias/
rm -rf /tmp/ilias_update
```
</details>
After upgrading the code from ILIAS 9 to ILIAS 10 due to structural changes, you need to move the `/Customizing/global/plugins`
and `/data` folder to its new destination. Both are now located in the newly created `public` folder.
and `/data` folder to its new destination. Both are now located in the newly created `public` folder. If this `public` folder does not exist yet you
will have to execute the npm and composer command first:

```shell
cd /var/www/ilias
sudo -u www-data npm clean-install --omit=dev --ignore-scripts
sudo -u www-data composer install --no-dev
sudo -uwww-data mkdir -p public/Customizing/global/plugins
mv data public/
mv data/* public/data/
mv Customizing/global/plugins/* public/Customizing/global/plugins/
```

Then update the code of your plugins according to their documentation to ensure they are compatible with the new ILIAS version.
If you are **not** using the tar.gz archive to upgrade your release, update your javascript and php dependencies. If you
are using a tar.gz archive and are using plugins, reload your php classmap with `composer du`.

```shell
sudo -uwww-data npm clean-install --omit-dev --ignore-scripts
sudo -uwww-data composer install --no-dev
```

Complete the update of the base system by [updating the database](#update-the-database).

As a last step, you should log in with a User using your custom skin. If everything
works fine, change back from Delos to your custom system style. If not, you probably
will need to update your style to match the new release.

<a name="update-the-database"></a>
## Update the Database
## Update the Database and doing migrations to IRSS

Database updates must be done for both minor and major updates, the schema and content
of the database probably won't match the code otherwise. Database updates are performed
Expand All @@ -596,16 +590,14 @@ make your installation work properly. **Migrations** are tasks, that potentially
some time, but which can also be executed while the installation is in productive use.

Run the `status` command on the command line to check if there are any updates
available and if ILIAS is responding. After this you need to perform the update.
available and if ILIAS is responding. After this you need to perform the update.

```
php cli/setup.php update
```

To check if there are migrations, run in your ILIAS folder.
Please make sure to check for migrations before you run the update. If there are migrations left
please make sure that these are done before updating.

```
php cli/setup.php migrate
```shell
cd /var/www/ilias
sudo -u www-data php cli/setup.php migrate
```

The command will show you if there are migrations that need to be run for you
Expand All @@ -617,9 +609,16 @@ questions. You might want to have a look into the [documentation of the command
or into the help of the program itself `php cli/setup.php help`. It is the tool
to manage and monitor your ILIAS installation.

As soon as all migrations are done you can do the database update:

```shell
cd /var/www/ilias
sudo -u www-data php cli/setup.php update
```

Database updates are performed in steps; it might happen that a step fails, e.g. due
to some edge case or inconsistency in existing data, files, etc.
In this case, a concecutive command `php setup/setup.php update` will error with
In this case, a consecutive command `php setup/setup.php update` will error with
a message like
> step 2 was started last, but step 1 was finished last.
> Aborting because of that mismatch.
Expand All @@ -628,17 +627,17 @@ You may reset the records for those steps by running:
```shell
php cli/setup.php achieve database.resetFailedSteps
```
However, be sure to understand the cause for the failing steps and tend to it before
However, be sure to understand the cause for the failing steps and take care of it before
resetting and running update again.

<a name="information-updates"></a>
## Information on Updates

To keep your ILIAS Installation secure and healthy it is important that you keep
it up to date. To get informations about updates and security fixes you should
consider subscribing to the [ILIAS Admin Mailing-List](http://lists.ilias.de/cgi-bin/mailman/listinfo/ilias-admins). Information on the
it up to date. To get information about updates and security fixes you should
consider subscribing to the [ILIAS Admin Mailing-List](https://lists.ilias.de/postorius/lists/ilias-admins.lists.ilias.de/). Information on the
new versions, such as Important Changes, Known Issues, Changed Behaviour and Fixed
Issues, can be found in the release notes in [Download & Releases](https://docu.ilias.de/go/lm/35).
Issues, can be found in the release notes in [Download & Releases](https://docu.ilias.de/go/pg/197850_35).

<a name="connect-and-contribute"></a>
# Connect and Contribute
Expand Down