Merge branch 'next' into mouss-user-guide-general-updates

Author: MoustaphaCamara

doc/contributing.rst

@@ -243,18 +243,6 @@ Install the database
    docker exec -it elabftw bin/init db:install
 
 
-* Enable debug mode to disable the caching of Twig templates
-
-.. code-block:: bash
-
-    # go back to where elabctl is present
-    cd $dev
-    ./elabctl mysql
-    # you are now on the mysql command line
-    mysql> update config set conf_value = '1' where conf_name = 'debug';
-    exit;
-    exit
-
 Finishing up
 ^^^^^^^^^^^^
 
@@ -508,3 +496,20 @@ Locally: current workaround:
    ./node_modules/.bin/cypress open
 
 Not great, not terrible.
+
+Debugging mysql queries
+=======================
+
+Connect as root in the MySQL container:
+
+.. code-block:: bash
+
+   docker exec -it mysql
+   mysql -uroot -p$MYSQL_ROOT_PASSWORD
+   mysql> SET GLOBAL general_log = ON;
+   # check where it is saved
+   mysql> SHOW VARIABLES WHERE Variable_name IN ('general_log','log_output','general_log_file');
+   # exit mysql
+   tail -f /var/lib/mysql/abcd1234.log
+
+This will log ALL queries.

doc/coordinator-guide.rst

@@ -0,0 +1,28 @@
+.. _coordinator-guide:
+
+*****************
+Coordinator guide
+*****************
+
+What is an Instance Coordinator
+===============================
+
+An instance coordinator helps manage the users in an instance. For example, they may add and remove users from different teams, and help to implement exit strategies for users and data. More information about the utility of this role and helpful strategies will be added soon!
+
+
+Different strategies for managing users in teams
+================================================
+
+When a user leaves a team
+-------------------------
+
+In eLabFTW, there are currently several options for handling the data of users who are about to leave a team. Here are four exit strategies to consider:
+
+ 1. Archiving the user and their entries
+If a person is only a member of one team, they can be archived. In this process, it's possible to choose whether their associated entries should also be locked and archived. This method ensures a clean separation, but it is only suitable if the person belongs to a single team. If the person is active in multiple teams, archiving them would also archive them in the other teams, which is usually not desired.
+ 2. Adjusting visibility and write permissions
+Another exit strategy involves explicitly setting the visibility and write permissions of the entries for the team the person is leaving. To ensure that the entries remain visible to the team after the user’s departure, the corresponding permissions for all entries need to be updated. This can be done by a team admin as a bulk action through the admin control panel. This way, the team retains access to experiments and entries without the person remaining part of the team.
+ 3. Transferring ownership or duplicating entries
+Another option is to transfer ownership of the entries to another team member. Alternatively, relevant entries can be duplicated before the person is removed from the team. Once a person is removed from the team, their entries are no longer visible to the team, which also means that the original ownership becomes unclear. To avoid this, the name of the original creator can be added to the entry title or stored as a tag to make the data origin more transparent.
+ 4. Restricting the visibility of entries
+Instead of removing the person from the team, they can remain a member while limiting the visibility of their entries. Access rights can be managed so that only the original owner and admins have access to certain entries. This ensures that the person leaving the team cannot access information irrelevant to them, while still technically remaining in the team.

doc/generalities.rst

@@ -14,6 +14,8 @@ Let's define a few terms first:
 * **Admin**: a user with Admin rights for a given team has access to the Admin Panel and can manage settings related to their Team. A given user can be Admin in Team A and User in Team B
 * **User**: a user with an account on the Instance, belonging to at least one Team
 
+We could also mention the role of **Instance Coordinator**, someone identified by the Users as the person to go to for all things eLab in the institution. It might be Research Data Managers, or a designated Researcher or Engineer that is very familiar with eLabFTW. This person could have access to managing the relationship between users and teams. They could animate the internal chat room related to eLabFTW usage.
+
 General principles
 ==================
 

doc/import-export.rst

@@ -152,6 +152,21 @@ Now you need to have a column named **title**. This is the column that will be p
 
 If you wish to include tags during the import, specify a column "tags" that will contain the tags separated by a "|" character. You can also have a "metadata" column containing JSON. The same logic applies to "metadata" column which can contain JSON that will be included in the metadata of the created entry.
 
+How columns are processed
+"""""""""""""""""""""""""
+
+* ``title`` becomes ``title``
+* ``body`` becomes the main text (HTML). If you wish to import markdown, have a column ``content_type`` with value `2` (`1` being for HTML content)
+* ``date`` becomes the user defined date. Prefer YYYY-MM-DD format
+  ``category_title`` and ``status_title`` will become the category or status (a new category/status will be created if necessary)
+  ``metadata`` will be processed as eLabFTW metadata (in JSON)
+  ``tags`` will get added as tags, they must be separated by ``|`` character
+  ``canread``, ``canwrite`` and ``canbook`` are the JSON permissions suitable for eLabFTW
+  ``rating``, if present, must be a value between 0 and 5 (stars rating)
+
+The rest of the columns will get added as Text Extra field.
+
+
 Once you are satisfied with the file, export it as a **.csv** (in File > Save as...). Make a copy of only the first 3 rows and export that too as csv, this will be our test file.
 
 2. Importing the file

doc/index.rst

@@ -66,6 +66,7 @@ Join the `chat room <https://gitter.im/elabftw/elabftw>`_ if you want to ask a q
     user-guide
     admin-guide
     sysadmin-guide
+    coordinator-guide
     import-export
     inventory
     metadata

doc/install.rst

@@ -53,7 +53,7 @@ The following MySQL modes are known to work fine with eLabFTW codebase:
 Strongly recommended dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * `curl <https://curl.haxx.se/>`_, to get files from command line (very likely already installed)
-* `docker compose plugin <https://docs.docker.com/compose/install/>`_, the tool to orchestrate containers, required by `elabctl`. It can be installed with the `docker-compose-plugin` package.
+* `docker compose plugin <https://docs.docker.com/compose/install/>`_, the tool to orchestrate containers, required by `elabctl`. It can be installed with the `docker-compose-plugin` package. You might need to enable Docker repositories to get this plugin. Make sure to **NOT** use the old `docker-compose` package/tool but to use the actual `compose plugin` of Docker, which might or might not come with Docker depending on your distribution/method of installation.
 * `dialog <https://en.wikipedia.org/wiki/Dialog_(software)>`_, required by `elabctl install`
 * `borgbackup <https://borgbackup.readthedocs.io/en/stable/>`_, a backup tool required by `elabctl backup`. Not required during installation.
 
@@ -144,6 +144,8 @@ Start eLabFTW
 
     elabctl start
 
+Then go to section :ref:`Initialize your database <db-init>`.
+
 
 Without elabctl (advanced users)
 --------------------------------
@@ -159,6 +161,8 @@ Edit this file and ``docker compose up -d`` to launch the containers.
 Initialize your database
 ========================
 
+.. _db-init:
+
 * Import the database structure with:
 
 .. code-block:: bash

doc/sysadmin-guide.rst

@@ -73,13 +73,40 @@ Configure authentication :sup:`(optional)`
 
 eLabFTW currently supports four authentication mechanisms:
 
-* Local authentication: email + password stored locally, this is the default
+* Local authentication: email + password stored locally (in the eLabFTW database), this is the default
 * SAML authentication: use one or several Identity Provider (IDP) to authenticate users. See dedicated :ref:`SAML documentation page <saml>`.
 * LDAP authentication: verify the login with an LDAP service. See dedicated :ref:`LDAP documentation page <ldap>`.
-* External authentication: use request headers added by your own middleware to authenticate the user (e.g. Apache's auth_mellon)
+* External authentication: use request headers added by your own middleware to authenticate the user (_e.g._ Apache's auth_mellon)
 
 It is possible to have several mechanisms at the same time but recommended to only leave one visible to users. So if you configure LDAP or SAML, disable the Local login so Users are not confused.
 
+Example configuration 1: only Admins can create accounts
+--------------------------------------------------------
+
+If you want to prevent users from registering accounts from the Register page but still want to allow Admins to create local user accounts in their team, use these settings:
+
+- enable "Admins can create local accounts" from the Server tab of Sysconfig panel (it is enabled by default)
+- in the Local Auth tab, disable "Enable local account creation"
+
+Example configuration 2: accounts can only be created from SAML
+---------------------------------------------------------------
+
+If you want user accounts to only exist through a valid SAML response, use these settings:
+
+- disable "Admins can create local accounts" from the Server tab of Sysconfig panel (it is enabled by default)
+- in the Local Auth tab, disable "Enable local account creation" and "Show local login form"
+- in the SAML tab, set "If the user doesn't exist yet, what to do?" to "Create the user on the fly"
+
+Example configuration 3: use LDAP mainly, but allow Admins to create local user accounts for external collaborators
+-------------------------------------------------------------------------------------------------------------------
+
+Configure the LDAP settings from the LDAP tab. Then you have a choice: you can either mask local login form with "Show local login form" disabled from the Local Auth tab, or keep it enabled and users can select "Local" or "LDAP" from the login page (LDAP will be selected by default), which might be confusing to some users (as they don't know what Local or LDAP corresponds to). It's up to you. If you mask local login, external collaborators will need to append "?letmein" to the login page URL so they can select Local login.
+
+Make sure that "Admins can create local accounts" from first tab is enabled, and that if you have a filter on email domains, the external collaborators emails can fit.
+
+Help, I'm locked out!
+---------------------
+
 If you disabled Local authentication and cannot login back because your other method fails, you'll want to run this SQL query (`elabctl mysql` will give you a MySQL prompt if you're using Dockerized MySQL service):
 
 .. code-block:: mysql
@@ -334,3 +361,14 @@ In some contexts, it might be advantageous to use S3 backed storage for uploaded
 3. In the Sysconfig panel, configure your bucket from the "UPLOADS" tab, test by uploading a file in an experiment
 4. Once S3 is correctly configured, run ``bin/console uploads:migrate``. This will copy all your locally stored files into the S3 bucket
 5. The final step is to remove the bind mounted ``/elabftw/uploads/`` folder from the container runtime configuration
+
+Command line tools
+==================
+
+The container comes with two CLI tools: ``bin/console`` and ``bin/init``. They provide utilities for Sysadmins such as team export as .eln.
+
+You can list available commands with ``bin/console list`` or ``bin/init list``.
+
+Example: ``docker exec -it elabftw bin/console list``.
+
+Check a command manual with ``-h`` flag. For example: ``bin/console prune:experiments -h``.

doc/user-guide.rst

@@ -239,6 +239,49 @@ This timestamp archive is immutable and cannot be modified or deleted.
 
    The archived zip
 
+Verifying the timestamp
+"""""""""""""""""""""""
+
+To verify locally the validity of the timestamp, you can use ``openssl`` with a command similar to:
+
+.. code:: bash
+
+   openssl ts -verify -CAfile /etc/ssl/cert.pem -data /path/to/X-timestamped.json -in /path/to/X-timestamped.asn1 -text
+
+If it was signed with a certificate trusted on your system, it should output "Verification: OK". You can also check the token content directly with:
+
+.. code:: bash
+
+    openssl ts -reply -in /path/to/X-timestamped.asn1 -text
+
+The output should look like:
+
+.. code-block:: console
+
+    Using configuration from /etc/ssl/openssl.cnf
+    Status info:
+    Status: Granted.
+    Status description: Operation Okay
+    Failure info: unspecified
+
+    TST info:
+    Version: 1
+    Policy OID: 1.3.6.1.4.1.22177.300.22.1
+    Hash Algorithm: sha256
+    Message data:
+        0000 - 5a 58 7b 86 c3 a6 79 27-35 b8 4d 57 bc 5a 7e 80   ZX{...y'5.MW.Z~.
+        0010 - 52 89 92 60 0b 8d 03 d4-f2 9e 4a 4c 6d ec 91 a4   R..`......JLm...
+    Serial number: 0xCDAB07382DF7B1BBE0CC970E93A7625B63F4DB7A
+    Time stamp: Jul 16 23:07:34 2025 GMT
+    Accuracy: unspecified
+    Ordering: no
+    Nonce: unspecified
+    TSA: unspecified
+    Extensions:
+
+The "Time stamp" line gives you the timestamp time. The "Hash Algorithm" and "Message data" should correspond to the digest of the data file (the .json). Compare it with: ``openssl dgst -sha256 /path/to/X-timestamped.json``
+
+
 
 6. Blockchain timestamp
 ^^^^^^^^^^^^^^^^^^^^^^^