├── .circleci └── config.yml ├── .github ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md ├── PULL_REQUEST_TEMPLATE.md └── workflows │ ├── codespell.yml │ └── trigger.yml ├── .gitignore ├── FUNDING.yml ├── LICENSE ├── README.md ├── SECURITY.md ├── config_examples ├── README.md ├── apache │ ├── README.md │ └── mod_security.md ├── haproxy │ ├── README.md │ ├── acl-evil.lst │ └── haproxy.cfg ├── nginx │ └── README.md ├── quadlet │ ├── elabftw.container │ ├── elabftw.network │ └── haproxy.container └── traefik │ └── README.md ├── doc ├── 404.rst ├── Makefile ├── _templates │ └── footer.html ├── addons.rst ├── admin-guide.rst ├── api.rst ├── backup.rst ├── changelog.rst ├── conf.py ├── contributing.rst ├── debug.rst ├── docker-doc.rst ├── faq.rst ├── features.rst ├── generalities.rst ├── how-to-update.rst ├── img │ ├── 1.2.1.png │ ├── admin-panel-itemstypes.png │ ├── admin-validate-user.png │ ├── api-keygen.png │ ├── apple.png │ ├── auth.png │ ├── book-edit-modal.png │ ├── book-item-button.png │ ├── by-sa.png │ ├── can-book-setting.png │ ├── compounds-db.png │ ├── compounds-edit.png │ ├── compounds-editor-help.png │ ├── compounds-editor.png │ ├── compounds-import-pubchem-modal.png │ ├── compounds-safety.png │ ├── container-app.png │ ├── contributing.png │ ├── didyoubackup.jpg │ ├── digitalocean.png │ ├── disable-2fa.png │ ├── doc-info.png │ ├── docker-select.gif │ ├── docker.png │ ├── elabftw-logo.png │ ├── export-options.png │ ├── extra-field-builder.png │ ├── extra-fields-dropdown.png │ ├── extra-fields-number-view.png │ ├── extra-fields-number.png │ ├── extra-fields-view.png │ ├── extra-fields.png │ ├── favtags.gif │ ├── favtags.mkv │ ├── favtags.png │ ├── freebsd.png │ ├── gnulinux.png │ ├── i18n.png │ ├── json-editor-mode.png │ ├── macwin.jpg │ ├── markdown-editor.gif │ ├── markdown-editor.png │ ├── metadata-example.png │ ├── modify-booking-menu.png │ ├── modify-booking-modal.png │ ├── nas-1.png │ ├── nas-2.png │ ├── observatory.png │ ├── opencloning.png │ ├── qnap.png │ ├── qnap │ │ ├── elabftw-1.png │ │ ├── elabftw-env.png │ │ ├── elabftw-link.png │ │ ├── elabftw-ports.png │ │ ├── elabftw-volumes.png │ │ ├── mysql-1.png │ │ ├── mysql-env.png │ │ └── mysql-volumes.png │ ├── qualys-ssl-report.png │ ├── quick_create.gif │ ├── quick_tags.gif │ ├── quick_upload.png │ ├── restore-entry.png │ ├── securityheaders.io.png │ ├── server-client.gif │ ├── settings.png │ ├── show-archived-uploads.png │ ├── smtp2go.jpg │ ├── sort-table.gif │ ├── sortable-table-icon.png │ ├── sysadmin-manage-teams.png │ ├── sysconfig-anonymous.png │ ├── sysconfig-email-warning.png │ ├── sysconfig-email-warning.webp │ ├── sysconfig-teams.png │ ├── tags-view.png │ ├── template-menu-click.png │ ├── template-toggle-pin.png │ ├── templates-menu.png │ ├── timestamp-archive.png │ ├── tinymce-editor-paragraph.png │ ├── tinymce-editor.png │ ├── user-alt-layout.png │ ├── user-anonymous-link.png │ ├── user-experiments-menu.png │ ├── user-file-uploader.png │ ├── user-guide-toolbar-edit.png │ ├── user-linked-entries-tools.png │ ├── user-scope-button.png │ ├── user-show-mode.png │ ├── user-switch-layout.png │ ├── user-toggle-pin-templates.gif │ ├── user-toggle-pin-templates.png │ ├── user-view-toolbar.png │ ├── view-mode-export-dropdown.png │ ├── view-mode-numbered.png │ └── windows.png ├── import-export.rst ├── index.rst ├── install-cloud.rst ├── install-nas.rst ├── install-nolinux.rst ├── install.rst ├── ldap.rst ├── metadata.rst ├── saml.rst ├── sysadmin-guide.rst ├── thanks.rst ├── upgrade-to-docker.rst └── user-guide.rst └── requirements.txt /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2.1 2 | orbs: 3 | # See the orb documentation here: https://circleci.com/developer/orbs/orb/circleci/python 4 | python: circleci/python@1.5.0 5 | 6 | # See: https://circleci.com/docs/2.0/configuration-reference/#jobs 7 | jobs: 8 | build: 9 | docker: 10 | - image: cimg/python:3.10.2 11 | steps: 12 | - checkout 13 | - python/install-packages: 14 | pkg-manager: pip 15 | - run: 16 | name: Install texlive and rsvgconverter 17 | command: 'sudo apt update && sudo apt install -y texlive texlive-xetex texlive-fonts-extra texlive-latex-extra xindy latexmk' 18 | - run: 19 | name: Build html 20 | command: cd doc && make html 21 | - store_artifacts: 22 | path: doc/_build/html 23 | destination: html 24 | - run: 25 | name: Build pdf 26 | command: cd doc && make latexpdf -e LATEXOPTS="-interaction=nonstopmode" 27 | - store_artifacts: 28 | path: doc/_build/latex/elabftw.pdf 29 | destination: pdf 30 | workflows: 31 | mkdoc: 32 | jobs: 33 | - build 34 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | 31 | **Smartphone (please complete the following information):** 32 | - Device: [e.g. iPhone6] 33 | - OS: [e.g. iOS8.1] 34 | - Browser [e.g. stock browser, safari] 35 | - Version [e.g. 22] 36 | 37 | **Additional context** 38 | Add any other context about the problem here. 39 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | Please base your PR on the `next` branch. 2 | -------------------------------------------------------------------------------- /.github/workflows/codespell.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: Codespell 3 | 4 | on: 5 | push: 6 | branches: [master,next] 7 | pull_request: 8 | branches: [master,next] 9 | 10 | jobs: 11 | codespell: 12 | name: Check for typos 13 | runs-on: ubuntu-latest 14 | 15 | steps: 16 | - name: Checkout 17 | uses: actions/checkout@v4 18 | 19 | - name: Run codespell 20 | uses: codespell-project/actions-codespell@v2 21 | with: 22 | # this file contains typos by design 23 | skip: acl-evil.lst 24 | -------------------------------------------------------------------------------- /.github/workflows/trigger.yml: -------------------------------------------------------------------------------- 1 | name: Trigger doc rebuild 2 | 3 | on: 4 | push: 5 | 6 | jobs: 7 | buildandpush: 8 | runs-on: ubuntu-latest 9 | steps: 10 | - name: Send request to webhook to trigger update of doc 11 | run: | 12 | curl -v -H 'X-Hook-Secret: ${{ secrets.HOOK_SECRET }}' ${{ secrets.HOOK_URL }} 13 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/* 2 | doc/_build 3 | build/ 4 | venv/ 5 | -------------------------------------------------------------------------------- /FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | liberapay: NicolasCARPi 3 | github: NicolasCARPi 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution-ShareAlike 4.0 International Public License 2 | 3 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 4 | 5 | Section 1 – Definitions. 6 | 7 | Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 8 | Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 9 | BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License. 10 | Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 11 | Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 12 | Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 13 | License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. 14 | Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 15 | Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 16 | Licensor means the individual(s) or entity(ies) granting rights under this Public License. 17 | Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 18 | Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 19 | You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 20 | 21 | Section 2 – Scope. 22 | 23 | License grant. 24 | Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 25 | reproduce and Share the Licensed Material, in whole or in part; and 26 | produce, reproduce, and Share Adapted Material. 27 | Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 28 | Term. The term of this Public License is specified in Section 6(a). 29 | Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 30 | Downstream recipients. 31 | Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 32 | Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. 33 | No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 34 | No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 35 | 36 | Other rights. 37 | Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 38 | Patent and trademark rights are not licensed under this Public License. 39 | To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 40 | 41 | Section 3 – License Conditions. 42 | 43 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 44 | 45 | Attribution. 46 | 47 | If You Share the Licensed Material (including in modified form), You must: 48 | retain the following if it is supplied by the Licensor with the Licensed Material: 49 | identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 50 | a copyright notice; 51 | a notice that refers to this Public License; 52 | a notice that refers to the disclaimer of warranties; 53 | a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 54 | indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 55 | indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 56 | You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 57 | If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 58 | ShareAlike. 59 | 60 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. 61 | The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. 62 | You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. 63 | You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. 64 | 65 | Section 4 – Sui Generis Database Rights. 66 | 67 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 68 | 69 | for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 70 | if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and 71 | You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 72 | 73 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 74 | 75 | Section 5 – Disclaimer of Warranties and Limitation of Liability. 76 | 77 | Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. 78 | To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. 79 | 80 | The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 81 | 82 | Section 6 – Term and Termination. 83 | 84 | This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 85 | 86 | Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 87 | automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 88 | upon express reinstatement by the Licensor. 89 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 90 | For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 91 | Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 92 | 93 | Section 7 – Other Terms and Conditions. 94 | 95 | The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 96 | Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. 97 | 98 | Section 8 – Interpretation. 99 | 100 | For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 101 | To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 102 | No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 103 | Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 104 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # elabdoc 2 | 3 | ## Description 4 | 5 | Source files for the [elabftw documentation](https://doc.elabftw.net). 6 | 7 | Main project repository: [elabftw/elabftw](https://github.com/elabftw/elabftw). 8 | 9 | ## Installation 10 | 11 | ~~~bash 12 | git clone https://github.com/elabftw/elabdoc 13 | cd elabdoc 14 | python -m venv venv 15 | source venv/bin/activate 16 | pip install -r requirements.txt 17 | ~~~ 18 | 19 | ## Config examples 20 | 21 | You might want to look into the [config_examples](./config_examples) folder for Apache, HAProxy, Nginx or Traefik configuration as reverse proxy. 22 | 23 | ## Usage 24 | 25 | To generate the HTML documentation: 26 | 27 | ~~~bash 28 | cd doc 29 | make html 30 | ~~~ 31 | 32 | Then point your browser to the `_build/html/index.html` file inside the `doc/` folder. 33 | 34 | ## CI 35 | 36 | The generated documentation can also be accessed in the Artifacts section of the [CircleCI builds](https://app.circleci.com/pipelines/github/elabftw/elabdoc). 37 | 38 | Click on "pdf" to get the doc as a pdf. 39 | 40 | ## Headings used 41 | 42 | ~~~rst 43 | *********** 44 | MAIN HEADER 45 | *********** 46 | 47 | TITLE 48 | ===== 49 | 50 | SUBTITLE 51 | -------- 52 | 53 | SUBSUBTITLE 54 | ^^^^^^^^^^^ 55 | 56 | SUBSUBSUBTITLE 57 | """""""""""""" 58 | ~~~ 59 | 60 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | See [our policy](https://www.deltablot.com/security/). 4 | -------------------------------------------------------------------------------- /config_examples/README.md: -------------------------------------------------------------------------------- 1 | # Configuration example files for eLabFTW 2 | 3 | This folder holds example configuration files for popular web servers, when used as a reverse proxy in front of the eLabFTW container. 4 | 5 | ## Apache 6 | 7 | The [Apache folder](./apache) contains documentation for running Apache as a reverse proxy for eLabFTW. 8 | 9 | ## Nginx 10 | 11 | The [Nginx folder](./nginx) contains documentation for running Nginx as a reverse proxy for eLabFTW. 12 | 13 | ## HAProxy 14 | 15 | The [HAProxy folder](./haproxy) contains configuration for running HAProxy in front of one (or several) elabimg containers in http mode. 16 | 17 | ## Traefik 18 | 19 | The [Traefik folder](./traefik) contains documentation related to traefik. 20 | -------------------------------------------------------------------------------- /config_examples/apache/README.md: -------------------------------------------------------------------------------- 1 | # Apache 2 | 3 | If you already have an Apache webserver running, you can use it to forward requests to the Docker container (this is called a reverse proxy). 4 | 5 | For that you will need to install/enable the `mod_proxy` Apache module, along with `mod_headers`: 6 | 7 | ~~~bash 8 | sudo a2enmod proxy 9 | sudo a2enmod headers 10 | ~~~ 11 | 12 | We recommend that you run the Docker container in HTTP mode and let Apache handle 13 | TLS termination. However, letting the Docker container deal with TLS is also an option. Both configurations are presented below. 14 | 15 | ## Prerequisite: running the container on a custom port 16 | 17 | Because our Apache server is already running on port 443, we will want the Docker container to run on another port. 18 | 19 | In the `ports` section of this configuration file, expose the container on port 3148 as follows: 20 | 21 | ~~~yaml 22 | ports: 23 | - '127.0.0.1:3148:443' 24 | ~~~ 25 | 26 | **Note**: We're using the 127.0.0.1 localhost ip to prevent Docker from exposing the port by bypassing the firewall configuration (see [this issue](https://github.com/moby/moby/issues/22054)). 27 | 28 | ## Reverse proxy for a container in http mode (recommended) 29 | 30 | ### Running the container in HTTP mode 31 | 32 | By default, the eLabFTW (elabftw/elabimg) container runs in HTTPS mode, so you'll need to edit your `elabftw.yml` file (or `docker-compose.yml`) and add: 33 | 34 | ~~~yaml 35 | DISABLE_HTTPS=true 36 | ~~~ 37 | 38 | ### Configuring the reverse proxy 39 | 40 | In your VirtualHost configuration block for eLabFTW, add the following lines: 41 | 42 | ~~~apacheconf 43 | RequestHeader set X-Forwarded-Proto "https" 44 | ProxyPreserveHost On 45 | ProxyPass "/" "http://localhost:3148/" 46 | ProxyPassReverse "/" "http://localhost:3148/" 47 | ~~~ 48 | 49 | ## Reverse proxy for a container in https mode 50 | 51 | You will need to make sure `mod_ssl` is activated. 52 | 53 | Add these lines to your Apache configuration file (probably in `/etc/apache2/apache.conf` or in your VirtualHosts files). 54 | 55 | ~~~apacheconf 56 | SSLEngine on 57 | SSLProxyEngine on 58 | ProxyPreserveHost On 59 | ProxyPass "/" "https://localhost:3148/" 60 | ProxyPassReverse "/" "https://localhost:3148/" 61 | ~~~ 62 | -------------------------------------------------------------------------------- /config_examples/apache/mod_security.md: -------------------------------------------------------------------------------- 1 | # Apache mod_security for eLabFTW 2 | 3 | If you use [mod_security](https://github.com/SpiderLabs/ModSecurity) with your Apache server. It is necessary to have this configuration: 4 | 5 | ~~~apacheconf 6 | 7 |         ServerName 8 | 9 |         10 | 11 | # Disable outbound anomaly score 12 |         SecRuleRemoveById 959100 13 | 14 |         # Special config for /api endpoint 15 |         16 |                 SecRequestBodyAccess Off 17 |                 SecRuleRemoveById 949110 18 |         19 | 20 | ~~~ 21 | 22 | List of rules is available here: https://www.netnea.com/cms/core-rule-set-inventory/ 23 | 24 | Please note that this is not a full-fledged configuration but rather a tweak that allows eLabFTW to work. 25 | -------------------------------------------------------------------------------- /config_examples/haproxy/README.md: -------------------------------------------------------------------------------- 1 | # HAProxy configuration for eLabFTW 2 | 3 | This is an example config for a case in which HAProxy is in front of one or several eLabFTW containers (image: elabftw/elabimg). 4 | 5 | ## Example docker-compose config 6 | 7 | Use the official HAProxy image with a bind mount on the config folder: 8 | 9 | ~~~yaml 10 | services: 11 | haproxy: 12 | image: haproxy:2.2-alpine 13 | container_name: haproxy 14 | restart: always 15 | read_only: true 16 | depends_on: 17 | - elabftw 18 | ports: 19 | - '80:80' 20 | - '443:443' 21 | volumes: 22 | - /path/to/haproxy:/usr/local/etc/haproxy:ro 23 | ~~~ 24 | -------------------------------------------------------------------------------- /config_examples/haproxy/acl-evil.lst: -------------------------------------------------------------------------------- 1 | /02.php 2 | /099.php 3 | /1111.php 4 | /11a.php 5 | /1213.php 6 | /123131/index.php 7 | /12345.php 8 | /1234.php 9 | /123.php 10 | /12.php 11 | /1556189185.php 12 | /15.php 13 | /1hou.php 14 | /1/index.php 15 | /1ndex.php 16 | /1.php 17 | /1q.php 18 | /1x.php 19 | /2015/wp-includes/wlwmanifest.xml 20 | /2016/wp-includes/wlwmanifest.xml 21 | /2017/wp-includes/wlwmanifest.xml 22 | /2018/wp-includes/wlwmanifest.xml 23 | /2.php 24 | /321/index.php 25 | /3.php 26 | /_404.php 27 | /404.php 28 | /411.php 29 | /415.php 30 | /421.php 31 | /444.php 32 | /4.php 33 | /51314.php 34 | /51.php 35 | /5201314.php 36 | /520.php 37 | /5678.php 38 | /56.php 39 | /605.php 40 | /666666.php 41 | /666.php 42 | /6.php 43 | /%73%65%61%72%63%68%2e%70%68%70 44 | /%73%65%65%79%6F%6E/%68%74%6D%6C%6F%66%66%69%63%65%73%65%72%76%6C%65%74 45 | /%75%73%65%72%2e%70%68%70 46 | /%75%73%65%72/%72%65%67%69%73%74%65%72 47 | /777.php 48 | /789056.php 49 | /7o.php 50 | /7.php 51 | /887.php 52 | /888.php 53 | /92.php 54 | /9510.php 55 | /9678.php 56 | /981.php 57 | /987.php 58 | /98k.php 59 | /999.php 60 | /99.php 61 | /9.php 62 | /a2billing/customer/templates/default/footer.tpl 63 | /a411.php 64 | /aaa9 65 | /aaaaaa1.php 66 | /aaaa.php 67 | /aaa.php 68 | /aab9 69 | /aa.php 70 | /aap.php 71 | /abc776.php 72 | /abc.php 73 | /about.php 74 | /ack.php 75 | /actualites.feed 76 | /actuator 77 | /admin1.php 78 | /admin/config.php 79 | /admin-console 80 | /admin/index.php 81 | /Administrator.php 82 | /administrator/webconfig.txt.php 83 | /admin/mysql2/index.php 84 | /admin/mysql/index.php 85 | /admin/phpmyadmin2/index.php 86 | /admin/phpmyadmin/index.php 87 | /admin/phpMyAdmin/index.php 88 | /admin/pma/index.php 89 | /admin/PMA/index.php 90 | /admn.php 91 | /ads.txt 92 | /afafaf.php 93 | /?a=fetch 94 | /ak47.php 95 | /ak48.php 96 | /ak.php 97 | /Alarg53.php 98 | /alipay.php 99 | /angge.php 100 | /anyi.php 101 | /aojiao.php 102 | /aotian.php 103 | /aotu7.php 104 | /aotu.php 105 | /a.php 106 | /api/jsonws 107 | /api.php 108 | /App74d8459f.php 109 | /Appdbd9459f.php 110 | /app.php 111 | /App.php 112 | /appserv.php 113 | /[asDomaincom]_backup.sql 114 | /[asDomaincom]_dump.sql 115 | /[asDomaincom].sql 116 | /asen.php 117 | /Autodiscover 118 | /autoloader.php 119 | /avast.php 120 | /aw.php 121 | /awstats/awstatstotals.php 122 | /awstats/index.php 123 | /awstatstotals/awstatstotals.php 124 | /awstatstotals/index.php 125 | /babel-plugin-dotenv 126 | /backend 127 | /back.php 128 | /backup 129 | /backup.sql 130 | /bag2 131 | /baidoubi.php 132 | /bak.php 133 | /base.dump.sql 134 | /base.sql 135 | /bb.php 136 | /bbq.php 137 | /bbqq.php 138 | /bbr.php 139 | /bbv.php 140 | /beimeng.php 141 | /bf.php 142 | /bitcoin 143 | /blog/wp-includes/wlwmanifest.xml 144 | /blog/wp-login.php 145 | /blog/xmlrpc.php 146 | /bn.php 147 | /boaform 148 | /bois-energie 149 | /boots.php 150 | /boxes 151 | /b.php 152 | /buluya.php 153 | /bx.php 154 | /cacti/plugins/weathermap/editor.php 155 | /cadre.php 156 | /cainiao.php 157 | /can.php 158 | /caonma.php 159 | /CCCC.PHP 160 | /CCC.PHP 161 | /cc.php 162 | /CC.php 163 | /ce.PHP 164 | /cere.php 165 | /cer.php 166 | /ceshi.php 167 | /cgi-bin 168 | /cgi-bin/login.html 169 | /cgi-bin/nobody/Machine.cgi 170 | /cgi-bin/user/Config.cgi 171 | /chaoda.php 172 | /ci.php 173 | /ckeditor 174 | /ckfinder 175 | /claroline/phpMyAdmin/index.php 176 | /class1.php 177 | /cmdd.php 178 | /cmd.php 179 | /cms/wp-includes/wlwmanifest.xml 180 | /cmv.php 181 | /cnm.php 182 | /cn.php 183 | /code.php 184 | /common.js 185 | /composer.php 186 | /composers.php 187 | /conf1g.php 188 | /confg.php 189 | /confie.php 190 | /.config.php 191 | /config.php 192 | /Config_Shell.php 193 | /conflg.php 194 | /conf.php 195 | /console 196 | /coonig.php 197 | /coon.php 198 | /copy.sql 199 | /core.php 200 | /c.php 201 | /cron.php 202 | /cs.php 203 | /current_config/passwd 204 | /currentsetting.htm 205 | /cxfm666.php 206 | /d7.php 207 | /dashu.php 208 | /data/admin/help.php 209 | /data.php 210 | /datas.php 211 | /dbadmin/index.php 212 | /db_cts.php 213 | /db_dataml.php 214 | /db_desql.php 215 | /db/index.php 216 | /db.init.php 217 | /db__.init.php 218 | /db.php 219 | /db_pma.php 220 | /db_session.init.php 221 | /ddd.php 222 | /default.php 223 | /defect.php 224 | /desktop.ini.php 225 | /device_description.xml 226 | /dexgp.php 227 | /dialog 228 | /diy.php 229 | /DJ.php 230 | /dns.php 231 | /dns-query 232 | /docs.css 233 | /dong.php 234 | /doudou.php 235 | /download/index.php 236 | /d.php 237 | /Drupal.php 238 | /duke.php 239 | /dump.sql 240 | /ecmsmod.php 241 | /editor 242 | /Editor.js 243 | /elrekt.php 244 | /.env 245 | /erba.php 246 | /error_page.htm 247 | /error.php 248 | /errors.php 249 | /errors/processor.php 250 | /erwa.php 251 | /evox 252 | /fack.php 253 | /fantao.php 254 | /fb.php 255 | /FCK 256 | /fckeditor 257 | /fdgq.php 258 | /fdsrwe 259 | /feixiang.php 260 | /ffr.php 261 | /floaw.php 262 | /ftmabc.php 263 | /fuck.php 264 | /function.inc.php 265 | /fusheng.php 266 | /fx.php 267 | /ganshiqiang.php 268 | /ganzhuolang.php 269 | /general.php 270 | /gg.php 271 | /.git 272 | /.git.php 273 | /godkey.php 274 | /g.php 275 | /GponForm 276 | /gsy.php 277 | /guai.php 278 | /guipu.php 279 | /h156.php 280 | /h1.php 281 | /hack.php 282 | /hacly.php 283 | /hannan.php 284 | /hd.php 285 | /hello.php 286 | /hell.php 287 | /help-e.php 288 | /help.php 289 | /hgx.php 290 | /hhhhhh.php 291 | /hhh.php 292 | /hh.php 293 | /hl.php 294 | /hm.php 295 | /HNAP1 296 | /HNAP1/ 297 | /home.php 298 | /htdocs.php 299 | /htfr.php 300 | /html/public/index.php 301 | /hudson 302 | /hue2.php 303 | /huoshan.php 304 | /HX.php 305 | /Hzllaga.php 306 | /_ignition 307 | /igo.php 308 | /iis.php 309 | /images/1ndex.php 310 | /images/1.php 311 | /images/asp.php 312 | /images/attari.php 313 | /images/defau1t.php 314 | /images/entyy.php 315 | /images/jsspwneed.php 316 | /images/logo.gif 317 | /images/!.php 318 | /images/stories/cmd.php 319 | /images/stories/filemga.php 320 | /images/swfupload/tags.php 321 | /images/up.php 322 | /images/vuln.php 323 | /include/data/tags.php 324 | /include/tags.php 325 | /inc.php 326 | /inc/rsd.php 327 | /indea.php 328 | /inde.php 329 | /index1.php 330 | /indexa.php 331 | /indexbak.php 332 | /index.php?s=/Index 333 | /info1.php 334 | /info8.php 335 | /infoo.php 336 | /info.php 337 | /infos.php 338 | /install/includes 339 | /ioi.php 340 | /ip.php 341 | /issmall 342 | /izom.php 343 | /java.php 344 | /jbb.php 345 | /jb.php 346 | /jenkins 347 | /jiaochi.php 348 | /jing.php 349 | /ji.php 350 | /jj1.php 351 | /jjj.php 352 | /jkl.php 353 | /j.php 354 | /jsc.php 355 | /jsc.php.php 356 | /juji.php 357 | /jy.php 358 | /jyyy.php 359 | /key.php 360 | /kkl.php 361 | /kk.php 362 | /knal.php 363 | /kpl.php 364 | /ks1.php 365 | /kvast.php 366 | /l6.php 367 | /l7.php 368 | /l8.php 369 | /lala-dpr.php 370 | /lala.php 371 | /lang.php 372 | /lanke.php 373 | /lanyecn.php 374 | /laobiao.php 375 | /lapan.php 376 | /laravel.php 377 | /ldw.php 378 | /lequ.php 379 | /liangchen.php 380 | /license.php 381 | /lindex.php 382 | /link.php 383 | /linkr.php 384 | /linkx.php 385 | /linux1.php 386 | /linux.php 387 | /linuxse.php 388 | /ljb.php 389 | /llld.php 390 | /lmn.php 391 | /lm.php 392 | /log1.php 393 | /login.htm 394 | /login/login.html 395 | /logon.php 396 | /log.php 397 | /lol.php 398 | /lost.php 399 | /lr.php 400 | /lucky.php 401 | /luoke.php 402 | /luoran6.php 403 | /luoran.php 404 | /luso.php 405 | /lx.php 406 | /lz.php 407 | /manager 408 | /manager/html 409 | /manager/text/list 410 | /mazi.php 411 | /MCLi.php 412 | /media 413 | /media/wp-includes/wlwmanifest.xml 414 | /meijianxue 415 | /meijianxue.php 416 | /meng.php 417 | /miao.php 418 | /mifs 419 | /min.php 420 | /mjx.php 421 | /ml.php 422 | /mm.php 423 | /mobai.PHP 424 | /mo.php 425 | /Moxin.PHP 426 | /m.php 427 | /muhstik2.php 428 | /muhstik-dpr.php 429 | /muhstik.php 430 | /muhstiks.php 431 | /muieblackcat 432 | /mutuba.php 433 | /mx.php 434 | /myadmin 435 | /MyAdmin 436 | /myadmin2/index.php 437 | /myadmin/index.php 438 | /MyAdmin/index.php 439 | /myadmin/scripts/db___.init.php 440 | /MyAdmin/scripts/db___.init.php 441 | //myadmin/scripts/setup.php 442 | /myadmin/scripts/setup.php 443 | //MyAdmin/scripts/setup.php 444 | /MyAdmin/scripts/setup.php 445 | /mybestloves.php 446 | /my.php 447 | /mysql-admin/index.php 448 | /mysql/admin/index.php 449 | /mysql_admin/index.php 450 | /mysqladmin/index.php 451 | /mysql/dbadmin/index.php 452 | /mysql/index.php 453 | /mysql/mysqlmanager/index.php 454 | /mysql.php 455 | /mysql/sqlmanager/index.php 456 | /mz.php 457 | /n23.php 458 | /n24.php 459 | /nb.php 460 | /neko.php 461 | /new_license.php 462 | /news/wp-includes/wlwmanifest.xml 463 | /nice%20ports 464 | /nidage.php 465 | /nmaplowercheck 466 | /nnn.php 467 | /no1.php 468 | /no.php 469 | /nuoxi.php 470 | /okokok.php 471 | /ok.php 472 | /ooi.php 473 | /ooo23.php 474 | /ooo.php 475 | /orange.php 476 | /ou2.php 477 | /oumi.php 478 | /owa 479 | /p34ky1337.php 480 | /Panel/ 481 | /payload.php 482 | /paylog.php 483 | /pe.php 484 | /.php 485 | /php2MyAdmin/index.php 486 | /phpadmin/index.php 487 | /phpAdmin/index.php 488 | /phpdm.php 489 | /phpiMyAdmin/index.php 490 | /phpinf0.php 491 | /phpinfi.php 492 | /phpini.php 493 | /phpmadmin/index.php 494 | /phpma/index.php 495 | /phpMyAbmin/index.php 496 | /phpmyadm1n/index.php 497 | /phpMyAdm1n/index.php 498 | /phpMyadmi/index.php 499 | /phpmyadmin 500 | /phpmyadmin0/index.php 501 | /phpMyAdmin_111/index.php 502 | /phpMyAdmin123/index.php 503 | /phpmyadmin1/index.php 504 | /phpMyAdmin1/index.php 505 | /phpmyadmin2222/index.php 506 | /phpmyadmin2/index.php 507 | /phpMyAdmin._2/index.php 508 | /phpmyadmin3333/index.php 509 | /phpMyAdmin-4.4.0/index.php 510 | /phpMyAdmina/index.php 511 | /phpMyadmin_bak/index.php 512 | /phpMyAdminhf/index.php 513 | /phpmyadmin/index.php 514 | /phpMyAdmin+++---/index.php 515 | /phpMyAdmin._/index.php 516 | /phpMyAdmin/index.php 517 | /phpMyAdmin__/index.php 518 | /phpMyAdminn/index.php 519 | /phpmyadmin-old/index.php 520 | /phpMyAdmin.old/index.php 521 | /phpMyAdminold/index.php 522 | /phpmyadmin/phpmyadmin/index.php 523 | /phpMyAdmin/phpMyAdmin/index.php 524 | /phpmyadmin/scripts/db___.init.php 525 | /phpMyAdmin/scripts/db___.init.php 526 | //phpmyadmin/scripts/setup.php 527 | /phpmyadmin/scripts/setup.php 528 | //phpMyAdmin/scripts/setup.php 529 | /phpMyAdmin/scripts/setup.php 530 | /phpMyAdmins/index.php 531 | /phpMyAdmion/index.php 532 | /phpMyAdmln/index.php 533 | /phpMydmin/index.php 534 | /phpmy/index.php 535 | /phpmy/scripts/setup.php 536 | /phpNyAdmin/index.php 537 | /php.php 538 | /phppma/index.php 539 | /phpstudy.php 540 | /phpStudy.php 541 | /Pings.php 542 | /pk1914.php 543 | /plugins/weathermap/editor.php 544 | /plus/90sec.php 545 | /plus/bakup.php 546 | /plus/canshi.php 547 | /plus/dajihi.php 548 | /plus/e7xue.php 549 | /plus/gu.php 550 | /plus/huai.php 551 | /plus/laobiaoaien.php 552 | /plus/laobiao.php 553 | /plus/lucas.php 554 | /plus/ma.php 555 | /plus/moon.php 556 | /plus/mybak.php 557 | /plus/mytag.php 558 | /plus/qiang.php 559 | /plus/read.php 560 | /plus/result.php 561 | /plus/service.php 562 | /plus/shaoyong.php 563 | /plus/tou.php 564 | /plus/xsvip.php 565 | /plus/yunjitan.php 566 | /PMA2/index.php 567 | /pma/index.php 568 | /PMA/index.php 569 | /pmamy2/index.php 570 | /pmamy/index.php 571 | /pma-old/index.php 572 | /pma.php 573 | /pma/scripts 574 | /pma/scripts/db___.init.php 575 | /PMA/scripts/db___.init.php 576 | //pma/scripts/setup.php 577 | /pma/scripts/setup.php 578 | /PMA/scripts/setup.php 579 | /pmd/index.php 580 | /pmd_online.php 581 | /pop.php 582 | /portal 583 | /post.php 584 | /p.php 585 | /ppl.php 586 | /pp.php 587 | /ppp.php 588 | /ppx.php 589 | /program/index.php 590 | /proxyjudge.php 591 | /public/index.php 592 | /pwd/index.php 593 | /python.php 594 | /qa.php 595 | /qaq.php 596 | /qaz.php 597 | /qiangkezhi.php 598 | /qiqi11.php 599 | /qiqi1.php 600 | /qiqi.php 601 | /?q=login.destroy.session 602 | /q.php 603 | /qq5262.php 604 | /qq.php 605 | /qqq.php 606 | /que.php 607 | /queqiao.php 608 | /_query.php 609 | /qunhuang.php 610 | /qwe.php 611 | /qw.php 612 | /qwq.php 613 | /qwqw.php 614 | /remote 615 | /repeat.php 616 | /robots.txt 617 | /root11.php 618 | /root.php 619 | /rrr.php 620 | /ruii.php 621 | /ruyi.php 622 | /rxr.php 623 | /s1.php 624 | /sample.php 625 | /sanan.php 626 | /sane.php 627 | /sbb/index.php 628 | /sbkcb.php 629 | /sbkc.php 630 | /scripts/db___.init.php 631 | /scripts/setup.php 632 | /sdk 633 | /sean.php 634 | /servlet 635 | /setup.cgi 636 | /shaAdmin/index.php 637 | /shanzhi.php 638 | /sha.php 639 | /sheep.php 640 | /shell 641 | /shell.php 642 | /she.php 643 | /shh.php 644 | /shi.php 645 | /shipu.php 646 | /shopdb/index.php 647 | /shop/wp-includes/wlwmanifest.xml 648 | /s/index.php 649 | /sitemap.xml 650 | /site/wp-includes/wlwmanifest.xml 651 | /site/wp-login.php 652 | /sito/wp-includes/wlwmanifest.xml 653 | /Skri.php 654 | /slider.php 655 | /sllolx.php 656 | /smb_scheduler/ 657 | /solr 658 | /s.php 659 | /spider.php 660 | /sqlk.php 661 | /ssaa.php 662 | /ss.php 663 | /Ss.php 664 | /sss.php 665 | /stats/index.php 666 | /super.php 667 | /system.php 668 | /sz.php 669 | /t6nv.php 670 | /taisui.php 671 | /taocishun.php 672 | /temp.php 673 | /temtel.php 674 | /test123.php 675 | /test_404_page 676 | /test404.php 677 | /test_for_404 678 | /test.php 679 | /tests.php 680 | /test/wp-includes/wlwmanifest.xml 681 | /text.php 682 | /think.php 683 | /thinkphp/html/public/index.php 684 | /tiandi.php 685 | /tianqi.php 686 | /tomcat.php 687 | /tools.cgi 688 | /tools/phpMyAdmin/index.php 689 | /toor.php 690 | /TP 691 | /TP/html/public/index.php 692 | /TP/index.php 693 | /TP/public/index.php 694 | /tt.php 695 | /ttt.php 696 | /tty.php 697 | /typo3/phpmyadmin/index.php 698 | /tyrant.php 699 | /undx.php 700 | /Updata.php 701 | /u.php 702 | /uploader.php 703 | /UploadFile 704 | /up.php 705 | /UserFiles 706 | /user.php 707 | /userr.php 708 | /usshiuig 709 | /uu.php 710 | /uuu.php 711 | /v5she 712 | /vedioes.php 713 | /vendor/php-unit 714 | /vendor/phpunit 715 | /vendor/phpunit/phpunit/src/Util/PHP/eval-stdin.php 716 | /ver.php 717 | /vf.php 718 | /v/index.php 719 | /v.php 720 | /vtigercrm/vtigerservice.php 721 | /vuln1.php 722 | /vuln.php 723 | /vulnspy.php 724 | /vvv.php 725 | /w00tw00t 726 | /w00tw00t.at.blackhats.romanian.anti-sec:) 727 | /waf.php 728 | /wanan.php 729 | /wanmei.php 730 | /wan.php 731 | /wb.php 732 | /wc.php 733 | /wcp.php 734 | /weathermap/editor.php 735 | /webconfig.php 736 | /webconfig.txt.php 737 | /web-console 738 | /webdav/ 739 | /web/phpMyAdmin/index.php 740 | /website/wp-includes/wlwmanifest.xml 741 | /webslee.php 742 | /web/wp-includes/wlwmanifest.xml 743 | /weixiao.php 744 | /.well-known/security.txt 745 | /whoami.php 746 | /whoami.php.php 747 | /win1.php 748 | /winbox.png 749 | /win.php 750 | /wordpress/wp-includes/wlwmanifest.xml 751 | /wordpress/wp-login.php 752 | /woshimengmei.php 753 | /wp1/wp-includes/wlwmanifest.xml 754 | /wp1/wp-login.php 755 | /wp2/wp-includes/wlwmanifest.xml 756 | /wp2/wp-login.php 757 | /wp3/wp-login.php 758 | /wp4/wp-login.php 759 | /wp5/wp-login.php 760 | /wp-admins.php 761 | /wp-config.php 762 | /wp-content 763 | /wp-content/plugins/ad-inserter/readme.txt 764 | /wp-content/plugins/portable-phpmyadmin/wp-pma-mod/index.php 765 | /wp-content/themes/AdvanceImage5/header.php 766 | /wp-content/themes/bl.php 767 | /wpc.php 768 | /w.php 769 | /wp-includes/css/modules.php 770 | /wp-includes/css/wp-config.php 771 | /wp-includes/css/wp-login.php 772 | /wp-includes/fonts/modules.php 773 | /wp-includes/fonts/wp-config.php 774 | /wp-includes/fonts/wp-login.php 775 | /wp-includes/modules/modules.php 776 | /wp-includes/modules/wp-config.php 777 | /wp-includes/modules/wp-login.php 778 | /wp-includes/wlwmanifest.xml 779 | /wp-login 780 | /wp-login.php 781 | /wpo.php 782 | /wp/wp-includes/wlwmanifest.xml 783 | /wp/wp-login.php 784 | /wshell.php 785 | /wsx.php 786 | /wuwu11.php 787 | /wuwu.php 788 | /ww.php 789 | /www.php 790 | /www/phpMyAdmin/index.php 791 | /WWW/phpMyAdmin/index.php 792 | /xampp/phpmyadmin/index.php 793 | /xh.php 794 | /xiaobin.php 795 | /xiaodai.php 796 | /xiaohei.php 797 | /xiaomae.php 798 | /xiaoma.php 799 | /xiaomar.php 800 | /xiaomo.php 801 | /xiao.php 802 | /xiaoxia.php 803 | /xiaoxi.php 804 | /xiaoyu.php 805 | /xiaxia.php 806 | /xing.php 807 | /xiong.php 808 | /xi.php 809 | /xiu.php 810 | /xixi.php 811 | //xmlrpc.php 812 | /xmlrpc.php 813 | /x.php 814 | /xp.php 815 | /xshell.php 816 | /xsser.php 817 | /xun.php 818 | /xw1.php 819 | /xw.php 820 | /xx33.php 821 | /xx.php 822 | /xxx.php 823 | /xxxx.php 824 | /xz.php 825 | /yao.php 826 | /yccc.php 827 | /ycc.php 828 | /yc.php 829 | /yj.php 830 | /ysy.php 831 | /yumo.php 832 | /yu.php 833 | /yuyang.php 834 | /yyx.php 835 | /yyy.php 836 | /zhk.php 837 | /zhui.php 838 | /zmp.php 839 | /z.php 840 | /zshmindex.php 841 | /zuoindex.php 842 | /zuo.php 843 | /zuoshou.php 844 | /zuoshss.php 845 | /zuos.php 846 | /zuoss.php 847 | /zxc0.php 848 | /zxc1.php 849 | /zxc2.php 850 | /zxc.php 851 | /zxy.php 852 | /zyc.php 853 | /zzk.php 854 | /zz.php 855 | /zzz.php 856 | -------------------------------------------------------------------------------- /config_examples/haproxy/haproxy.cfg: -------------------------------------------------------------------------------- 1 | # HAProxy config example for eLabFTW (https://www.elabftw.net) 2 | 3 | # GLOBAL CONFIG 4 | global 5 | # max number of sessions (default 2000) 6 | maxconn 5000 7 | 8 | # Default SSL material locations 9 | ca-base /etc/ssl/certs 10 | crt-base /etc/ssl/private 11 | tune.ssl.default-dh-param 2048 12 | 13 | # log to stdout 14 | log stdout format raw local0 info 15 | 16 | # Default ciphers to use on SSL-enabled listening sockets 17 | # from https://mozilla.github.io/server-side-tls/ssl-config-generator/ 18 | ssl-default-bind-ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256 19 | ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets 20 | ssl-default-server-ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256 21 | ssl-default-server-options no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets 22 | 23 | # DEFAULTS 24 | defaults 25 | mode http 26 | 27 | timeout connect 5000 28 | timeout client 50000 29 | timeout server 50000 30 | 31 | # logs 32 | log global 33 | option httplog 34 | option dontlognull 35 | 36 | option forwardfor 37 | option http-server-close 38 | 39 | # use gzip compression 40 | compression algo gzip 41 | 42 | # HTTP FRONTEND 43 | frontend http-in 44 | bind :::80 v4v6 45 | 46 | acl missing_cl hdr_cnt(Content-length) eq 0 47 | http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl 48 | http-request deny if METH_GET HTTP_CONTENT 49 | http-request deny unless METH_GET or METH_POST or METH_OPTIONS 50 | # httpoxy.org 51 | http-request del-header Proxy 52 | 53 | # don't log HEAD requests from uptimerobot 54 | http-request set-log-level silent if METH_HEAD 55 | 56 | # evil acl 57 | acl evil path_beg -f /usr/local/etc/haproxy/acl-evil.lst 58 | # don't log the denied stuff 59 | http-request set-log-level silent if evil 60 | http-request silent-drop if evil 61 | 62 | # letsencrypt 63 | acl letsencrypt-acl path_beg /.well-known/acme-challenge/ 64 | 65 | # add header to say we're coming from http 66 | http-request add-header X-Forwarded-Proto http 67 | 68 | redirect prefix https://elabftw.example.org code 301 if { hdr(host) -i elabftw.example.org } !letsencrypt-acl 69 | 70 | use_backend letsencrypt-backend if letsencrypt-acl 71 | default_backend defaultback 72 | 73 | # HTTPS FRONTEND 74 | frontend https-in 75 | # use a script to concatenate the let's encrypt files into one file so haproxy can read it 76 | # example script: 77 | # 78 | # #!/usr/bin/env bash 79 | # set -eu 80 | # DOMAIN=elabftw.example.org 81 | # certbot renew --http-01-port=8989 82 | # cat "/etc/letsencrypt/live/elabftw.example.org/fullchain.pem" "/etc/letsencrypt/live/elabftw.example.org/privkey.pem" > "/path/to/haproxy/certs/elabftw.example.org-haproxy.pem" 83 | # /usr/bin/docker compose -f /path/to/docker-compose.yml restart haproxy 84 | # 85 | bind :::443 v4v6 ssl crt /usr/local/etc/haproxy/certs/elabftw.example.org-haproxy.pem alpn h2,http/1.1 86 | 87 | # stats 88 | stats enable 89 | stats uri /stats 90 | # CHANGE THIS 91 | stats auth your_user:your_password_hash 92 | stats refresh 10s 93 | 94 | # httpoxy.org 95 | http-request del-header Proxy 96 | 97 | # letsencrypt 98 | acl letsencrypt-acl path_beg /.well-known/acme-challenge/ 99 | 100 | # don't log HEAD requests from uptimerobot 101 | http-request set-log-level silent if METH_HEAD 102 | 103 | # evil acl 104 | acl evil path_beg -f /usr/local/etc/haproxy/acl-evil.lst 105 | # don't log the denied stuff 106 | http-request set-log-level silent if evil 107 | http-request silent-drop if evil 108 | 109 | # add header to say we're coming from https 110 | http-request add-header X-Forwarded-Proto https 111 | 112 | use_backend letsencrypt-backend if letsencrypt-acl 113 | use_backend netdata if netdata-acl 114 | 115 | default_backend defaultback 116 | 117 | # BACKENDS 118 | backend defaultback 119 | description eLabFTW 120 | server elabftw-1 elabftw:443 check port 443 121 | # you can have several elabftw containers if you use redis for php sessions 122 | #server elabftw-2 elabftw:443 check port 443 123 | -------------------------------------------------------------------------------- /config_examples/nginx/README.md: -------------------------------------------------------------------------------- 1 | # Nginx 2 | 3 | If you already have an Nginx webserver running, you can use it to forward requests to the Docker container (this is called a reverse proxy). 4 | 5 | ## Prerequisite: running the container on a custom port 6 | 7 | Because our Nginx server is already running on port 443, we will want the Docker container to run on another port. 8 | 9 | In the `ports` section of this configuration file, expose the container on port 3148 as follows: 10 | 11 | ~~~yaml 12 | ports: 13 | - '127.0.0.1:3148:443' 14 | ~~~ 15 | 16 | **Note**: We're using the 127.0.0.1 localhost ip to prevent Docker from exposing the port by bypassing the firewall configuration (see [this issue](https://github.com/moby/moby/issues/22054)). 17 | 18 | ## Nginx configuration 19 | 20 | In the following example, the URL https://elab.example.org is forwarded to local port 3148, where the Docker container is listening. In this example, Nginx is listening to port 8888, and HAProxy is handling TLS termination. Adapt this example to your needs. If HAProxy is not handling TLS termination in your case, use https in the proxy_pass instruction and make sure DISABLE_HTTPS is false in the elabftw.yml config. 21 | 22 | ~~~nginxconf 23 | server { 24 | server_name elab.example.org; 25 | 26 | listen 8888; 27 | listen [::]:8888; 28 | 29 | access_log /var/log/nginx/elab.example.org.log proxy; 30 | 31 | location / { 32 | proxy_pass http://localhost:3148; # use httpS here if needed 33 | proxy_set_header Host $host; 34 | proxy_set_header X-Real-IP $remote_addr; 35 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 36 | # add this if nginx is terminating TLS 37 | proxy_set_header X-Forwarded-Proto $scheme; 38 | } 39 | } 40 | ~~~ 41 | 42 | Add this to /etc/nginx/nginx.conf to get the real IP address in the logs: 43 | 44 | ~~~nginxconf 45 | log_format proxy '$proxy_add_x_forwarded_for - $remote_user [$time_local] ' 46 | '"$request" $status $body_bytes_sent ' 47 | '"$http_referer" "$http_user_agent" "$gzip_ratio"'; 48 | ~~~ 49 | -------------------------------------------------------------------------------- /config_examples/quadlet/elabftw.container: -------------------------------------------------------------------------------- 1 | # This file is an example .container file for eLabFTW service. Also place the .network file and possible configure HAProxy accordingly. 2 | # Place it in /etc/containers/systemd so a quadlet is generated and the service can be managed by systemd. 3 | # Documentation: https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html 4 | 5 | [Unit] 6 | Description=elabftw container service 7 | After=network.target 8 | 9 | [Container] 10 | # Note: it is recommended to pin to a specific version instead of using the "stable" tag. 11 | Image=docker.io/elabftw/elabimg:stable 12 | ContainerName=elabftw 13 | 14 | # CAPABILITIES 15 | DropCapability=ALL 16 | AddCapability=CHOWN 17 | AddCapability=SETGID 18 | AddCapability=SETUID 19 | AddCapability=FOWNER 20 | AddCapability=DAC_OVERRIDE 21 | AddCapability=NET_BIND_SERVICE 22 | 23 | NoNewPrivileges=true 24 | 25 | # HEALTHCHECK 26 | HealthCmd=curl http://localhost:443/healthcheck 27 | HealthInterval=5s 28 | HealthTimeout=5s 29 | HealthRetries=20 30 | 31 | # ENVIRONMENT VARIABLES 32 | Environment=DB_HOST=10.X.Y.Z 33 | Environment=DB_NAME=elabftw 34 | Environment=DB_USER=elabftw 35 | Environment=DB_PORT=3306 36 | Secret=elabftw-db-password,type=env,target=DB_PASSWORD 37 | Environment=DB_CERT_PATH=/mysql-cert/mysql.pem 38 | Secret=elabftw-secret-key,type=env,target=SECRET_KEY 39 | Environment=SERVER_NAME=eln.example.org 40 | # in this example we run http server behind TLS terminating proxy 41 | Environment=DISABLE_HTTPS=true 42 | Environment=MAX_PHP_MEMORY=512M 43 | Environment=MAX_UPLOAD_SIZE=1G 44 | Environment=PHP_TIMEZONE=Europe/Paris 45 | Environment=TZ=Europe/Paris 46 | Environment=SET_REAL_IP=true 47 | Environment=SET_REAL_IP_FROM=10.X.Y.Z 48 | Environment=PHP_MAX_CHILDREN=50 49 | Environment=PHP_MAX_EXECUTION_TIME=90 50 | Environment=USE_REDIS=true 51 | Environment=REDIS_HOST=10.X.Y.Z 52 | Environment=REDIS_PORT=6379 53 | Environment=REDIS_USERNAME=elabftw_php_sessions 54 | Secret=redis-password,type=env,target=REDIS_PASSWORD 55 | Environment=ENABLE_IPV6=false 56 | Environment=SITE_URL=https://eln.example.org 57 | Environment=ELABFTW_USER=nobody 58 | Environment=ELABFTW_GROUP=nobody 59 | Environment=ELABFTW_USERID=65534 60 | Environment=ELABFTW_GROUPID=65534 61 | Environment=STATUS_PASSWORD=secr3t 62 | # if using S3 storage 63 | Secret=elabftw-s3-ak,type=env,target=ELAB_AWS_ACCESS_KEY 64 | Secret=elabftw-s3-sk,type=env,target=ELAB_AWS_SECRET_KEY 65 | 66 | # VOLUMES 67 | # if not using s3, bind mount the uploads folder in the host 68 | # do NOT add :z here because NFS cause an issue # 69 | # host:container 70 | Volume=/mnt/data/elabftw_uploads:/elabftw/uploads 71 | # this is necessary if you encrypt mysql connection and thus want the container to have access to the mysql cert 72 | Volume=/deltablot/mysql:/mysql-cert:z 73 | 74 | # NETWORKS 75 | Network=elabftw.network 76 | 77 | [Service] 78 | # see: https://gist.github.com/ageis/f5595e59b1cddb1513d1b425a323db04 79 | LockPersonality=yes 80 | PrivateTmp=yes 81 | ProtectHome=yes 82 | ProtectKernelModules=yes 83 | Restart=unless-stopped 84 | RestrictAddressFamilies=AF_UNIX AF_INET AF_NETLINK 85 | RestrictRealtime=yes 86 | 87 | # these ones break container execution 88 | #NoNewPrivileges=yes 89 | #PrivateDevices=yes 90 | #DevicePolicy=closed 91 | #ProtectSystem=strict 92 | #ProtectControlGroups=yes 93 | #ProtectKernelTunables=yes 94 | #RestrictNamespaces=yes 95 | #RestrictSUIDSGID=yes 96 | #MemoryDenyWriteExecute=yes 97 | 98 | [Install] 99 | WantedBy=multi-user.target 100 | -------------------------------------------------------------------------------- /config_examples/quadlet/elabftw.network: -------------------------------------------------------------------------------- 1 | [Unit] 2 | Description=network for elabftw 3 | 4 | [Network] 5 | -------------------------------------------------------------------------------- /config_examples/quadlet/haproxy.container: -------------------------------------------------------------------------------- 1 | [Unit] 2 | Description=HAProxy Service 3 | Wants=network.target 4 | After=network.target 5 | 6 | [Container] 7 | Image=docker.io/haproxy:3.0 8 | ContainerName=haproxy 9 | ReadOnly=true 10 | NoNewPrivileges=true 11 | PidsLimit=12 12 | 13 | # Port mapping 14 | PublishPort=80:8080 15 | ExposeHostPort=80 16 | PublishPort=443:4443 17 | ExposeHostPort=443 18 | 19 | # Volume mounts 20 | Volume=/usr/local/etc/haproxy:/usr/local/etc/haproxy:ro,z 21 | 22 | Network=elabftw.network 23 | 24 | [Service] 25 | Restart=always 26 | 27 | [Install] 28 | WantedBy=multi-user.target 29 | -------------------------------------------------------------------------------- /config_examples/traefik/README.md: -------------------------------------------------------------------------------- 1 | # traefik 2 | 3 | If you are already using [traefik](https://traefik.io/traefik/) to manage your containers, here is how to run eLabFTW: 4 | 5 | * Get a docker-compose configuration file: 6 | 7 | ~~~bash 8 | curl -sL -o docker-compose.yml "https://get.elabftw.net/?config" 9 | ~~~ 10 | 11 | Edit this file with your favorite editor and: 12 | 13 | For the `web` service: 14 | 15 | * Remove the `container_name` 16 | * Set `DISABLE_HTTPS=true` 17 | * Set `ENABLE_LETSENCRYPT=false` 18 | * Remove the `ports` section 19 | * Remove the `networks` section (or adapt it to your network) 20 | 21 | For the `mysql` service: 22 | 23 | * Remove everything if you already have a MySQL service running 24 | * Remove the `container_name` 25 | * Remove the `ports` section 26 | * Remove the `networks` section (or adapt it to your network) 27 | 28 | And remove the final `networks` section. 29 | 30 | Add a label to the `web` service so traffic is routed to it. See traefik documentation. 31 | 32 | Configure TLS accordingly. See traefik documentation. 33 | 34 | Use docker-compose to bring the containers up and traefik should detect it and route requests accordingly. 35 | -------------------------------------------------------------------------------- /doc/404.rst: -------------------------------------------------------------------------------- 1 | :orphan: 2 | 3 | *************** 4 | Page not found! 5 | *************** 6 | 7 | Oops! 8 | ===== 9 | 10 | No page with that name could be found. Maybe you clicked on an old link? 11 | 12 | Look at the menu on the left to find what you are looking for! 13 | 14 | 15 | -------------------------------------------------------------------------------- /doc/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 36 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 38 | @echo " text to make text files" 39 | @echo " man to make manual pages" 40 | @echo " texinfo to make Texinfo files" 41 | @echo " info to make Texinfo files and run them through makeinfo" 42 | @echo " gettext to make PO message catalogs" 43 | @echo " changes to make an overview of all changed/added/deprecated items" 44 | @echo " xml to make Docutils-native XML files" 45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 46 | @echo " linkcheck to check all external links for integrity" 47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 48 | 49 | clean: 50 | rm -rf $(BUILDDIR)/* 51 | 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | dirhtml: 58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 61 | 62 | singlehtml: 63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 64 | @echo 65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 66 | 67 | pickle: 68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 69 | @echo 70 | @echo "Build finished; now you can process the pickle files." 71 | 72 | json: 73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 74 | @echo 75 | @echo "Build finished; now you can process the JSON files." 76 | 77 | htmlhelp: 78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 79 | @echo 80 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 81 | ".hhp project file in $(BUILDDIR)/htmlhelp." 82 | 83 | qthelp: 84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 85 | @echo 86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/elabftw.qhcp" 89 | @echo "To view the help file:" 90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/elabftw.qhc" 91 | 92 | devhelp: 93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 94 | @echo 95 | @echo "Build finished." 96 | @echo "To view the help file:" 97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/elabftw" 98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/elabftw" 99 | @echo "# devhelp" 100 | 101 | epub: 102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 103 | @echo 104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 105 | 106 | latex: 107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 108 | @echo 109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 111 | "(use \`make latexpdf' here to do that automatically)." 112 | 113 | latexpdf: 114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 115 | @echo "Running LaTeX files through pdflatex..." 116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 118 | 119 | latexpdfja: 120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 121 | @echo "Running LaTeX files through platex and dvipdfmx..." 122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 124 | 125 | text: 126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 127 | @echo 128 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 129 | 130 | man: 131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 132 | @echo 133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 134 | 135 | texinfo: 136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 137 | @echo 138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 139 | @echo "Run \`make' in that directory to run these through makeinfo" \ 140 | "(use \`make info' here to do that automatically)." 141 | 142 | info: 143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 144 | @echo "Running Texinfo files through makeinfo..." 145 | make -C $(BUILDDIR)/texinfo info 146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 147 | 148 | gettext: 149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 150 | @echo 151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 152 | 153 | changes: 154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 155 | @echo 156 | @echo "The overview file is in $(BUILDDIR)/changes." 157 | 158 | linkcheck: 159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 160 | @echo 161 | @echo "Link check complete; look for any errors in the above output " \ 162 | "or in $(BUILDDIR)/linkcheck/output.txt." 163 | 164 | doctest: 165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 166 | @echo "Testing of doctests in the sources finished, look at the " \ 167 | "results in $(BUILDDIR)/doctest/output.txt." 168 | 169 | xml: 170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 171 | @echo 172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 173 | 174 | pseudoxml: 175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 176 | @echo 177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 178 | -------------------------------------------------------------------------------- /doc/_templates/footer.html: -------------------------------------------------------------------------------- 1 | {% extends '!footer.html' %} 2 | {% block extrafooter %} 3 | cc-by-sa 4 | {% endblock %} 5 | -------------------------------------------------------------------------------- /doc/addons.rst: -------------------------------------------------------------------------------- 1 | .. _addons: 2 | 3 | ****** 4 | Addons 5 | ****** 6 | 7 | What are addons? 8 | ================= 9 | 10 | Addons are services that can be deployed to provide extended functionality for eLabFTW. They are not a requirement but are definitely recommended. 11 | 12 | Chem Plugin 13 | =========== 14 | 15 | Description 16 | ----------- 17 | 18 | The ``chem-plugin`` addon is necessary for two things: 19 | 20 | - calculating fingerprint of chemical compounds (which subsequently allows for substructure search) 21 | - enabling all features of the chemical editor 22 | 23 | How to install 24 | -------------- 25 | 26 | Deploy a ``chem-plugin`` container somewhere. It can be on the same server than eLabFTW or some other place. Adding a service to your ``docker-compose.yml`` file is the easiest. See the `example docker-compose.yml file `_. 27 | 28 | The deployment is really straightforward, as there is nothing to configure. You just start the container and that's it. 29 | 30 | .. code:: yaml 31 | 32 | chem-plugin: 33 | image: elabftw/chem-plugin:latest 34 | container_name: chem-plugin 35 | restart: always 36 | networks: 37 | - elabftw-net 38 | 39 | Next, configure eLabFTW to use that service by adding two environment variables: 40 | 41 | .. code:: yaml 42 | 43 | # This service is necessary for the Chemical structure editor (Ketcher) 44 | - USE_INDIGO=true 45 | - INDIGO_URL=http://chem-plugin/ 46 | # The fingerprinter is necessary to create a fingerprint of chemical compounds so we can do sub-structure search 47 | - USE_FINGERPRINTER=true 48 | - FINGERPRINTER_URL=http://chem-plugin:8000/ 49 | 50 | In the example above, the container is on the same network as ``elabftw`` container, so we use its name as hostname. 51 | 52 | Restart the ``elabftw`` container to take these changes into account. 53 | 54 | OpenCloning addon 55 | ================= 56 | 57 | Description 58 | ----------- 59 | 60 | OpenCloning is an application useful to plan and document cloning. It allows loading DNA data from various sources and is tightly integrated with eLabFTW. This means that you can easily use your Resources in eLabFTW and their attached files to perform cloning operations. 61 | 62 | How to install 63 | -------------- 64 | 65 | To enable OpenCloning in eLabFTW, deploy a container like shown in the `example docker-compose.yml `_. 66 | 67 | Then enable it in ``elabftw`` container configuration: 68 | 69 | .. code:: yaml 70 | 71 | # This is for the integration of the DNA Cloning tool 72 | - USE_OPENCLONING=true 73 | - OPENCLONING_URL=http://opencloning-plugin:8000/ 74 | 75 | Restart the ``elabftw`` container to take these changes into account. 76 | -------------------------------------------------------------------------------- /doc/admin-guide.rst: -------------------------------------------------------------------------------- 1 | .. _admin-guide: 2 | 3 | *********** 4 | Admin guide 5 | *********** 6 | This guide is intended for Admins of Teams. An Admin is a User in a Team with Admin rights, and access to the Admin Panel (accessed via the top right menu or the bottom left link). A Team can have several Admins and must have at least one. 7 | 8 | How to become an Admin? 9 | ======================= 10 | A User is automatically an Admin if they are the first User in a Team. An Admin can promote another User to the Admin level from the Admin Panel > Users tab. A Sysadmin can promote a User to the Admin level in the same way (from the Sysadmin Panel). 11 | 12 | General overview 13 | ================ 14 | An Admin: 15 | 16 | * Has access to the Admin Panel, where they can change the settings for their entire Team 17 | * Can validate/archive Users of their Team 18 | * Can edit available Categories and Status options for Experiments and Resources used by their Team 19 | * Can edit the default Experiment template 20 | * Can manage groups of Users within the Team (see below) 21 | * Can change the rightmost link in the main menu (default is Documentation) 22 | * Can archive a User, thus disabling login for that account, and locking all Experiments created by that account. 23 | 24 | Validating accounts 25 | =================== 26 | Unless this setting has been modified by the Sysadmin, or provisioning is done automatically, new accounts will need to be validated by a Team Admin before new Users can connect. The Admin is responsible for validating new User accounts. To validate new Users, head to the Admin panel where you will see a list of Users waiting for validation. 27 | 28 | .. image:: img/admin-validate-user.png 29 | :align: center 30 | :alt: Admin User validation 31 | 32 | If you do not wish to validate an account because that User does not belong to your Team, you can either ask the Sysadmin to change the Team associated with that account, or delete the account yourself. 33 | 34 | TEAM tab 35 | ======== 36 | The first tab in the Admin Panel contains various settings for the Team. This is where you can configure what Users can or cannot do in the Team, and define a default template for Experiments or change the last link in the main menu. 37 | 38 | GROUPS tab 39 | ========== 40 | The Admin can create User Groups from the Admin Panel. Once a User Group is created, the Admin can add Users to this Group by typing their names in the input field and selecting the suggested Users. Users in a Group can set the permissions of a Resource/Experiment for that Group such that only members of the Group can see/edit an entry. 41 | 42 | Note that it is possible to add Users from other Teams to a User Group. 43 | 44 | USERS tab 45 | ========= 46 | The Users tab allows you to modify User accounts in your Team. From this page, you can reset a password directly or "archive" a User. An "archived" User will no longer be able to login and all of their Experiments will be locked. If a User needs to leave one Team and join a different Team, that User should first be archived in the original Team. Then, a new account (same email) can be created for that User in the new Team. This way, the first Team keeps the data previously inputted by the User, and the User has a fresh account in the new Team using the same email address. 47 | 48 | You can also disable multifactor authentication for a particular User, if needed. 49 | 50 | From this page, you can also directly add a new User to your Team. The new User will need to activate the "Reset password" functionality to access their account. 51 | 52 | Reinitializing 2FA 53 | ------------------ 54 | 55 | In case a user lost their phone, they might need to re-initialize two factors authentication. This action can be done by an Admin or Sysadmin account. 56 | 57 | .. image:: img/disable-2fa.png 58 | :align: center 59 | :alt: Disable 2FA 60 | 61 | CATEGORIES tab 62 | ============== 63 | 64 | This menu allows you to define Categories for Experiments. Categories are very similar to status options: they have a name and a color. 65 | 66 | You can also define Categories for Resources. These are similar to Experiment templates because in addition to the name and color, you can define default text/Tags/links/fields. 67 | 68 | You can have as many as you want. For instance: 69 | 70 | * Antibody 71 | * Cell line 72 | * Microscope (you can make it bookable so it can be accessed in the Scheduler, found in the Team tab) 73 | * Protocol (or you could use a template for this) 74 | * Computer 75 | * Software 76 | * Project 77 | * Plasmid 78 | * ... 79 | 80 | Select a Category and click "Go" to load it, or click "Create" to add a new Category. 81 | 82 | .. image:: img/admin-panel-itemstypes.png 83 | :align: right 84 | :alt: resources categories tab 85 | 86 | 87 | When you create a new Category, use the default template of that type of item to add fields. For instance, for a Plasmid category you might want to have: 88 | 89 | **Concentration:** 90 | 91 | **Backbone:** 92 | 93 | **Resistance bacteria:** 94 | 95 | **Resistance mammalian:** 96 | 97 | You can also use :ref:`extra fields ` defined in the metadata json editor so that all items created in that Category will have these supplementary inputs. 98 | 99 | STATUS tab 100 | ========== 101 | The Status options are editable and customizable. There is one set of Status options for Experiments and another one for Resources. 102 | 103 | EXPORT tab 104 | ========== 105 | This tab allows you to export Experiments, items, or scheduled bookings in various formats. 106 | 107 | TAG MANAGER tab 108 | =============== 109 | This interface allows an Admin to edit existing Tags. For instance, if you have Tags called "RPE1" and "RPE-1" and you want all of the Tags to be in the form "RPE-1", find the "RPE1" Tag, click on it to edit it to "RPE-1", and click the Deduplicate button. 110 | -------------------------------------------------------------------------------- /doc/api.rst: -------------------------------------------------------------------------------- 1 | .. _api: 2 | 3 | *** 4 | API 5 | *** 6 | 7 | What's that? 8 | ============ 9 | 10 | It's a way to read or write data to eLabFTW from an external program (like a Python script). 11 | 12 | For instance, instead of using a web browser to access the web interface and create an experiment, 13 | you make a call to the API saying "hey, create an experiment for me", and the api will reply with the ID of the newly created experiment. 14 | 15 | It can be used to directly feed data to eLabFTW, coming from a piece of equipment for instance. 16 | 17 | Getting started 18 | =============== 19 | 20 | Generating a key 21 | ---------------- 22 | 23 | In order to use the API, you need to generate an API key. Head to the Settings page and create a new key by giving it a name and access level: 24 | 25 | .. image:: img/api-keygen.png 26 | :align: center 27 | :alt: api key generation 28 | 29 | Protect this key like you would do with a password, as it gives access to your account! 30 | 31 | Basic request 32 | ------------- 33 | 34 | The public API works with HTTP requests, so you are free to use any technology capable to make HTTP requests, which basically includes everything under the sun. 35 | 36 | A simple tool to get started is `curl` (most likely already available if using a GNU/Linux system). Here is how to fetch data of experiment with ID 42: 37 | 38 | .. code-block:: bash 39 | 40 | export KEY=3-cb2314b00d2845a... 41 | curl -H "Authorization: $KEY" https://eln.example.org/api/v2/experiments/42 42 | 43 | What we've done is use ``curl`` to make a ``GET`` request to eLabFTW api v2 endpoint. Sending the key in the ``Authorization`` header, and specifying that we want the experiment with id 42 in the URL. The response is a JSON object. 44 | 45 | Mainly, the API is using HTTP verbs for different actions. ``GET`` to read things (will not modify anything), ``POST`` to create things, ``PATCH`` to modify things, ``DELETE`` to, you guessed it, delete things. 46 | 47 | For instance, to create an experiment: 48 | 49 | .. code-block:: bash 50 | 51 | curl -I -H "Content-Type: application/json" -H "Authorization: $KEY" -X POST https://eln.example.org/api/v2/experiments 52 | 53 | The response headers contain the URL to the created resource in the ``location`` header: 54 | 55 | .. code-block:: text 56 | 57 | HTTP/2 201 58 | content-type: text/html; charset=UTF-8 59 | location: https://eln.example.org/api/v2/experiments/321 60 | ...other headers... 61 | 62 | You can then ``PATCH`` that newly created entry with whatever attributes you wish to change (title, date, main text, tags, etc...): 63 | 64 | .. code-block:: bash 65 | 66 | curl -H "Content-Type: application/json" -H "Authorization: $KEY" -X PATCH -d '{"title": "created from api", "date": "2024-02-15", "body": "main text content"}' https://eln.example.org/api/v2/experiments/321 67 | 68 | Everything is described in the `documentation `_ generated from the specification. 69 | 70 | You'll probably want to use python or a shell language to build a more meaningful script. Fortunately, a `python library `_ is available to make things easy for you (look at the `examples` folder!). 71 | 72 | Read the doc 73 | ============ 74 | 75 | The complete documentation of all endpoints with code examples is available here: `elabftw's API documentation `_. 76 | -------------------------------------------------------------------------------- /doc/backup.rst: -------------------------------------------------------------------------------- 1 | .. _backup: 2 | 3 | ************* 4 | How to backup 5 | ************* 6 | 7 | Introduction 8 | ============ 9 | 10 | This page documents how to backup an existing eLabFTW installation. It is important that you take the time to make sure that your backups are working properly. 11 | 12 | .. image:: img/didyoubackup.jpg 13 | 14 | There is basically three things to backup : 15 | 16 | * the MySQL database (by default in `/var/elabftw/mysql`) 17 | * the uploaded files (by default in `/var/elabftw/web`) 18 | * your configuration file (by default `/etc/elabftw.yml`): not really required if you use provisioning tools like Ansible and store your config/secrets somewhere else 19 | 20 | How to backup a Docker installation 21 | =================================== 22 | 23 | Important note 24 | -------------- 25 | 26 | The instructions below are merely a suggestion on how to proceed. If you are familiar with different tools or procedures to backup data, use them. At the end of the day, eLabFTW's data is a very classical MySQL database and even more classical files. The important points are: 27 | 28 | - test your backups 29 | - ensure if they fail you get a notification by email somehow 30 | - test your backups regularly 31 | - bonus: test your backups automatically 32 | 33 | Another point is: you **never** have too many backups. So use a full VM backup + mysqldump + copy files here and there + do a filesystem snapshot. Use all the tools at your disposal. Read this *postmortem* about a `Gitlab.com outage and how they discovered how broken their backup procedures were `_. 34 | 35 | With elabctl 36 | ------------ 37 | 38 | Using the backup function of `elabctl` is the recommended approach. The MySQL database will be dumped thanks to `mysqldump` present in the `mysql` container. The uploaded files will be copied with `borgbackup `_ and you need to install it first and then configure it. 39 | 40 | Configuration 41 | ^^^^^^^^^^^^^ 42 | 43 | Start by figuring out where you want the borg repository to live. It can be local or remote folder (remote is better but requires ssh correctly setup to access it). It can also be local but on a network-mounted path, which makes it remote. 44 | 45 | After installing borg, initialize a new repository with: 46 | 47 | .. code-block:: bash 48 | 49 | # for a local path 50 | borg init -e repokey-blake2 /path/to/elabftw-borg-repo 51 | # for a remote (ssh) path 52 | borg init -e repokey-blake2 someserver:/path/to/elabftw-borg-repo 53 | 54 | It is necessary to use the `elabctl.conf` configuration file (available `here `_). Place this file in `/root/.config/elabctl.conf` and make sure to specify the settings correctly. 55 | 56 | Test 57 | ^^^^ 58 | 59 | Try the backup with: 60 | 61 | .. code-block:: bash 62 | 63 | elabctl backup 64 | 65 | You can also use `mysql-backup` to only backup the MySQL database: 66 | 67 | .. code-block:: bash 68 | 69 | elabctl mysql-backup 70 | 71 | You can also use `borg-backup` to only backup the uploaded files: 72 | 73 | .. code-block:: bash 74 | 75 | elabctl borg-backup 76 | 77 | .. warning:: 78 | 79 | Important: verify that all the files are correctly created and that you will be able to restore from a backup! 80 | 81 | Without elabctl 82 | --------------- 83 | 84 | You're on your own. Use your favorite tools to backup the MySQL database and uploaded files. 85 | 86 | Making it automatic using cron 87 | ============================== 88 | 89 | A good backup is automatic. Use a cronjob or a systemd timer job to trigger the backup job regularly (ideally daily). 90 | 91 | With a cronjob 92 | -------------- 93 | 94 | If you have the traditional cron service running, try:: 95 | 96 | crontab -e 97 | 98 | This will open the cronjob file in edit mode. 99 | 100 | Add this line at the bottom:: 101 | 102 | 00 04 * * * /path/to/elabctl backup 103 | 104 | This will run the script everyday at 4am. Make sure to write the full path to `elabctl` as it might not be in the `$PATH` for cron. 105 | 106 | With a systemd timer 107 | -------------------- 108 | 109 | Some systems don't use the traditional cron service, so instead of installing it, you should use a systemd timer (provided systemd is your init system, which is quite likely). 110 | 111 | You will need to create two files, one `.service` and one `.timer`. 112 | 113 | Content of `/etc/systemd/system/elabftw-backup.service`:: 114 | 115 | [Unit] 116 | Description=Backup eLabFTW data 117 | Wants=elabftw-backup.timer 118 | 119 | [Service] 120 | Type=oneshot 121 | # make sure to edit the path below 122 | ExecStart=/path/to/elabctl backup 123 | # Make sure to use a user with enough rights 124 | User=root 125 | 126 | [Install] 127 | WantedBy=multi-user.target 128 | 129 | Content of `/etc/systemd/system/elabftw-backup.timer`:: 130 | 131 | [Unit] 132 | Description=Backup eLabFTW data 133 | 134 | [Timer] 135 | OnCalendar=*-*-* 4:00:00 136 | Persistent=true 137 | 138 | [Install] 139 | WantedBy=timers.target 140 | 141 | Now activate it:: 142 | 143 | systemctl enable elabftw-backup 144 | systemctl start elabftw-backup 145 | 146 | .. _restore-backup: 147 | 148 | How to restore a backup 149 | ======================= 150 | 151 | You should have three files/folders to start with: 152 | 153 | * A MySQL dump (file ending in .sql or .sql.gz) 154 | * Your uploaded files as a borg archive 155 | * Possibly your configuration file 156 | 157 | To extract your uploaded files from a borg backup: 158 | 159 | .. code-block:: bash 160 | 161 | export BORG_REPO=/path/to/borg/repo 162 | export BORG_PASSPHRASE="your passphrase" 163 | borg list 164 | borg extract "::example-2022-07-14_13-37" 165 | 166 | See documentation on how to manage your borg repository: `Borg extract documentation `_. 167 | 168 | Then we move the uploaded files and config file at the correct place (adjust the paths to your case): 169 | 170 | .. code-block:: bash 171 | 172 | mv /path/to/uploaded-files-backup/* /var/elabftw/web 173 | mv /path/to/configuration-backup-elabftw.yml /etc/elabftw.yml 174 | # now fix the permissions 175 | chown -R 101:101 /var/elabftw/web 176 | chmod 600 /etc/elabftw.yml 177 | 178 | Now we import the SQL database (the mysql container must be running): 179 | 180 | .. code-block:: bash 181 | 182 | gunzip mysql_dump-YYYY-MM-DD.sql.gz # uncompress the file 183 | docker cp mysql_dump-YYYY-MM-DD.sql mysql:/ # copy it inside the mysql container 184 | docker exec -it mysql bash # spawn a shell in the mysql container 185 | mysql -uroot -p$MYSQL_ROOT_PASSWORD # login to mysql prompt 186 | Mysql> drop database elabftw; # delete the brand new database 187 | Mysql> create database elabftw character set utf8mb4 collate utf8mb4_0900_ai_ci; # create a new one 188 | Mysql> use elabftw; # select it 189 | Mysql> set names utf8mb4; # make sure you import in utf8 (don't do this if you are in latin1) 190 | Mysql> source mysql_dump-YYYY-MM-DD.sql; # import the backup 191 | Mysql> exit; 192 | 193 | Now you should have your old install back :) 194 | -------------------------------------------------------------------------------- /doc/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # elabftw documentation build configuration file, created by 5 | # sphinx-quickstart on Fri Jul 24 17:28:23 2015. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | import sys 17 | import os 18 | from sphinx.builders.html import StandaloneHTMLBuilder 19 | import sphinx_rtd_theme 20 | 21 | # use gif first, then png 22 | StandaloneHTMLBuilder.supported_image_types = ['image/gif', 'image/svg+xml', 'image/png', 'image/jpeg'] 23 | 24 | # If extensions (or modules to document with autodoc) are in another directory, 25 | # add these directories to sys.path here. If the directory is relative to the 26 | # documentation root, use os.path.abspath to make it absolute, like shown here. 27 | #sys.path.insert(0, os.path.abspath('.')) 28 | 29 | # -- General configuration ------------------------------------------------ 30 | 31 | # If your documentation needs a minimal Sphinx version, state it here. 32 | #needs_sphinx = '1.0' 33 | 34 | # Add any Sphinx extension module names here, as strings. They can be 35 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 36 | # ones. 37 | extensions = [ 38 | "sphinxcontrib.jquery", 39 | "sphinx_rtd_theme", 40 | ] 41 | 42 | # Add any paths that contain templates here, relative to this directory. 43 | templates_path = ['_templates'] 44 | 45 | # The suffix of source filenames. 46 | source_suffix = '.rst' 47 | 48 | # The encoding of source files. 49 | #source_encoding = 'utf-8-sig' 50 | 51 | # The master toctree document. 52 | master_doc = 'index' 53 | 54 | # General information about the project. 55 | project = 'elabftw' 56 | copyright = '2012, Nicolas CARPi' 57 | 58 | # The version info for the project you're documenting, acts as replacement for 59 | # |version| and |release|, also used in various other places throughout the 60 | # built documents. 61 | # 62 | # The short X.Y version. 63 | version = '5.2' 64 | # The full version, including alpha/beta/rc tags. 65 | release = '5.2.4' 66 | 67 | # The language for content autogenerated by Sphinx. Refer to documentation 68 | # for a list of supported languages. 69 | #language = None 70 | 71 | # There are two options for replacing |today|: either, you set today to some 72 | # non-false value, then it is used: 73 | #today = '' 74 | # Else, today_fmt is used as the format for a strftime call. 75 | #today_fmt = '%B %Y' 76 | 77 | # List of patterns, relative to source directory, that match files and 78 | # directories to ignore when looking for source files. 79 | exclude_patterns = ['_build'] 80 | 81 | # The reST default role (used for this markup: `text`) to use for all 82 | # documents. 83 | #default_role = None 84 | 85 | # If true, '()' will be appended to :func: etc. cross-reference text. 86 | #add_function_parentheses = True 87 | 88 | # If true, the current module name will be prepended to all description 89 | # unit titles (such as .. function::). 90 | #add_module_names = True 91 | 92 | # If true, sectionauthor and moduleauthor directives will be shown in the 93 | # output. They are ignored by default. 94 | #show_authors = False 95 | 96 | # The name of the Pygments (syntax highlighting) style to use. 97 | pygments_style = 'sphinx' 98 | 99 | # A list of ignored prefixes for module index sorting. 100 | #modindex_common_prefix = [] 101 | 102 | # If true, keep warnings as "system message" paragraphs in the built documents. 103 | #keep_warnings = False 104 | 105 | 106 | # -- Options for HTML output ---------------------------------------------- 107 | 108 | # The theme to use for HTML and HTML Help pages. See the documentation for 109 | # a list of builtin themes. 110 | #html_theme = 'alabaster' 111 | html_theme = 'sphinx_rtd_theme' 112 | 113 | # Theme options are theme-specific and customize the look and feel of a theme 114 | # further. For a list of options available for each theme, see the 115 | # documentation. 116 | html_theme_options = { 117 | 'navigation_depth': 5, 118 | } 119 | 120 | # Add any paths that contain custom themes here, relative to this directory. 121 | #html_theme_path = [] 122 | 123 | # The name for this set of Sphinx documents. If None, it defaults to 124 | # " v documentation". 125 | #html_title = None 126 | 127 | # A shorter title for the navigation bar. Default is the same as html_title. 128 | #html_short_title = None 129 | 130 | # The name of an image file (relative to this directory) to place at the top 131 | # of the sidebar. 132 | #html_logo = None 133 | 134 | # The name of an image file (within the static path) to use as favicon of the 135 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 136 | # pixels large. 137 | #html_favicon = None 138 | 139 | # Add any paths that contain custom static files (such as style sheets) here, 140 | # relative to this directory. They are copied after the builtin static files, 141 | # so a file named "default.css" will overwrite the builtin "default.css". 142 | #html_static_path = ['_static'] 143 | 144 | # Add any extra paths that contain custom files (such as robots.txt or 145 | # .htaccess) here, relative to this directory. These files are copied 146 | # directly to the root of the documentation. 147 | #html_extra_path = [] 148 | 149 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 150 | # using the given strftime format. 151 | #html_last_updated_fmt = '%b %d, %Y' 152 | 153 | # If true, SmartyPants will be used to convert quotes and dashes to 154 | # typographically correct entities. 155 | #html_use_smartypants = True 156 | 157 | # Custom sidebar templates, maps document names to template names. 158 | #html_sidebars = {} 159 | 160 | # Additional templates that should be rendered to pages, maps page names to 161 | # template names. 162 | #html_additional_pages = {} 163 | 164 | # If false, no module index is generated. 165 | #html_domain_indices = True 166 | 167 | # If false, no index is generated. 168 | #html_use_index = True 169 | 170 | # If true, the index is split into individual pages for each letter. 171 | #html_split_index = False 172 | 173 | # If true, links to the reST sources are added to the pages. 174 | #html_show_sourcelink = True 175 | 176 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 177 | #html_show_sphinx = True 178 | 179 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 180 | #html_show_copyright = True 181 | 182 | # If true, an OpenSearch description file will be output, and all pages will 183 | # contain a tag referring to it. The value of this option must be the 184 | # base URL from which the finished HTML is served. 185 | #html_use_opensearch = '' 186 | 187 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 188 | #html_file_suffix = None 189 | 190 | # Output file base name for HTML help builder. 191 | htmlhelp_basename = 'elabftwdoc' 192 | 193 | 194 | # -- Options for LaTeX output --------------------------------------------- 195 | 196 | # Use an UTF-8 capable engine (default is pdflatex) 197 | latex_engine = 'xelatex' 198 | 199 | latex_elements = { 200 | # The paper size ('letterpaper' or 'a4paper'). 201 | #'papersize': 'letterpaper', 202 | 203 | # The font size ('10pt', '11pt' or '12pt'). 204 | #'pointsize': '10pt', 205 | 206 | # Additional stuff for the LaTeX preamble. 207 | #'preamble': '', 208 | } 209 | 210 | # Grouping the document tree into LaTeX files. List of tuples 211 | # (source start file, target name, title, 212 | # author, documentclass [howto, manual, or own class]). 213 | latex_documents = [ 214 | ('index', 'elabftw.tex', 'elabftw Documentation', 215 | 'Nicolas CARPi', 'manual'), 216 | ] 217 | 218 | # The name of an image file (relative to this directory) to place at the top of 219 | # the title page. 220 | #latex_logo = None 221 | 222 | # For "manual" documents, if this is true, then toplevel headings are parts, 223 | # not chapters. 224 | #latex_use_parts = False 225 | 226 | # If true, show page references after internal links. 227 | #latex_show_pagerefs = False 228 | 229 | # If true, show URL addresses after external links. 230 | #latex_show_urls = False 231 | 232 | # Documents to append as an appendix to all manuals. 233 | #latex_appendices = [] 234 | 235 | # If false, no module index is generated. 236 | #latex_domain_indices = True 237 | 238 | 239 | # -- Options for manual page output --------------------------------------- 240 | 241 | # One entry per manual page. List of tuples 242 | # (source start file, name, description, authors, manual section). 243 | man_pages = [ 244 | ('index', 'elabftw', 'elabftw Documentation', 245 | ['Nicolas CARPi'], 1) 246 | ] 247 | 248 | # If true, show URL addresses after external links. 249 | #man_show_urls = False 250 | 251 | 252 | # -- Options for Texinfo output ------------------------------------------- 253 | 254 | # Grouping the document tree into Texinfo files. List of tuples 255 | # (source start file, target name, title, author, 256 | # dir menu entry, description, category) 257 | texinfo_documents = [ 258 | ('index', 'elabftw', 'elabftw Documentation', 259 | 'Nicolas CARPi', 'elabftw', 'One line description of project.', 260 | 'Miscellaneous'), 261 | ] 262 | 263 | # Documents to append as an appendix to all manuals. 264 | #texinfo_appendices = [] 265 | 266 | # If false, no module index is generated. 267 | #texinfo_domain_indices = True 268 | 269 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 270 | #texinfo_show_urls = 'footnote' 271 | 272 | # If true, do not generate a @detailmenu in the "Top" node's menu. 273 | #texinfo_no_detailmenu = False 274 | -------------------------------------------------------------------------------- /doc/debug.rst: -------------------------------------------------------------------------------- 1 | .. _debug: 2 | 3 | ***** 4 | Debug 5 | ***** 6 | 7 | You have an issue with your eLabFTW installation? Here are the things you should check before opening an issue on GitHub ;) 8 | 9 | Docker logs 10 | =========== 11 | 12 | If the server is not responding at all, check the web container logs. If the application cannot connect to MySQL, check the mysql container logs. 13 | 14 | .. code-block:: bash 15 | 16 | # to check if the containers are running 17 | elabctl status 18 | # or 19 | docker ps 20 | # for the web container 21 | docker logs elabftw 22 | # for the mysql container 23 | docker logs mysql 24 | 25 | PHP logs 26 | ======== 27 | 28 | If you get "An error occurred!" message, check the PHP logs. All errors should be logged there. 29 | 30 | .. code-block:: bash 31 | 32 | docker logs elabftw 1>/dev/null 33 | 34 | Accessing MySQL database 35 | ======================== 36 | 37 | Sometimes it might be necessary to look directly into the database. You can use `elabctl mysql` to get a MySQL prompt directly. 38 | 39 | Clean everything 40 | ================ 41 | 42 | If you're not sure what to do to fix issues, or you have an error that seems unresolvable. You can try this: 43 | 44 | .. code-block:: bash 45 | 46 | # stop everything 47 | elabctl stop 48 | # check nothing is running 49 | docker ps -a 50 | # cleanup everything 51 | docker system prune -a 52 | # start again 53 | elabctl start 54 | 55 | Note that this procedure is safe and won't impact your data. Upon starting, it will redownload the docker images and start fresh containers. 56 | 57 | Resetting a password directly from MySQL 58 | ======================================== 59 | 60 | If you can't reset a password because the mail system doesn't work and have access to the MySQL database, you can reset it manually. 61 | 62 | First connect to a MySQL prompt: 63 | 64 | .. code-block:: bash 65 | 66 | # docker users 67 | elabctl mysql 68 | 69 | Find out the userid of the user you want to reset the password: 70 | 71 | .. code-block:: sql 72 | 73 | SELECT userid FROM users WHERE firstname = 'XXX'; 74 | 75 | Replace XXX with the firstname. You can of course also search with "email" or "lastname". Now that you have the userid, we need to change the `password_hash` column. The `password_hash` column will be: 76 | 77 | $2y$10$KXkB/w1NhLnl1mHbK0yTsuAbgJ8st4qQ2i36KyTk7kwo.G6Oq6LXa 78 | 79 | .. code-block:: sql 80 | 81 | UPDATE users SET password_hash = "$2y$10$KXk..." WHERE userid = X; 82 | 83 | Replace X with the correct userid. 84 | 85 | Once this is done, you can login with the password: "totototo". Make sure to change it again from the Settings page once logged in! 86 | -------------------------------------------------------------------------------- /doc/docker-doc.rst: -------------------------------------------------------------------------------- 1 | .. _docker-doc: 2 | 3 | ************ 4 | About Docker 5 | ************ 6 | 7 | .. image:: img/docker.png 8 | :align: center 9 | :alt: docker 10 | 11 | Introduction 12 | ============ 13 | 14 | This page explains the containerization technology in broad strokes. 15 | 16 | eLabFTW works with containers (`wikipedia `_). The `official image `_, from which containers will be created, bundles everything eLabFTW needs to run. This workflow can be managed by `Docker `_ with `docker-compose `_ or `Podman `_ with systemd services. 17 | 18 | One of the main advantages of using the containerization technology is to allow you to run eLabFTW without modifying the configuration of your server. By using the official image you don't have to worry about missing php extensions, wrong php version or misconfigurations of the server because everything was configured for you beforehand. It's also **much easier to upgrade** and keep your installation up to date and secure. 19 | 20 | On the development side, it facilitate many things as it gives more control to the application environment to the developers. 21 | 22 | Finally, the containerization technology is massively used nowadays by cloud/IT companies and you can imagine that there are many good reasons for that. 23 | 24 | How does it work? 25 | ================= 26 | 27 | 28 | .. note:: This document is about Docker + docker-compose but the same principles apply to a Podman installation. 29 | 30 | The most important file is your docker-compose configuration file (see `example file `_). While it is possible to launch containers without docker-compose (by running individual `docker run ...` commands), it is strongly advised to use this `docker-compose.yml` file (or `/etc/elabftw.yml`). It contains all the configuration options needed to customize your instance. 31 | 32 | Docker will take care of downloading the official image. In the `image:` part of the configuration, you can target a specific version or branch by specifying a tag. Example: `image: elabftw/elabimg:4.3.0` or `image: elabftw/elabimg:next`. Omitting a tag corresponds to `latest`, which will pull the latest stable version. 33 | 34 | Once downloaded, a container is created from the image, and the webserver starts to listen on the specified port for incoming requests. The default configuration also launches a MySQL container from the official MySQL image but it is not mandatory and another MySQL server can be used. Other containers like Redis or PHPMyAdmin can also be launched, depending on the configuration you want. 35 | 36 | If you already have let's say an Apache server running and are considering installing eLabFTW along your other PHP projects, know that you can keep your existing Apache installation and use it as a reverse proxy to a Docker container. See the `documentation for reverse proxies `_. 37 | 38 | About the Docker image 39 | ====================== 40 | - The eLabFTW Docker image is using `Alpine Linux `_ as a base OS, so we get a lightweight and secure base. 41 | - `PHP 8 `_ is used so we get an up to date and fast PHP. 42 | - `Nginx `_ is used so we get the best webserver out there running our app with `HTTP/2 `_ capabilities. A custom nginx is compiled for eLabFTW. 43 | 44 | Using the provided Docker image adds security features automatically: 45 | 46 | - header X-Frame-Option 47 | - header X-XSS-Protection 48 | - header X-Content-Type-Options 49 | - header Strict-Transport-Security 50 | - header Content-Security-Policy to prevent XSS 51 | - use Diffie-Hellman for key exchange with 2048 bits parameter 52 | - use modern cipher suite and protocols for SSL. This will result in an A rating on `SSLLabs `_, as you can see below. 53 | - custom secure php configuration 54 | - custom secure nginx configuration 55 | - have a score of 115/100 on `Mozilla's Observatory `_: 56 | 57 | .. image:: img/observatory.png 58 | :align: center 59 | :alt: mozilla's observatory scan 60 | 61 | 62 | Test scan of an eLabFTW install at `SecurityHeaders.io `_: 63 | 64 | .. image:: img/securityheaders.io.png 65 | :align: center 66 | :alt: security headers result 67 | 68 | Test scan of an eLabFTW install at `Qualys SSL labs `_: 69 | 70 | .. image:: img/qualys-ssl-report.png 71 | :align: center 72 | :alt: SSL labs report 73 | 74 | Just for fun, try to use these two websites to scan the sites of other services you might use or consider using. You'll see a lot of F marks… I'll let you draw your own conclusions from that ;) 75 | 76 | You don't have to be a specialist in web security to see that some services are completely insecure and should be avoided. There is a reason why cybercrime makes millions of dollars, a lot of companies have outdated installations and never follow good practices. 77 | 78 | While full security can never be completely achieved when it comes to web and computers, with eLabFTW at least you have the best possible setup to mitigate or stop the most commons attacks. Especially if you use a Docker container. 79 | 80 | Why can't I run it outside Docker 81 | ================================= 82 | 83 | While there might be valid use case for running eLabFTW without containers (example: running a BSD operating system), a choice have been made to completely drop support for non-Docker installations. 84 | 85 | An application like eLabFTW is highly complex and composed of many parts. Using a container removes variability and prevents misconfigurations and bugs. There are so many ways to run a PHP app that it quickly becomes an impossible task to correctly test for all use cases. Having to support two kind of installs (with and without Docker) adds complexity to the code and documentation. 86 | 87 | **Real world reasons that motivated this choice:** 88 | 89 | * users running eLabFTW without proper security headers in the webserver config 90 | * issues related to a different webserver (eLabFTW uses nginx) 91 | * issues related to different operating systems 92 | * unnecessary complexity in the code to check if things are available and support different configurations 93 | * unnecessary documentation work for non-Docker users 94 | * high time cost of upgrading for sysadmins due to dependencies updates (example: installing new php version) leaving instances out-of-date 95 | * all the positive aspects of running containers, as described above 96 | 97 | Running an eLabFTW instance in Docker doesn't mean there will never be any issue, but at least it reduces greatly the "bug surface". 98 | -------------------------------------------------------------------------------- /doc/faq.rst: -------------------------------------------------------------------------------- 1 | .. _faq: 2 | 3 | ************************** 4 | Frequently asked questions 5 | ************************** 6 | 7 | But how is it better than something I can buy? 8 | ============================================== 9 | 10 | The difference is huge. Because eLabFTW is not only free (as in beer), but it is free (as in speech). This means that you can have a look at the code (and improve it) and you can also redistribute the code with your improvements. 11 | 12 | But more importantly, you cannot trust your data with something that acts like a **black box**. What if the data you upload on the server of a company can be read by someone else? With eLabFTW, you install it on your own server, and you are the master of your data at all time. 13 | 14 | What about patents and intellectual property? 15 | ============================================= 16 | 17 | Since March 2013, the USA modified their law (see `America Invents Act `_) to switch from first-to-invent to first-inventor-to-file. This means that proving that you did this experiment before someone else has become less critical. It is only needed if you invented something, before someone put a patent on it (and you can prove it), and you want to keep using it as **prior user**. 18 | 19 | Fortunately, eLabFTW allows rock solid timestamping of your experiments. With just one click of a mouse, you can timestamp your work. There are currently two strategies available for timestamping: Trusted Timestamping and Blockchain Timestamping. 20 | 21 | Trusted timestamping 22 | -------------------- 23 | This is the protocol defined by :rfc:`3161`, here is how it works: 24 | 25 | 1. we first generate a JSON export of the entity, containing all the data relevant to that entry 26 | 2. we pass it through a cryptographic hash function to get its fingerprint 27 | 3. we request a timestamp token from the Time Stamping Authority (TSA) 28 | 4. we store the JSON file along with the token in an immutable ZIP archive (visible if you display archived attachments of a timestamped entry) 29 | 30 | A TSA is a trusted timestamping service that will be used to request a token. Several TSA are already configured in eLabFTW: 31 | 32 | - DFN.de (free academic service, default TSA) 33 | - Universign (eIDAS qualified, paid service) 34 | - Digicert (free) 35 | - Sectigo (free) 36 | - GlobalSign (free) 37 | - Custom: you can define your own service if necessary 38 | 39 | Blockchain timestamping 40 | ----------------------- 41 | This timestamping method uses the `Bloxberg consortium `_ blockchain to timestamp your data. Here is how it works: 42 | 43 | 1. we first generate a JSON export of the entity, containing all the data relevant to that entry 44 | 2. we pass it through a cryptographic hash function to get its fingerprint 45 | 3. we add it to the Ethereum based blockchain 46 | 4. we store the JSON file along with a PDF certifying our data in an immutable ZIP archive (visible if you display archived attachments of a timestamped entry) 47 | 48 | 49 | Why use eLabFTW? 50 | ================ 51 | 52 | * **It's free and open source software** 53 | * It improves the value of your experiments by allowing you to keep a good track of it 54 | * It makes searching your data as easy as a google search 55 | * Everything can be organized in your lab 56 | * It makes it easy to share information between co-workers or collaborators 57 | * It is simple to install and to keep up to date 58 | * **It works for Windows, Mac OS X, Linux, BSD, Solaris, etc…** 59 | * Protected access with login/password (password is very securely stored as salted SHA-512 sum) 60 | * It can be used by multiple users at the same time 61 | * **It can be used by multiple teams** 62 | * You can have templates for experiments you do often 63 | * **You can export an experiment as a PDF** 64 | * **You can timestamp an experiment so it is legally strong** 65 | * You can export one or several experiments as a ZIP archive 66 | * You can duplicate experiments in one click 67 | * There is advanced search capabilities 68 | * You can write in Markdown 69 | * The tagging system allows you to keep track of family of experiments 70 | * Experiments can have color coded statuses (that you can edit at will) 71 | * You can link an experiment with an item from the database to retrieve in a click the plasmid/sirna/antibody/chemical you used 72 | * And it works the other way around, you can find all experiments done with a particular item from the database! 73 | * blockchain blockchain blockchain 74 | * There is a locking mechanism preventing further edition 75 | * You can comment on an experiment (if it's not your experiment) 76 | * You can import your old database stored in an excel file 77 | * You can use it in your language 78 | * :doc:`and much more… ` 79 | 80 | You also have to consider the fact that installing eLabFTW on your own server means that no one will be able to snoop on your data. If you have ever used Evernote or basically any online ELN that says «Free», read carefully the privacy policy, you might be surprised what they allow themselves to do under the cover of «to improve your experience»… 81 | 82 | 83 | Is this system stable? Can I trust my data with it? 84 | =================================================== 85 | 86 | Yes. It is used in numerous research centers all over the world since a few years now and if an issue is found it is quickly reported and fixed. 87 | 88 | However, having an automated :ref:`backup ` strategy is mandatory in order to be sure **nothing will be lost**. 89 | 90 | Being able to do backups is yet another advantage over paper (you can't backup paper!). 91 | 92 | Who else is using it? 93 | ===================== 94 | 95 | We do not maintain a list of institutions using it anymore. There are just too many. Consider that there are thousands of eLabFTW instances worldwide. 96 | 97 | In France, it's the ELN of choice for the CNRS, the 3rd largest research organization in the world, along with many other universities and research institutes. It is also useful to startups and companies. 98 | 99 | In Germany, it is ubiquitous. Installed in many universities and private companies. 100 | 101 | In Europe, it is often seen being used in universities and research centers. 102 | 103 | In the rest of the world, it is also used, because its interface is translated in 17 languages, including many asian languages. 104 | 105 | Is the data encrypted? 106 | ====================== 107 | 108 | The data is encrypted when travelling from your browser to the server with the highest quality encryption currently available (TLSv1.2/1.3 with modern ciphers). 109 | 110 | The passwords are not recoverable in case of a breach and are hashed using state of the art algorithms. 111 | 112 | Only manually validated accounts can interact with the software. It is secure by default. 113 | 114 | If you wish to have data at rest encryption, it needs to be done during the web server installation, and is not the concern of the software itself. 115 | 116 | Is eLabFTW still maintained? 117 | ============================ 118 | 119 | Not only it is maintained, but it is actively being worked on, with major new features and improvements being added regularly. 120 | 121 | Since 2019, the company `Deltablot `_ exists to provide support and hosting to eLabFTW users around the world. This company will allow funding further development of the software thanks to an original business model: the software itself is entirely free, but the individual support, custom features development and hosting are paid options. 122 | 123 | If you are interested in such options, please visit this page: `Deltablot's elabftw page `_. 124 | 125 | Will I be able to import my plasmids/antibodies/whatever in the database from a Excel file? 126 | =========================================================================================== 127 | 128 | Yes, see :ref:`Import CSV Documentation `. 129 | 130 | Can I try it before I install it? 131 | ================================= 132 | 133 | Sure, there is a demo online here: `eLabFTW live DEMO `_. 134 | 135 | What are the technical requirements? 136 | ==================================== 137 | 138 | eLabFTW is a server software that should be installed on a server. 139 | 140 | Requirements for the server 141 | --------------------------- 142 | 143 | The following specification has been shown to perform well for an instance of several hundred daily users. The more users using the instance, the more CPU and RAM you'll need. 144 | 145 | **Hardware** 146 | 147 | At least 2Gb of RAM, a decent processor (> 2GHz), preferably multi-core and an SSD disk with at least a few Gb free. 148 | 149 | **Software** 150 | 151 | The operating system of the server must be a flavor of GNU/Linux. We recommend Rocky Linux or RHEL. 152 | 153 | The service runs in containers (`Docker `_ or `Podman `_), which are a Linux specific technology. 154 | 155 | A **MySQL** database service is required. You can deploy a MySQL service with Docker by following the standard installation procedure, or use an existing separate MySQL server. Only **MySQL** is supported. Not PostgreSQL, not MariaDB, not SQLite. 156 | 157 | Requirements for the clients (users) 158 | ------------------------------------ 159 | 160 | - Any operating system with either Firefox, or Chrome based browser (Chrome, Chromium, Edge, Brave, Opera). Safari is `known to cause issues `_ and is not officially supported. Internet Explorer is not supported. 161 | - An internet connection. 162 | 163 | What about data retention/traceability 164 | ====================================== 165 | 166 | When a user is making a change to an experiment, a copy of the previous version is kept in the database. This copy cannot be altered by anyone. The admin can also prevent users from deleting experiments, and the creation date is kept in memory, even if the date field is changed later on. 167 | 168 | When an entry is deleted, it is not completely removed from the database, but instead marked as deleted. Same with attached files: overwriting a file will mark the previous version as "Archived". 169 | 170 | Is it compliant to 21CFR Part 11? 171 | ================================= 172 | 173 | 1. Closed system: eLabFTW requires unique credentials to access the system. A system of permissions and roles allow fine control of what can be seen by whom. 174 | 175 | 2. Experiments and resources (protocols, reagents, cell lines...) can be signed with cryptographic signatures, verifiable outside the system, and stored in an immutable archive. 176 | 177 | 3. Trusted timestamping: RFC3161 Trusted Timestamping is available for experiments. When using a qualified TSA such as Universign, this makes the process compliant with ETSI EN 319 42 (eIDAS european regulation). 178 | 179 | 4. Audit trail: changes to entries are internally recorded and cannot be tampered with by users. A version history is available, with adjustable granularity. 180 | 181 | 5. Retention of records: a soft-delete mechanism prevents destructive actions on data. 182 | 183 | 6. Copies of records: you can export your data in PDF, ZIP archives or CSV files very easily. This can also be automated via the API. 184 | 185 | 7. Password policy: passwords are securely stored in the database and security mechanisms such as preventing too many authentication tries are in place. Password policies can also be enforced, and centralized authentication mechanisms can be setup. 186 | 187 | What about GMP compliance? 188 | ========================== 189 | 190 | GMP Compliance Statement for eLabFTW 191 | 192 | 1. Introduction 193 | 194 | eLabFTW is an open-source electronic lab notebook (ELN) and database designed for academic, industrial, and research institutions. This document outlines how eLabFTW complies with Good Manufacturing Practice (GMP) requirements, particularly in contexts where digital recordkeeping must meet regulatory standards. 195 | 196 | 2. System Overview 197 | 198 | eLabFTW provides features essential for compliance with GMP, including: 199 | 200 | * Secure and tamper-evident electronic recordkeeping 201 | * Comprehensive audit trails 202 | * User authentication and access control 203 | * Version control of records 204 | * Role-based permission management 205 | * Timestamped entries 206 | 207 | 3. GMP-Relevant Compliance Features 208 | 209 | 3.1 Data Integrity and Security 210 | 211 | eLabFTW ensures data integrity through: 212 | 213 | * Enforced HTTPS connections 214 | * Encrypted data in transit 215 | * Automatic backups 216 | * Tamper-evident log entries 217 | 218 | 3.2 Audit Trails 219 | 220 | Nearly every action performed in eLabFTW is logged. The audit trail includes: 221 | 222 | * Timestamp of the action 223 | * User identity 224 | * Nature of the change (e.g., edit, delete) 225 | * Linked records or experiments 226 | 227 | 3.3 User Management and Access Control 228 | 229 | * Each user has a unique login with secure password requirements 230 | * Role-based access controls limit user permissions 231 | * Admins can assign and revoke roles 232 | * Inactive users can be disabled to maintain access security 233 | 234 | 3.4 Electronic Signatures eLabFTW supports electronic signatures that are: 235 | 236 | * Unique to each user 237 | * Tied to a specific time and action 238 | * Stored in immutable archives 239 | * Using state of the art cryptography 240 | 241 | 3.5 Validation and Qualification 242 | 243 | eLabFTW supports system validation through: 244 | 245 | * Open-source codebase (fully inspectable) 246 | * Documented update logs and change management 247 | 248 | 3.6 Data Retention and Exportability 249 | 250 | * Data can be exported in human-readable and machine-readable formats 251 | * Archived data remains accessible and readable 252 | * Long-term retention complies with GMP recordkeeping requirements 253 | 254 | 4. Implementation Best Practices 255 | 256 | To ensure GMP compliance, administrators should: 257 | 258 | * Implement validated backup strategies 259 | * Maintain system validation documentation 260 | * Define and enforce access policies 261 | * Perform regular audits using eLabFTW's built-in reporting tools 262 | * Train users on GMP principles and proper usage of eLabFTW 263 | 264 | 5. Conclusion 265 | 266 | When properly configured and maintained, eLabFTW provides the necessary functionality to support GMP compliance in electronic documentation and laboratory recordkeeping environments. For full compliance, users must align eLabFTW usage with their internal SOPs and regulatory guidelines. 267 | 268 | 6. References 269 | 270 | `EU GMP Annex 11: Computerised Systems `_ 271 | 272 | 273 | 274 | What about compliance to standards? 275 | =================================== 276 | eLabFTW tries to comply to the following standards : 277 | 278 | * `Code of Federal Regulations Title 21, paragraph 11 `_ 279 | * `FERPA `_ 280 | * `HIPAA `_ 281 | * `FISMA `_ 282 | 283 | The timestamping is based on RFC3161 standardized protocol and fits with the eIDAS european regulation (910/2014). 284 | 285 | How to change the team of a user? 286 | ================================= 287 | 288 | There is two ways to do that: 289 | 290 | * if the user registered in the wrong team, the Sysadmin can simply change the team from the Sysadmin panel 291 | * if the user switched team, old team needs to Archive the user (from the Admin panel), and user needs to register a new account (same email can be used) in the new team 292 | 293 | Is there a plugin system? 294 | ========================= 295 | 296 | No, eLabFTW has no plugins and no plan to add support for it. This decision is motivated by several factors: 297 | 298 | - security of the application: a badly written plugin might compromise an instance (this happens daily with Wordpress plugins) 299 | - a stable plugin API has to be maintained, which is a heavy burden on development, as plugins will hook into internals, and it opens the door to a never ending stream of requests about adding hooks here and there 300 | - our vision is about a single coherent codebase, not a morcellated software 301 | 302 | If you wish to add functionality to eLabFTW, the best is to discuss it in an issue, and eventually create a pull request with the code you want to merge, rather than planning on plugins. 303 | 304 | Is it totally free? 305 | =================== 306 | 307 | YES. eLabFTW is free/libre software, so it is totally free of charge and always will be. `Read more about the free software philosophy `_. 308 | 309 | 310 | What is the meaning of 'FTW'? 311 | ============================= 312 | 313 | One of those: 314 | 315 | - For The World 316 | - For Those Wondering 317 | - For The Worms 318 | - Forever Two Wheels 319 | - Free The Wookies 320 | - Forward The Word 321 | - Forever Together Whenever 322 | - Face The World 323 | - Forget The World 324 | - Free To Watch 325 | - Feed The World 326 | - Feel The Wind 327 | - Feel The Wrath 328 | - Fight To Win 329 | - Find The Waldo 330 | - Finding The Way 331 | - Flying Training Wing 332 | - Follow The Way 333 | - For The Wii 334 | - For The Win 335 | - For The Wolf 336 | - Free The Weed 337 | - Free The Whales 338 | - From The Wilderness 339 | - Freedom To Work 340 | - For The Warriors 341 | - Full Time Workers 342 | - Fabricated To Win 343 | - Furiously Taunted Wookies 344 | - Flash The Watch 345 | -------------------------------------------------------------------------------- /doc/features.rst: -------------------------------------------------------------------------------- 1 | .. _features: 2 | 3 | ******** 4 | Features 5 | ******** 6 | 7 | General 8 | ======= 9 | * Free as in speech 10 | * Free as in beer 11 | * Web application: accessible to users like any other website through their web browser 12 | * Multiple teams: one eLabFTW instance can host several teams, each composed of users, that can belong to multiple teams 13 | * Supported software: development and maintenance is ensured by the `Deltablot `_ company 14 | 15 | For Sysadmins 16 | ============= 17 | * Dockerized service: containerization technology facilitates deployments and updates, by ensuring a specific application environment 18 | * Centralized authentication with SAML2 or LDAP 19 | * S3 compatible object storage for uploaded files 20 | * Several options to configure the user provisioning workflow 21 | * Possibility to restrict email domains 22 | 23 | Experiments and Resources 24 | ========================= 25 | * Status, Categories, Tags 26 | * Rich text editor (WYSIWYG) or Markdown editor 27 | * Advanced permission system 28 | * Upload multiple files of any kind 29 | * Insert images into text 30 | * Steps list 31 | * Templates 32 | * Duplicate entries 33 | * Supported export formats: PDF, PDF/A, JSON, ZIP, ELN, CSV 34 | * Advanced export and import functions for entries, users or teams 35 | * Supported import formats: CSV, ELN 36 | * Lock the experiment 37 | * Request reviews or actions from other users 38 | * Support for various file types that will render in 2D or 3D (.mol, .sdf, .pdb, etc...) 39 | * Links between entities 40 | * Molecule editor 41 | * User groups to restrict read access among a team 42 | * Doodle canvas 43 | * Rating system 44 | 45 | Security 46 | ======== 47 | * HTTPS 48 | * CSRF protection 49 | * Secure headers 50 | * Automated vulnerability scans on Docker images 51 | * Secure PHP settings 52 | * Anti bruteforce system 53 | * Secure storage of password (bcrypt) 54 | * Secure password reset mechanism 55 | * Option for new account admin validation 56 | * Two-factor authentication (TOTP) 57 | * Password policies with complexity and expiration 58 | 59 | Intellectual property, integrity and imputability 60 | ================================================= 61 | * :rfc:`3161` compliant Trusted Timestamping 62 | * Blockchain timestamping 63 | * Audit logs 64 | * Revisions and Changelog systems to track changes 65 | * Cryptographic signatures (ed25519) 66 | * Support for Keeex (see https://keeex.me/) 67 | 68 | User experience 69 | =============== 70 | * Lovely design (by @manonstripes) 71 | * Internationalization (several languages available) 72 | * Optimized code/assets for speed and correctness 73 | * WCAG 2.1 accessibility compliance 74 | * Various configuration options for Sysadmins, Admins or Users 75 | * Customizable keyboard shortcuts 76 | * TODOlist 77 | -------------------------------------------------------------------------------- /doc/generalities.rst: -------------------------------------------------------------------------------- 1 | .. _generalities: 2 | 3 | ************ 4 | Generalities 5 | ************ 6 | 7 | Lexicon 8 | ======= 9 | Let's define a few terms first: 10 | 11 | * **Instance**: a running eLabFTW service, for example: https://eln.example.org 12 | * **Team**: the main way to compartimentalize users 13 | * **Sysadmin**: a user with Sysadmin rights can modify the Instance configuration and create Teams, it is generally the same person that installed the Instance 14 | * **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 15 | * **User**: a user with an account on the Instance, belonging to at least one Team 16 | 17 | General principles 18 | ================== 19 | 20 | One eLabFTW instance can host several Teams. 21 | 22 | Every User needs to belong to at least one Team. Every team must have at least one Admin user. 23 | 24 | .. code-block:: html 25 | 26 | ┌────────────────────────┐ 27 | │ │ 28 | │ eLabFTW Instance │ 29 | │ │ 30 | └────┬───────────┬─────┬─┘ ┌──────────┐ 31 | │ │ │ │ Team C │ 32 | │ │ │ ├──────────┤ 33 | │ │ └──────► │ Admin 1 │ 34 | │ │ │ User 1 │ 35 | ▼ ▼ │ User 2 │ 36 | ┌──────────┐ ┌──────────┐ │ User 3 │ 37 | │ Team A │ │ Team B │ │ User 4 │ 38 | ├──────────┤ ├──────────┤ └──────────┘ 39 | │ Admin 1 │ │ Admin 1 │ 40 | │ User 1 │ │ Admin 2 │ 41 | │ User 2 │ │ Admin 3 │ 42 | │ User 3 │ │ User 1 │ 43 | └──────────┘ │ User 2 │ 44 | │ User 3 │ 45 | └──────────┘ 46 | 47 | Teams 48 | ===== 49 | A Team generally correspond to a real life research group or service. It is not advisable to use Teams as Projects as this doesn't scale well (and Teamgroups can be used instead for that purpose). A User can belong to several teams if needed, they will then need to select a team upon login. 50 | 51 | Every Team has one or several Admin, who can change many settings affecting users in the team, such as the default experimental template, categories for database items (Items Types), experiments Status, Tags, etc... 52 | 53 | Teams are created by the Sysadmin from the Sysconfig page (:ref:`see documentation `). 54 | 55 | Experiments and Resources 56 | ========================= 57 | 58 | There are two main types of records that exist: **Experiments** and **Resources**. They are listed in their corresponding page, accessible from the main top menu. 59 | 60 | **Experiments** are the main aspect of the ELN: it is where users log their results. 61 | 62 | **Resources** correspond to a repository of *things* present in the lab, generally physical things, such as plasmids, equipment, antibodies, chemical products, etc... They have different properties than experiments, although both objects are similar in many aspects. A Resource can be made bookable (so they can be booked in the Scheduler) or procurable (so we can order more of it). 63 | 64 | By default, Experiments and Resources are restricted to a team. But users can choose to extend this to all registered users or even anonymous users if enabled by the Sysadmin. An extensive fine-grained permission system is available for both types of records and their corresponding templates to have complete control on who get to read/write what. 65 | 66 | User accounts 67 | ============= 68 | 69 | There are several ways to manage users, they can be created by a Sysadmin, an Admin, during authentication with centralized directory, or users can create their account directly. 70 | 71 | Users can directly create their account on the register page (`/register.php`), accessible from the login page. They will need to select a team from the list. 72 | 73 | By default, newly created accounts are disabled. The admin of the team needs to validate them by going into the admin panel and activate new users. 74 | 75 | It is also possible to provision users or use an external authentication service such as an Identity Provider (IdP/SAML2) or LDAP directory. 76 | -------------------------------------------------------------------------------- /doc/how-to-update.rst: -------------------------------------------------------------------------------- 1 | .. _how-to-update: 2 | 3 | ************* 4 | How to update 5 | ************* 6 | 7 | .. warning:: Be sure to `read the release notes `_, they might contain important information. And have a :ref:`backup `. 8 | 9 | .. note:: If you are running out of disk space, you can do "docker system prune -a" to free up some space taken by old images. 10 | 11 | STEP 0: Before the update 12 | ========================= 13 | 14 | Make sure to figure out what version you are running and **read the release notes** for the new version. 15 | 16 | The current running version can be seen in the bottom right of every page. 17 | 18 | .. warning:: Be sure to `read the release notes `_, they might contain important information. And have a :ref:`backup `. 19 | 20 | STEP 1: Specify which version you want 21 | ====================================== 22 | 23 | Start by editing your configuration file (`/etc/elabftw.yml` by default) and change the version of the image (line `image: elabftw/elabimg:X.Y.Z`) 24 | 25 | The latest version can be found on `this page `_. 26 | 27 | 28 | STEP 2: Launch a new container 29 | ============================== 30 | 31 | With elabctl 32 | ------------ 33 | 34 | .. code-block:: bash 35 | 36 | elabctl update 37 | 38 | Without elabctl 39 | --------------- 40 | 41 | In the directory where you have the `docker-compose.yml` file: 42 | 43 | .. code-block:: bash 44 | 45 | docker-compose pull 46 | docker-compose down 47 | docker-compose up -d 48 | 49 | STEP 3: Run the database migration 50 | ================================== 51 | 52 | .. code-block:: bash 53 | 54 | # change the name of the container if it is different in your configuration 55 | docker exec -it elabftw bin/console db:update 56 | # Note: for version 3.3 to 3.4 use this instead 57 | docker exec -it elabftw bin/console db:updateTo34 58 | # Note: for version 2.x to 3.x use this instead 59 | docker exec -it elabftw bin/console db:updateto3 60 | 61 | Congratulations, you are now running the latest version! Make sure to keep your installation regularly updated! 62 | 63 | If you encounter an issue during the database migration, open a GitHub issue! 64 | 65 | Note that you can use `db:revert XYZ` to revert the changes made by schema `XYZ`, or use `--force` to ignore errors (only do that if you know what you are doing!). 66 | 67 | Updating from incredibly old versions 68 | ===================================== 69 | 70 | If you are running eLabFTW version <3.4.0 (from March 2020), you'll want to run ``db:updateto34`` after upgrading to 3.4.0 (again, always read the release notes from the version you're targeting). 71 | 72 | If you are running eLabFTW version <3.0.0 (from April 2019), you'll want to run ``db:updateto3`` after upgrading to 3.0.0. 73 | 74 | If you are running eLabFTW version <2.0.7 (from December 2018), you'll want to update more often so you're not stuck with an incredibly outdated software application. 75 | -------------------------------------------------------------------------------- /doc/img/1.2.1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/1.2.1.png -------------------------------------------------------------------------------- /doc/img/admin-panel-itemstypes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/admin-panel-itemstypes.png -------------------------------------------------------------------------------- /doc/img/admin-validate-user.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/admin-validate-user.png -------------------------------------------------------------------------------- /doc/img/api-keygen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/api-keygen.png -------------------------------------------------------------------------------- /doc/img/apple.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/apple.png -------------------------------------------------------------------------------- /doc/img/auth.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/auth.png -------------------------------------------------------------------------------- /doc/img/book-edit-modal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/book-edit-modal.png -------------------------------------------------------------------------------- /doc/img/book-item-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/book-item-button.png -------------------------------------------------------------------------------- /doc/img/by-sa.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/by-sa.png -------------------------------------------------------------------------------- /doc/img/can-book-setting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/can-book-setting.png -------------------------------------------------------------------------------- /doc/img/compounds-db.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-db.png -------------------------------------------------------------------------------- /doc/img/compounds-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-edit.png -------------------------------------------------------------------------------- /doc/img/compounds-editor-help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-editor-help.png -------------------------------------------------------------------------------- /doc/img/compounds-editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-editor.png -------------------------------------------------------------------------------- /doc/img/compounds-import-pubchem-modal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-import-pubchem-modal.png -------------------------------------------------------------------------------- /doc/img/compounds-safety.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/compounds-safety.png -------------------------------------------------------------------------------- /doc/img/container-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/container-app.png -------------------------------------------------------------------------------- /doc/img/contributing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/contributing.png -------------------------------------------------------------------------------- /doc/img/didyoubackup.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/didyoubackup.jpg -------------------------------------------------------------------------------- /doc/img/digitalocean.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/digitalocean.png -------------------------------------------------------------------------------- /doc/img/disable-2fa.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/disable-2fa.png -------------------------------------------------------------------------------- /doc/img/doc-info.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/doc-info.png -------------------------------------------------------------------------------- /doc/img/docker-select.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/docker-select.gif -------------------------------------------------------------------------------- /doc/img/docker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/docker.png -------------------------------------------------------------------------------- /doc/img/elabftw-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/elabftw-logo.png -------------------------------------------------------------------------------- /doc/img/export-options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/export-options.png -------------------------------------------------------------------------------- /doc/img/extra-field-builder.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-field-builder.png -------------------------------------------------------------------------------- /doc/img/extra-fields-dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-fields-dropdown.png -------------------------------------------------------------------------------- /doc/img/extra-fields-number-view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-fields-number-view.png -------------------------------------------------------------------------------- /doc/img/extra-fields-number.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-fields-number.png -------------------------------------------------------------------------------- /doc/img/extra-fields-view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-fields-view.png -------------------------------------------------------------------------------- /doc/img/extra-fields.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/extra-fields.png -------------------------------------------------------------------------------- /doc/img/favtags.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/favtags.gif -------------------------------------------------------------------------------- /doc/img/favtags.mkv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/favtags.mkv -------------------------------------------------------------------------------- /doc/img/favtags.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/favtags.png -------------------------------------------------------------------------------- /doc/img/freebsd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/freebsd.png -------------------------------------------------------------------------------- /doc/img/gnulinux.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/gnulinux.png -------------------------------------------------------------------------------- /doc/img/i18n.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/i18n.png -------------------------------------------------------------------------------- /doc/img/json-editor-mode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/json-editor-mode.png -------------------------------------------------------------------------------- /doc/img/macwin.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/macwin.jpg -------------------------------------------------------------------------------- /doc/img/markdown-editor.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/markdown-editor.gif -------------------------------------------------------------------------------- /doc/img/markdown-editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/markdown-editor.png -------------------------------------------------------------------------------- /doc/img/metadata-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/metadata-example.png -------------------------------------------------------------------------------- /doc/img/modify-booking-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/modify-booking-menu.png -------------------------------------------------------------------------------- /doc/img/modify-booking-modal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/modify-booking-modal.png -------------------------------------------------------------------------------- /doc/img/nas-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/nas-1.png -------------------------------------------------------------------------------- /doc/img/nas-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/nas-2.png -------------------------------------------------------------------------------- /doc/img/observatory.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/observatory.png -------------------------------------------------------------------------------- /doc/img/opencloning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/opencloning.png -------------------------------------------------------------------------------- /doc/img/qnap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap.png -------------------------------------------------------------------------------- /doc/img/qnap/elabftw-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/elabftw-1.png -------------------------------------------------------------------------------- /doc/img/qnap/elabftw-env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/elabftw-env.png -------------------------------------------------------------------------------- /doc/img/qnap/elabftw-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/elabftw-link.png -------------------------------------------------------------------------------- /doc/img/qnap/elabftw-ports.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/elabftw-ports.png -------------------------------------------------------------------------------- /doc/img/qnap/elabftw-volumes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/elabftw-volumes.png -------------------------------------------------------------------------------- /doc/img/qnap/mysql-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/mysql-1.png -------------------------------------------------------------------------------- /doc/img/qnap/mysql-env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/mysql-env.png -------------------------------------------------------------------------------- /doc/img/qnap/mysql-volumes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qnap/mysql-volumes.png -------------------------------------------------------------------------------- /doc/img/qualys-ssl-report.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/qualys-ssl-report.png -------------------------------------------------------------------------------- /doc/img/quick_create.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/quick_create.gif -------------------------------------------------------------------------------- /doc/img/quick_tags.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/quick_tags.gif -------------------------------------------------------------------------------- /doc/img/quick_upload.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/quick_upload.png -------------------------------------------------------------------------------- /doc/img/restore-entry.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/restore-entry.png -------------------------------------------------------------------------------- /doc/img/securityheaders.io.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/securityheaders.io.png -------------------------------------------------------------------------------- /doc/img/server-client.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/server-client.gif -------------------------------------------------------------------------------- /doc/img/settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/settings.png -------------------------------------------------------------------------------- /doc/img/show-archived-uploads.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/show-archived-uploads.png -------------------------------------------------------------------------------- /doc/img/smtp2go.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/smtp2go.jpg -------------------------------------------------------------------------------- /doc/img/sort-table.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sort-table.gif -------------------------------------------------------------------------------- /doc/img/sortable-table-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sortable-table-icon.png -------------------------------------------------------------------------------- /doc/img/sysadmin-manage-teams.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sysadmin-manage-teams.png -------------------------------------------------------------------------------- /doc/img/sysconfig-anonymous.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sysconfig-anonymous.png -------------------------------------------------------------------------------- /doc/img/sysconfig-email-warning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sysconfig-email-warning.png -------------------------------------------------------------------------------- /doc/img/sysconfig-email-warning.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sysconfig-email-warning.webp -------------------------------------------------------------------------------- /doc/img/sysconfig-teams.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/sysconfig-teams.png -------------------------------------------------------------------------------- /doc/img/tags-view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/tags-view.png -------------------------------------------------------------------------------- /doc/img/template-menu-click.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/template-menu-click.png -------------------------------------------------------------------------------- /doc/img/template-toggle-pin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/template-toggle-pin.png -------------------------------------------------------------------------------- /doc/img/templates-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/templates-menu.png -------------------------------------------------------------------------------- /doc/img/timestamp-archive.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/timestamp-archive.png -------------------------------------------------------------------------------- /doc/img/tinymce-editor-paragraph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/tinymce-editor-paragraph.png -------------------------------------------------------------------------------- /doc/img/tinymce-editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/tinymce-editor.png -------------------------------------------------------------------------------- /doc/img/user-alt-layout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-alt-layout.png -------------------------------------------------------------------------------- /doc/img/user-anonymous-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-anonymous-link.png -------------------------------------------------------------------------------- /doc/img/user-experiments-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-experiments-menu.png -------------------------------------------------------------------------------- /doc/img/user-file-uploader.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-file-uploader.png -------------------------------------------------------------------------------- /doc/img/user-guide-toolbar-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-guide-toolbar-edit.png -------------------------------------------------------------------------------- /doc/img/user-linked-entries-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-linked-entries-tools.png -------------------------------------------------------------------------------- /doc/img/user-scope-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-scope-button.png -------------------------------------------------------------------------------- /doc/img/user-show-mode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-show-mode.png -------------------------------------------------------------------------------- /doc/img/user-switch-layout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-switch-layout.png -------------------------------------------------------------------------------- /doc/img/user-toggle-pin-templates.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-toggle-pin-templates.gif -------------------------------------------------------------------------------- /doc/img/user-toggle-pin-templates.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-toggle-pin-templates.png -------------------------------------------------------------------------------- /doc/img/user-view-toolbar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/user-view-toolbar.png -------------------------------------------------------------------------------- /doc/img/view-mode-export-dropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/view-mode-export-dropdown.png -------------------------------------------------------------------------------- /doc/img/view-mode-numbered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/view-mode-numbered.png -------------------------------------------------------------------------------- /doc/img/windows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/elabftw/elabdoc/a6169a302020fa8710a75eebf09400fda3123c4f/doc/img/windows.png -------------------------------------------------------------------------------- /doc/import-export.rst: -------------------------------------------------------------------------------- 1 | .. _import-export: 2 | 3 | *************** 4 | Import / Export 5 | *************** 6 | 7 | Introduction 8 | ============ 9 | 10 | When users add information into systems like eLabFTW, that information can get trapped in this system. We do not want that. We want information to flow freely. 11 | 12 | As such, eLabFTW allows users to freely export and import data, in different file formats, as well as accessing it through a :ref:`public API `, for automation tools. 13 | 14 | This page describes the Import and Export features available in eLabFTW. 15 | 16 | .. _importing-data: 17 | 18 | Importing data 19 | ============== 20 | 21 | Data import can be used to facilitate ingestion of multiple records into the current system. It can also be a convenient way to transfer data between systems. For instance, a research group leaving an institution can export all their team's data and import it into the new institution. 22 | 23 | Import can be done from the web interface, accessible to all users, but also from the Command Line Interface (CLI), which is only accessible to Sysadmins with console access to the container. CLI import is the recommended way to import big files (such as a full team export), as it prevents issues such as timeouts, if the import takes too long. 24 | 25 | Two filetypes are currently supported for import: `.eln` (vnd.eln+zip) and `.csv` (text/csv). 26 | 27 | Importing a .eln archive 28 | ------------------------ 29 | 30 | You can import data from a `.eln` archive generated by any ELN software conforming to the `specification `_. 31 | 32 | Importing a `.eln` file created by an eLabFTW instance will produce the best results. This documentation focuses on these. 33 | 34 | A `.eln` can contain any type of data: 35 | 36 | * Experiments 37 | * Experiments templates 38 | * Resources 39 | * Resources categories 40 | 41 | eLabFTW will pick up the type of each entry through its `genre `_ attribute. Alternatively, you can force the type of entry by selecting one from the dropdown menu (web UI) or using the `--type` option (CLI). The same logic applies to selecting the appropriate category. 42 | 43 | Importing through web interface 44 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 45 | 46 | Head to the "Import" tab of your Profile page by selecting "Import" from the top right menu. 47 | 48 | Select a `.eln` file to display import options. Then click Import. 49 | 50 | Importing through CLI 51 | ^^^^^^^^^^^^^^^^^^^^^ 52 | 53 | .. note:: This approach is only available to Sysadmins with shell access. 54 | 55 | If you wish to import a rather large `.eln` archive (such as a full team export), the CLI is the better approach. Display the help with: 56 | 57 | .. code-block:: bash 58 | 59 | docker exec -it -u nginx:nginx elabftw bin/console import:eln -h 60 | 61 | As you can see, there are two mandatory arguments, the path to the file, and the Team ID where the import will be performed. The first thing to do is to copy the file in the right place in the container. It must be in `/elabftw/exports` folder. Copy it with a command similar to this: 62 | 63 | .. code-block:: bash 64 | 65 | docker cp your.eln elabftw:/elabftw/exports/ 66 | 67 | Figure out the Team ID by looking at the Teams tab from the Sysconfig panel, where the ID will be displayed next to the Team. Next, import your file with: 68 | 69 | .. code-block:: bash 70 | 71 | # import in team 12 and be verbose 72 | docker exec -it -u nginx:nginx elabftw bin/console import:eln -vv your.eln 12 73 | # import in team 25, force everything to be owned by user 5 and be extra verbose 74 | docker exec -it -u nginx:nginx elabftw bin/console import:eln -vvv your.eln 25 --userid 5 75 | # import in team 42, force everything to be of type "Resources" with category "6" 76 | docker exec -it -u nginx:nginx elabftw bin/console import:eln --type items --category 6 your.eln 42 77 | 78 | By default (if no ``--userid`` setting is provided), the ownership of the items will be 79 | determined by comparing the email addresses of users between the export and import 80 | servers. This allows for simple migration of data from one eLabFTW instance to another, 81 | even if users have differing ``userid`` values on the two instances. If the user that owns 82 | an item in the exported data is not present on the destination (import) instance, the 83 | import process will create users as necessary. 84 | 85 | 86 | .. _csvimport: 87 | 88 | Importing a .csv file 89 | --------------------- 90 | 91 | If you already have some Resources catalogued in an Excel file or File Maker database, you can import them in eLabFTW with a .csv file. 92 | A .csv file is a very simple file format. You can save a .xlsx or .ods file into this format. If using Microsoft Office, make sure to select "CSV UTF-8" in the dropdown menu. It needs to be "flat", meaning the first row is the column names, and all subsequent rows correspond to one entry. 93 | 94 | To achieve a successful import, make sure to follow these instructions: 95 | 96 | 1. Preparing the file 97 | ^^^^^^^^^^^^^^^^^^^^^ 98 | 99 | It is important to make sure that the file you are going to import is "clean". Open your file (.xls/.xlsx/.ods/.csv) in an editor like LibreOffice Calc or Microsoft Excel. 100 | 101 | Make sure that there are no empty rows or extra information outside the main data. And that you don't have columns with the same name, or columns with no useful information. 102 | 103 | You should have a number of columns and rows, looking something like that: 104 | 105 | .. list-table:: Example antibodies dataset 106 | :header-rows: 1 107 | 108 | * - Name 109 | - Host 110 | - Target 111 | - Reference 112 | - Seller 113 | - Storage 114 | * - Anti α-actin 115 | - Mouse 116 | - Human 117 | - AB3148 118 | - Abcam 119 | - -20°C 120 | * - Anti γ-tubulin 121 | - Rabbit 122 | - Human 123 | - AB1337 124 | - Abcam 125 | - +4°C 126 | 127 | 128 | Now you need to have a column named **title**. This is the column that will be picked up as the title of the eLabFTW entry once imported. This column doesn't necessarily needs to be the first one, but it needs to be there. Here we're going to change the "Name" column. So now it looks like this: 129 | 130 | 131 | .. list-table:: Example antibodies dataset modified 132 | :header-rows: 1 133 | 134 | * - title 135 | - Host 136 | - Target 137 | - Reference 138 | - Seller 139 | - Storage 140 | * - Anti α-actin 141 | - Mouse 142 | - Human 143 | - AB3148 144 | - Abcam 145 | - -20°C 146 | * - Anti γ-tubulin 147 | - Rabbit 148 | - Human 149 | - AB1337 150 | - Abcam 151 | - +4°C 152 | 153 | 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. 154 | 155 | 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. 156 | 157 | 2. Importing the file 158 | ^^^^^^^^^^^^^^^^^^^^^ 159 | 160 | Select "Import" from the main top right user menu. If you haven't done it already, create first a Resource Category that corresponds to your data type (or ask your Admin to do it). Here we will use an "Antibody" category as that's what we are importing. 161 | 162 | Start by selecting your `.csv` file. Options to select the type (Resource) and category (Antibody in our case) appear. Select the appropriate options and click "Import". 163 | 164 | In the import window, select the correct category (Antibody in this example). Then select the visibility. Now select your **test** CSV file (with a few rows only) and click the "Import" button. 165 | 166 | Every row will correspond to an entry in the correct category of Resources. All the columns (except title, tags, metadata, date, custom_id, and other picked up special columns) will be imported in the body of each entry. 167 | 168 | If the import looks good, you can now delete these newly imported items and import your complete file. 169 | 170 | Using the API to control how things are imported 171 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 172 | 173 | If you want to have complete control over the import process, you can use a few lines of python to do the import. 174 | 175 | .. warning:: **Important**: the scripts linked below will import automatically all the rows present in your CSV file. Try first with a few rows before importing everything, so you have a chance to correct errors easily! 176 | 177 | We will use the `elabapi-python` library to make things easy. See `installation instructions `_. 178 | 179 | You can then have a look at `this example to import CSV using the API and metadata/extra fields `_. 180 | 181 | .. _compounds-import: 182 | 183 | Importing compounds through CLI (csv file) 184 | ------------------------------------------ 185 | 186 | .. note:: This approach is only available to Sysadmins with shell access. 187 | 188 | If you're working with a large database of compounds, using the CLI is a more efficient approach. Display the help with: 189 | 190 | .. code-block:: bash 191 | 192 | docker exec -it elabftw bin/console import:compounds -h 193 | 194 | The file must be available inside the container at /elabftw/exports. Use the following to copy your file into the container: 195 | 196 | .. code-block:: bash 197 | 198 | docker cp your_compounds.csv elabftw:/elabftw/exports/ 199 | 200 | Figure out the Team ID by looking at the Teams tab from the Sysconfig panel, where the ID will be displayed next to the Team. Next, import your file with: 201 | 202 | .. code-block:: bash 203 | 204 | # import in team 2 and be verbose 205 | docker exec -it elabftw bin/console import:compounds -vv your_compounds.csv 2 206 | # import in team 25, force everything to be owned by user 5 and be extra verbose 207 | docker exec -it elabftw bin/console import:compounds -vvv your_compounds.csv 25 --userid 5 208 | 209 | Preparing the CSV file for import 210 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 211 | 212 | One thing to know, is that the import command has an option (``-p``) to match compounds with PubChem, through the CAS or PubChem CID. So a .csv file with a single column ``cas`` or ``pubchemcid`` is enough to import compounds in eLabFTW. 213 | 214 | When importing, there is an option to automatically create a Resource for each imported Compound. The Resource will be linked to the Compound, and its title will be the Compound name. For this, simply provide the Resource Category ID with the ``-c`` flag. 215 | 216 | To also import locations/containers with quantity and units, use columns: 217 | 218 | - ``location``: as a ``/`` separated value. For example: "Building C / Floor 2 / Chemistry room". Note that it is possible to specify another separator, which might be useful if your existing data is using another character than ``/``. 219 | - ``quantity``: this should be a number corresponding to the quantity stored at the location 220 | - ``unit``: this should be a value such as μg, mg, g, kg, mL, L 221 | 222 | Other columns such as ``inchi``, ``smiles``, ``molecularweight``, ``molecularformula`` will also match and be imported to the compound. The full list of columns matched is accessible `here `_. 223 | 224 | Once you have your CSV file ready, send it to your Sysadmin and let them know if it should be imported with PubChem and if you want to create Resources, too. 225 | 226 | Matching an existing database 227 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 228 | 229 | Maybe you already have a Resource Category: "Chemical compounds" for instance, with Compounds associated to a "CAS" extra field. And you'd like to import the already existing compounds in the Compounds table in eLab so they exist as proper compounds. 230 | 231 | To do that, the import should be done with the ``--match-with`` command option, which will match an existing Resource through its extra field value. For example: ``--match-with cas`` will import the compound and link it to the Resource where an extra field ``cas`` has the same value as the row from the column ``cas`` in the .csv. 232 | 233 | 234 | .. _exporting-data: 235 | 236 | Exporting data 237 | ============== 238 | 239 | Exporting through web interface 240 | ------------------------------- 241 | 242 | The Export tab from your Profile allows full export of all your data, in several formats. Click "Create new export" to configure how you want the data to be exported. A "File is not ready" entry will be displayed. Wait a few seconds and click "Refresh". Once you see a link to the file, you can click it and download the exported file. 243 | 244 | Very long exports will still be processed if you close your browser or navigate away. 245 | 246 | Note to Sysadmins: on a given instance, export jobs are processed only one at a time. Users can each keep only 6 exported files. They are stored in `exports` within the elabFTW root folder. The `exports` folder may be mapped to a path outside the container to prevent exceeding the disk usage quota of the container. 247 | This can be done by adding a corresponding entry to `/etc/elabftw.yml` beneath the existing mapping for the upload path. In the example below, the exports folder is mapped to `/var/elabftw/exports`. 248 | 249 | .. code:: yaml 250 | 251 | volumes: 252 | # this is where you will keep the uploaded files persistently 253 | # for Windows users it might look like this 254 | # - D:\Users\Nico\elab-data\web:/elabftw/uploads 255 | # host:container 256 | - /var/elabftw/web:/elabftw/uploads 257 | # mapping of exports folder 258 | - /var/elabftw/exports:/elabftw/exports 259 | 260 | Exporting through CLI 261 | --------------------- 262 | 263 | As a Sysadmin with shell access, you can export an entire team, which can be useful if that team migrates out of your instance for instance. Use `bin/console export:eln -h`. The only argument is the team ID that you wish to export. 264 | 265 | It will export everything into a .eln file, that you need to copy out of the container. This file can later be re-imported on another instance. 266 | 267 | Important note: Import/Export is only supported between instances of the same version, preferably the latest version! 268 | -------------------------------------------------------------------------------- /doc/index.rst: -------------------------------------------------------------------------------- 1 | .. elabftw documentation master file, created by 2 | sphinx-quickstart on Fri Jul 24 17:28:23 2015. 3 | 4 | ***************************************** 5 | Welcome to the documentation for eLabFTW! 6 | ***************************************** 7 | 8 | .. image:: img/elabftw-logo.png 9 | :align: center 10 | :alt: elabftw logo 11 | 12 | :Website: https://www.elabftw.net 13 | :Live demo: https://demo.elabftw.net 14 | 15 | ======================== 16 | 17 | How to use this site 18 | ==================== 19 | 20 | This website contains both the technical documentation for installation, configuration and maintenance of the application, and the user documentation. Look at the menu on the left and select where you want to go: 21 | 22 | .. image:: img/doc-info.png 23 | :align: center 24 | :alt: doc info 25 | 26 | ======================== 27 | 28 | Introduction 29 | ============ 30 | 31 | eLabFTW is a web application, running in a linux container and using a MySQL database to store data persistently. Once installed on a server, users can register an account and start using their electronic lab notebook. 32 | 33 | Several teams can be hosted on the same install. Ideally, it is installed at the institution/company level. But individual teams can install it for themselves, too. Or you can run it locally on your computer, though this is not advised. 34 | 35 | It is distributed through Docker images, ensuring portability and added security through containerization. See the :doc:`Docker documentation ` for more information about the containerization technology. 36 | 37 | If you're looking into what eLabFTW can do before installing it, you might be interested in the :doc:`list of features `. 38 | 39 | Start the installation 40 | ---------------------- 41 | 42 | See :doc:`this page ` to install it on your server. 43 | 44 | See :doc:`this page ` if you don't have access to a server already. 45 | 46 | Join the `chat room `_ if you want to ask a question or require help. 47 | 48 | .. image:: img/by-sa.png 49 | :align: center 50 | :alt: cc-by-sa 51 | 52 | 53 | .. toctree:: 54 | :caption: Installation 55 | 56 | install 57 | install-cloud 58 | install-nas 59 | install-nolinux 60 | addons 61 | 62 | .. toctree:: 63 | :caption: Usage 64 | 65 | generalities 66 | user-guide 67 | admin-guide 68 | sysadmin-guide 69 | import-export 70 | metadata 71 | api 72 | 73 | .. toctree:: 74 | :caption: Documentation 75 | 76 | backup 77 | how-to-update 78 | contributing 79 | faq 80 | features 81 | docker-doc 82 | upgrade-to-docker 83 | ldap 84 | saml 85 | debug 86 | 87 | .. toctree:: 88 | :caption: Miscellaneous 89 | 90 | thanks 91 | changelog 92 | -------------------------------------------------------------------------------- /doc/install-cloud.rst: -------------------------------------------------------------------------------- 1 | .. _install-cloud: 2 | 3 | ******************** 4 | Install in the cloud 5 | ******************** 6 | 7 | Introduction 8 | ============ 9 | 10 | If you do not wish to opt for the hosted solution (`PRO Hosting from Deltablot `_), you can install and manage your own eLabFTW instance on a Virtual Private Server (VPS). 11 | 12 | A VPS is a shared server which looks like a dedicated server to you. Meaning you get root level access and can do what you want with it. 13 | 14 | **Pros**: 15 | 16 | * you have complete control on your server and thus your data 17 | * it will only cost you the price of the server, which can be as low as 5$ a month + the domain name (a few $ per year) 18 | * you'll improve your GNU/Linux administrator skills and knowledge 19 | * on the same server you can install other software, like a wiki, a forge, a chat app, etc... 20 | * you can run your own fork with your customizations 21 | * you'll unleash your inner geek 22 | 23 | **Cons**: 24 | 25 | * if you mess up you can only blame yourself 26 | * you'll have to keep your instance updated and read the release notes 27 | * you'll have to manage your own backups (and test them!) 28 | * you'll be exposed to malicious actors trying to break into your server constantly 29 | * managing correctly a GNU/Linux server requires administration skills and knowledge 30 | * when you get hit by a ransomware malware, you'll realize your backups are encrypted too :/ 31 | 32 | Your eLabFTW installation will run in a `Docker `_ container. Learn more about eLabFTW in Docker :ref:`here `. 33 | 34 | If you don't have a domain name already, you can get one from `OVH `_, `Gandi `_, `1&1 `_ or any other domain name registrar. You can get one for half a dollar per year. It is required to have a domain name to run eLabFTW. 35 | 36 | .. note:: If you don't want to deal with server maintenance, TLS certificates renewal, backups and updates, have a look at `PRO Hosting from Deltablot `_ 37 | 38 | A note about backups 39 | ==================== 40 | 41 | **Making reliable backups is hard**. Even IT companies can get it wrong. See the *postmortem* of an `incident at Gitlab `_. It is a very interesting article, illustrating how even if you have several restoration options, they might all fail. And that was before ransomware malware was prevalent! Now if you don't have immutable snapshots on your filesystem where the backups live, you might have your backups encrypted too! 42 | 43 | The point I'm trying to make is that a lot of things can go wrong, and if you care about your data, it might be a good option to look into the `PRO Hosting offering `_ or let a professional systems administrator take care of it. 44 | 45 | Create your droplet 46 | =================== 47 | 48 | .. warning:: A proper subdomain is required. Subfolder install is not supported! 49 | 50 | * Create an account on `DigitalOcean `_. Use this referral link to have 100$ offered! 51 | 52 | * Alternatively, you can use `Vultr `_. Use this referral link to register an account! The rest of this tutorial is for DigitalOcean. 53 | 54 | .. image:: img/digitalocean.png 55 | :align: center 56 | :alt: digitalocean logo 57 | 58 | * Create a droplet with Docker (from the One-click Apps tab), select a size and a region. 59 | 60 | * Optional: enable backups (might be a good idea) 61 | 62 | * Optional but highly recommended: add your SSH key (`documentation `_) 63 | 64 | * Create the droplet (it takes less than a minute) 65 | 66 | * Copy the IP address 67 | 68 | * Go to the control panel of your domain name provider. Point your domain (or subdomain) to the IP address of your drop. It might take a bit of time for the DNS to propagate (a few hours). 69 | 70 | Install eLabFTW 71 | =============== 72 | 73 | * Open a terminal and connect to your new server: 74 | 75 | .. code-block:: bash 76 | 77 | ssh root@ 78 | 79 | * Follow the :ref:`steps for a normal install `. 80 | -------------------------------------------------------------------------------- /doc/install-nas.rst: -------------------------------------------------------------------------------- 1 | .. _install-nas: 2 | 3 | **************** 4 | Install on a NAS 5 | **************** 6 | 7 | .. image:: img/qnap.png 8 | :align: center 9 | :alt: qnap 10 | 11 | This page describes the installation of eLabFTW on a Qnap or Synology NAS. The procedure is slightly different than on a normal GNU/Linux server. 12 | 13 | The following instructions are for a Qnap NAS but if you have a Synology, it's not much different. 14 | 15 | .. note:: Here I'm using the command line but it is also completely possible to do it via the graphical interface 16 | 17 | Prerequisites 18 | ============= 19 | 20 | We will use the Docker container technology, so you need to install the Container Station app from the AppCenter. 21 | 22 | .. image:: img/container-app.png 23 | :align: center 24 | :alt: container-app 25 | 26 | Once it is installed, open it. It will create a /Container folder. Connect with SSH to the NAS and create subfolders for storing eLabFTW files: 27 | 28 | .. code-block:: bash 29 | 30 | cd /share/CACHEDEV1_DATA # path might be different on your system 31 | mkdir -p Container/elabftw/mysql 32 | mkdir Container/elabftw/web 33 | 34 | Get the config file 35 | =================== 36 | 37 | .. code-block:: bash 38 | 39 | cd /share/CACHEDEV1_DATA/Container/elabftw 40 | curl -so docker-compose.yml "https://get.elabftw.net/?config" 41 | 42 | Edit the config file 43 | ==================== 44 | 45 | To edit the file we just downloaded, you can use "vim" or just download it on your computer instead, edit it with your favorite text editor and upload it back. 46 | 47 | You need to edit the port binding of the elabftw container. So change '443:443' to '3148:443' of the "ports" section of the "web" service. 48 | 49 | You also need to edit the "volumes" bindings so that persistent files (MySQL database and uploaded files) are stored there. In the example below, the paths are relative because the "docker-compose.yml" file is in the folder where we expect to store the files, but you can also put an absolute path: 50 | 51 | .. image:: img/nas-1.png 52 | :align: center 53 | :alt: nas config 54 | 55 | .. image:: img/nas-2.png 56 | :align: center 57 | :alt: nas config 58 | 59 | Starting the containers 60 | ======================= 61 | 62 | .. code-block:: bash 63 | 64 | docker compose up -d 65 | 66 | Importing the database structure 67 | ================================ 68 | 69 | .. code-block:: bash 70 | 71 | docker exec -it elabftw bin/init db:install 72 | 73 | Replace "elabftw" in the command above by the name of the elabftw container if yours is different (for instance if you have several containers running with redis as session handler). You can check this with `elabctl status`. 74 | 75 | Accessing elabftw 76 | ================= 77 | 78 | Go to https://YOUR.NAS.IP:3148. You can should see the login page and you can go to the register page to create a sysadmin account. 79 | 80 | Post install 81 | ============ 82 | 83 | Don't forget to setup :ref:`backup `, and subscribe to `the newsletter `_! 84 | 85 | The next step is to read the :ref:`Sysadmin guide `. 86 | 87 | To update, you can do "docker compose pull" and "docker compose up -d". 88 | 89 | It's a good idea to subscribe to `the newsletter `_, to know when new releases are out (you can also see that from the Sysadmin panel). 90 | 91 | ~Thank you for using `eLabFTW `_ :) 92 | -------------------------------------------------------------------------------- /doc/install-nolinux.rst: -------------------------------------------------------------------------------- 1 | .. _install-nolinux: 2 | 3 | ************************* 4 | Install on Mac or Windows 5 | ************************* 6 | 7 | .. image:: img/macwin.jpg 8 | :align: center 9 | :alt: mac and windows 10 | 11 | Unsupported operating systems 12 | ============================= 13 | 14 | eLabFTW is a server software that runs in Docker containers on a GNU/Linux operating system. It is not to be installed on personal computers running Windows or MacOS. 15 | 16 | .. warning:: eLabFTW **MUST** be installed on a GNU/Linux server, not a personal computer. 17 | 18 | If you would like to run eLabFTW and don't have the resources to deploy an instance yourself, have a look at the `hosted offers by Deltablot `_. 19 | -------------------------------------------------------------------------------- /doc/install.rst: -------------------------------------------------------------------------------- 1 | .. _install: 2 | 3 | ***************************** 4 | Install on a GNU/Linux server 5 | ***************************** 6 | 7 | .. image:: img/gnulinux.png 8 | :align: center 9 | :alt: gnulinux 10 | 11 | These instructions will work for any of the GNU/Linux distribution with a containerization technology such as Docker, Podman or any other OCI-compliant runtimes. The documentation is focused on Docker. 12 | 13 | .. warning:: Only 64 bits distributions are supported. Do not try to install on a 32 bits operating system! 14 | 15 | .. image:: img/docker.png 16 | :align: right 17 | :alt: docker 18 | 19 | .. _normal-install: 20 | 21 | Prerequisites 22 | ============= 23 | 24 | You will need a GNU/Linux server. Because of the use of linux containerization technology, other operating systems (FreeBSD, OpenBSD, and others) are not supported. 25 | 26 | If you do not have a server, look at the documentation to rent one: :ref:`Install in the cloud ` or opt for a managed (SaaS) solution via `Deltablot PRO Hosting `_. 27 | 28 | Be aware that installing **eLabFTW** means it will need to be maintained, by regularly applying updates, configuring the backups properly, and hardening the host operating system. If you do not have GNU/Linux System Administration knowledge, it is recommended to consider the `SaaS offering `_. 29 | 30 | Dependencies 31 | ------------ 32 | 33 | Absolutely required dependencies 34 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 35 | A containerization technology such as `docker `_ or `podman `_. 36 | 37 | A **MySQL** service is already declared in the default configuration file, so you don't have to worry about installing **MySQL**. A container with **MySQL** will get created from the official **MySQL** docker image. Do **NOT** install ``mysql-server`` package. 38 | 39 | Alternatively, you can use another pre-existing **MySQL** service on your network. Important, it must be **MySQL**, **not MariaDB**. If you do that, make sure to comment out/remove the ``mysql`` container from the `docker compose` configuration file. 40 | 41 | The following MySQL modes are known to work fine with eLabFTW codebase: 42 | 43 | * `ERROR_FOR_DIVISION_BY_ZERO` 44 | * `IGNORE_SPACE` 45 | * `NO_ENGINE_SUBSTITUTION` 46 | * `NO_ZERO_DATE` 47 | * `NO_ZERO_IN_DATE` 48 | * `ONLY_FULL_GROUP_BY` 49 | * `PIPES_AS_CONCAT` 50 | * `REAL_AS_FLOAT` 51 | * `STRICT_ALL_TABLES` 52 | 53 | Strongly recommended dependencies 54 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 55 | * `curl `_, to get files from command line (very likely already installed) 56 | * `docker compose plugin `_, the tool to orchestrate containers, required by `elabctl`. It can be installed with the `docker-compose-plugin` package. 57 | * `dialog `_, required by `elabctl install` 58 | * `borgbackup `_, a backup tool required by `elabctl backup`. Not required during installation. 59 | 60 | Notes 61 | ----- 62 | You can have your normal user in the `docker` group to execute docker commands without sudo (see `documentation `_). This is generally convenient for development environments and not recommended in production. 63 | 64 | **Ubuntu users**: Docker as a snap is known to cause issues. Uninstall that and install it without snap. See `this issue `_. 65 | 66 | Configure eLabFTW 67 | ================= 68 | 69 | .. warning:: A proper subdomain is required! 70 | 71 | We will install ``elabctl``, a tool to help you manage the elabftw installation. It is not required to install it but it is quite handy so it is recommended (also it's just a bash script, nothing fancy). If you you do not wish to use ``elabctl`` and just want a YAML config to edit, see instructions below for advanced users. 72 | 73 | 74 | With elabctl (recommended) 75 | -------------------------- 76 | 77 | .. code-block:: bash 78 | 79 | # get the program (a bash script) and make it executable 80 | curl -sL https://get.elabftw.net -o elabctl && chmod +x elabctl 81 | # add it to a directory in your $PATH 82 | sudo mv elabctl /usr/local/bin/ 83 | 84 | * Pre-fill the configuration file: 85 | 86 | .. code-block:: bash 87 | 88 | elabctl install 89 | 90 | * Edit the configuration file (``/etc/elabftw.yml`` by default): 91 | 92 | Edit the YAML configuration to suit your server setup. For instance, you might want to change the port binding (default is 443 but it might be already used by a traditional webserver). See below for using the container with a reverse proxy. 93 | 94 | Note about TLS certificates 95 | --------------------------- 96 | 97 | The eLabFTW container can run an HTTP or HTTPS server. Both will run internally on port 443. 98 | 99 | Option A: HTTP mode 100 | ^^^^^^^^^^^^^^^^^^^ 101 | 102 | You can run the container in HTTP mode (internal port 443) only if you have a reverse proxy in front doing TLS termination and sending X-Forwarded-Proto header. 103 | 104 | * Set ``DISABLE_HTTPS=true``. 105 | 106 | Reverse proxy configurations examples can be found `here `_. 107 | 108 | Option B: HTTPS mode with Let's Encrypt certificates 109 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 110 | 111 | In order to request Let's Encrypt certificates, you need to install ``certbot`` and have your server publicly accessible. See `official Let's Encrypt documentation `_ for your system. When requesting a new certificate, make sure that port 80 is open (and also port 443 for eLabFTW if it is the one you want to use). Once certbot is installed, the command to use might look like this: `certbot certonly \--standalone -d elab.example.org`. 112 | 113 | * Set ``DISABLE_HTTPS=false``. 114 | * Set ``ENABLE_LETSENCRYPT=true``. 115 | * Uncomment the line `- /etc/letsencrypt:/ssl` in the `volumes:` part of the yml config file. 116 | 117 | Option C: HTTPS mode with custom certificates 118 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 119 | 120 | Have the private key and certificate in PEM format in the folder ``/etc/letsencrypt/live/SERVER_NAME/`` where ``SERVER_NAME`` matches the ``SERVER_NAME`` configuration variable. The files need to be named `fullchain.pem` and `privkey.pem`. The webserver in the container expects TLS certificates to be in a particular order and format. Make sure that your `fullchain.pem` file contains certificates in this order: , with PEM encoding. 121 | 122 | * Set ``DISABLE_HTTPS=false``. 123 | * Set ``ENABLE_LETSENCRYPT=true``. 124 | * Uncomment the line `- /etc/letsencrypt:/ssl` in the `volumes:` part of the yml config file. 125 | 126 | 127 | Option D: HTTPS mode with self-signed certificate 128 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 129 | 130 | The container can generate its own certificate. Only use this if you have no other choice, as users will see a warning that the certificate is invalid because it is self-signed. 131 | 132 | * Set ``DISABLE_HTTPS=false``. 133 | * Set ``ENABLE_LETSENCRYPT=false``. 134 | 135 | Using Apache, nginx, HAProxy or traefik as a reverse proxy 136 | ---------------------------------------------------------- 137 | 138 | Mandatory if you use Option A above (HTTP mode). All the documentation related to such configurations can be found `here `_. 139 | 140 | Start eLabFTW 141 | ------------- 142 | 143 | .. code-block:: bash 144 | 145 | elabctl start 146 | 147 | 148 | Without elabctl (advanced users) 149 | -------------------------------- 150 | 151 | Get the config with: 152 | 153 | .. code-block:: bash 154 | 155 | curl -so docker-compose.yml "https://get.elabftw.net/?config" 156 | 157 | Edit this file and ``docker compose up -d`` to launch the containers. 158 | 159 | Initialize your database 160 | ======================== 161 | 162 | * Import the database structure with: 163 | 164 | .. code-block:: bash 165 | 166 | elabctl initialize 167 | # same as: docker exec -it elabftw bin/init db:install 168 | 169 | Replace `elabftw` in the command above by the name of the elabftw container if yours is different (for instance if you have several containers running with redis as session handler). You can check this with ``elabctl status`` or ``docker ps``. 170 | 171 | Register a Sysadmin account 172 | =========================== 173 | 174 | Point your browser to **\https:///register.php** 175 | 176 | Post install 177 | ============ 178 | 179 | Don't forget to setup :ref:`backup `, and subscribe to `the newsletter `_! 180 | 181 | The next step is to read the :ref:`Sysadmin guide `. 182 | 183 | ENJOY! :D 184 | 185 | Advanced configurations 186 | ======================= 187 | 188 | Inserting locally trusted root Certificate Authority 189 | ---------------------------------------------------- 190 | 191 | If you need the eLabFTW container to trust your own CA, you will need to create a custom image and run that instead of the official image. 192 | 193 | For this, create a folder, and in that folder, create a ``Dockerfile`` with this content: 194 | 195 | .. code-block:: bash 196 | 197 | # Example Dockerfile to include custom trusted Certificate Authority 198 | # we use the "stable" tag so this always work and needs no editing between versions 199 | FROM elabftw/elabimg:stable 200 | # in this example, the file is named "my-cert.pem" and must be present in the same folder is this Dockerfile 201 | # we copy it into this folder so it can be picked up by the following command 202 | COPY my-cert.pem /usr/local/share/ca-certificates/my-cert.crt 203 | RUN update-ca-certificates 204 | 205 | Make sure to have your CA cert in the same folder, named ``my-cert.pem``, and build the image: 206 | 207 | .. code-block:: bash 208 | 209 | docker buildx build -t elabftw/elabimg-custom . 210 | 211 | And replace the image name (`elabftw/elabimg`) in the main elabftw configuration YAML file (`/etc/elabftw.yml` by default) with your custom image name (`elabftw/elabimg-custom`). 212 | 213 | Changing the userid/groupid of uploaded files 214 | --------------------------------------------- 215 | 216 | By default, the container will run `nginx` user with uid:gid 101:101. As a result, user-uploaded files will be saved on the host with this ownership. 217 | 218 | If you prefer to have a dedicated or specific user own the uploaded files (for instance, an ``elabftw`` user), you can configure the user and group to be created in the container when it starts. Refer to the section near ``ELABFTW_USER`` in the configuration file for more details. 219 | -------------------------------------------------------------------------------- /doc/ldap.rst: -------------------------------------------------------------------------------- 1 | .. _ldap: 2 | 3 | ***************************** 4 | Configure LDAP authentication 5 | ***************************** 6 | 7 | This page describes the configuration of LDAP authentication for an eLabFTW instance. 8 | 9 | .. image:: img/auth.png 10 | :align: center 11 | :alt: authentication 12 | 13 | | 14 | 15 | Introduction 16 | ============ 17 | 18 | It is possible to configure your LDAP instance to authenticate users through an LDAP service. Various settings are possible, to adapt to the different cases of LDAP servers. 19 | 20 | How does eLabFTW query LDAP servers? 21 | ==================================== 22 | 23 | The overall schematic for each query with the options set in the sysadmin menu looks like this: 24 | 25 | 1. Connect to the LDAP server (-> TLS?, host, port) 26 | 2. Bind (login) with username and password, or anonymously (-> username, password) 27 | 3. Search for users within a certain region of the LDAP world directory (-> base DN) and extract certain properties/fields (-> filter attribute, team name, email, firstname, lastname) 28 | 4. Unbind (log out) 29 | 30 | For this to work, eLabFTW needs information from you, which is what the LDAP configuration options documented in the next section are for. 31 | 32 | Sysadmin LDAP settings 33 | ====================== 34 | 35 | The LDAP settings are found on the LDAP tab of the Sysconfig Panel. 36 | 37 | Toggle LDAP login 38 | ----------------- 39 | 40 | This is your general ON/OFF switch to toggle LDAP authentication from the login page. Note that if local login is left available, a radio button will allow users to select local/ldap login, and ldap will be selected by default. Generally, you'll want to disable local login once LDAP login is working (see setting for local login in first tab of sysconfig panel). 41 | 42 | LDAP Scheme 43 | ----------- 44 | 45 | This setting allows you to override the scheme (``ldap`` or ``ldaps``) used when connecting. This is because different LDAP implementations will require a different protocol depending on the use of TLS/StartTLS and the port. This setting is present to make sure we can cover all cases. 46 | 47 | LDAP Host 48 | --------- 49 | 50 | Enter the domain name or IP address of the LDAP server. 51 | This should **not** include the protocol or the port, *i.e.* not ``ldaps://my.ldap.server:636``, but only ``my.ldap.server``. 52 | For selecting the protocol and port, use the dedicated "LDAP Port" and "Use TLS" options. 53 | 54 | LDAP Port 55 | --------- 56 | 57 | The port the LDAP server listens on, `389` by default. 58 | Use port `636` for LDAPS or any custom port you might have configured. 59 | 60 | LDAP Base DN 61 | ------------ 62 | 63 | This is the "Distinguished Name" for the search, *i.e.* which part of the (global) LDAP tree you want to find the users in. 64 | It is probably something like ``dc=example,dc=org``, but might also include "Organizational Units", so something like ``ou=myinstitute,dc=example,dc=org``. 65 | Importantly, this is something completely different from the LDAP username, even though the notation might be similar. 66 | 67 | LDAP Username 68 | ------------- 69 | 70 | This is the DN or username that connects (binds) to the LDAP server. 71 | Examples include ``myuser`` or ``cn=AnAdminOf,ou=MyUnit,dc=example,dc=org``. 72 | The user must have permission to query other users. 73 | 74 | LDAP Password 75 | ------------- 76 | 77 | This password is needed for the authentication on the LDAP server with the username specified above. 78 | 79 | Use TLS 80 | ------- 81 | 82 | Select this if using LDAPS (= LDAP with TLS). 83 | 84 | By which LDAP attribute the user will be found 85 | ---------------------------------------------- 86 | 87 | This is the "filter attribute" from above. 88 | Common choices include ``cn``, ``uid`` and the default ``mail``. 89 | This is the LDAP field that holds the information you want users to enter into the "login" field on the start page. 90 | 91 | What attribute to look for the team name 92 | ---------------------------------------- 93 | 94 | The LDAP server will reply with the information associated with the user trying to authenticate. 95 | Which field will be the one used to determine the team in which to create the user? 96 | 97 | Create team sent by server if it doesn't exist already 98 | ------------------------------------------------------ 99 | 100 | If the team found doesn't exist already, do you want to create one? 101 | 102 | If no team attribute is found, to which team user is assigned? 103 | -------------------------------------------------------------- 104 | 105 | Use this to add users to this team by default. 106 | Useful if the LDAP server doesn't answer with a team attribute that can be used for eLabFTW. 107 | 108 | What attribute to look for ... 109 | ------------------------------ 110 | 111 | The last three fields are to specify the fields to look for for the user email, firstname and lastname. 112 | 113 | .. note:: 114 | 115 | If you encounter difficulties, make sure to get a useful log message before opening an issue, :doc:`see debug documentation `. 116 | 117 | 118 | Using a custom cert file 119 | ======================== 120 | 121 | When authenticating with a LDAPS server, a custom certfile might be needed. 122 | It can easily be added by modifying the web/volumes part of ``elabftw.yml`` like so: 123 | 124 | .. code:: 125 | 126 | services: 127 | web: 128 | ... 129 | volumes: 130 | ... 131 | - /path/to/eLabFTW/certpath:/custom_certs 132 | - /path/to/eLabFTW/openldap:/etc/openldap 133 | ... 134 | ... 135 | 136 | Then, add your custom cert file to ``/path/to/eLabFTW/certpath`` and at ``/path/to/eLabFTW/openldap/`` add a new file ``ldap.conf`` with the content 137 | 138 | .. code:: 139 | 140 | TLS_CACERT /custom_certs/.pem 141 | TLS_REQCERT hard 142 | 143 | where you substitute ```` for the name of the cert file for authenticating against the LDAP server. 144 | This informs ``openldap`` of the cert file and instructs it to always require a valid certificate from servers. 145 | 146 | After (re)starting using ``elabctl restart``, the LDAP server should now be reachable from inside the container. 147 | You can check this via searching for a known user (like yourself?) via 148 | 149 | .. code:: 150 | 151 | docker exec elabftw bash -c "apk add openldap openldap-back-mdb openldap-clients && \ 152 | ldapsearch -v -LLL \ 153 | -H 'ldaps://' \ 154 | -b '' \ 155 | -D '' \ 156 | -w '' \ 157 | ''" 158 | 159 | where you might need to use ``sudo docker`` if you are not ``root``. 160 | Be sure to substitute the ``<...>`` fields with your values. 161 | The command above installs the needed ``openldap`` packages in the ``elabftw`` container using Alpine Linux's package manager ``apk`` and then launches a ldap search query. 162 | ```` can for example be ``cn=MyOwnName``, or ``uid=5``. 163 | If trying to connect to a LDAP server that listens on a port other than 636, specify it like ``-H 'ldaps://:'``. 164 | 165 | For more information on the ``ldapsearch`` command, consider 166 | 167 | .. code:: 168 | 169 | docker exec elabftw ldapsearch --help 170 | 171 | after installing the ``openldap`` packages. 172 | -------------------------------------------------------------------------------- /doc/metadata.rst: -------------------------------------------------------------------------------- 1 | .. _metadata: 2 | 3 | ******** 4 | Metadata 5 | ******** 6 | 7 | This page describes the usage of the metadata JSON field attached to experiments or items (and their templates). 8 | 9 | Description 10 | =========== 11 | 12 | Since eLabFTW 4.0.0, you can add custom JSON data to your entries, using the `metadata` attribute. You can add arbitrary JSON, or use specific keys to extend the customization of the entry, for instance by adding extra fields. Experiments, Items and their templates all have this attribute. 13 | 14 | Getting started 15 | =============== 16 | 17 | Let's try it on an Experiment. Create a new experiment, and scroll down (in edit mode) to the "Extra fields" part. 18 | 19 | Click "Add field", a modal window will appear. 20 | 21 | .. image:: img/extra-field-builder.png 22 | :align: center 23 | :alt: Extra field builder 24 | 25 | If you want your new inputs to appear in groups, you can click the + button next to "Group" to add a new group. Or select an existing group from the dropdown menu. 26 | 27 | Then you can select which type of input you want for your extra field. You are free to add as many as you want, of different types. It is most useful to define them in the Templates, so when creating an entry, all the required inputs are already present. 28 | 29 | 30 | Example with dropdown menu 31 | -------------------------- 32 | 33 | Let's select "Dropdown menu" for our example. Enter a name for this input, optionally a description and at least 2 entries to select from. 34 | 35 | .. image:: img/extra-fields-dropdown.png 36 | :align: center 37 | :alt: Extra field dropdown 38 | 39 | Then click save and the new input (extra field) will appear right under the "Save" and "Save and go back" buttons: 40 | 41 | .. image:: img/extra-fields-view.png 42 | :align: center 43 | :alt: Extra field view 44 | 45 | Example with number and units 46 | ----------------------------- 47 | 48 | In our second example, we will add an input of type `number` with several choices for the units. This is how it looks like: 49 | 50 | 51 | .. image:: img/extra-fields-number.png 52 | :align: center 53 | :alt: Extra field number 54 | 55 | Then click save and the generated input will accept only numbers, and a dropdown menu with a list of available units will be appended to the input: 56 | 57 | .. image:: img/extra-fields-number-view.png 58 | :align: center 59 | :alt: Extra field number view 60 | 61 | Advanced use 62 | ============ 63 | 64 | Keep in mind that what the builder menu will do for you is simply create some JSON code and store it in the `metadata` attribute of the entry. You are free to edit this JSON code from the editor. 65 | 66 | .. image:: img/json-editor-mode.png 67 | :align: center 68 | :alt: json-editor-mode 69 | 70 | Positions 71 | --------- 72 | In order to assign a particular position to the inputs, use the `position` key, with a number as value. The inputs will then be ordered based on this value. Lowest value being on top. Groups are shown in the position they are defined. 73 | 74 | Removing an input 75 | ----------------- 76 | If you wish to remove an input, click the trash icon present in edit mode on the right side of the input block. 77 | 78 | Masking the main text 79 | --------------------- 80 | It is possible to hide the main text input by toggling the "Display main text" in the JSON Editor section. 81 | 82 | This will result in the presence of a special attribute: `display_main_text` with a value of `false` in the `elabftw` key: 83 | 84 | 85 | .. code:: javascript 86 | 87 | { 88 | "extra_fields": { 89 | ... 90 | }, 91 | "elabftw": { 92 | "display_main_text": false 93 | } 94 | } 95 | 96 | 97 | Example code 98 | ============ 99 | 100 | This will allow you to copy/paste easily the following code block into the editor (once the editor's mode is set to "Code"): 101 | 102 | .. code:: javascript 103 | 104 | { 105 | "extra_fields": { 106 | "End date": { 107 | "type": "date", 108 | "value": "2021-06-09", 109 | "position": 1 110 | }, 111 | "Magnification": { 112 | "type": "select", 113 | "value": "20X", 114 | "options": [ 115 | "10X", 116 | "20X", 117 | "40X" 118 | ], 119 | "position": 2 120 | }, 121 | "Pressure (Pa)": { 122 | "type": "number", 123 | "value": "12", 124 | "position": 3, 125 | "blank_value_on_duplicate": true 126 | }, 127 | "Wavelength (nm)": { 128 | "type": "radio", 129 | "position": 4, 130 | "value": "405", 131 | "options": [ 132 | "488", 133 | "405", 134 | "647" 135 | ] 136 | } 137 | } 138 | } 139 | 140 | Now click Save and scroll up a bit. Above the Steps you should now see four new inputs under the "Extra fields" header. When they are modified, the change is saved immediately. 141 | 142 | 143 | .. image:: img/extra-fields.png 144 | :align: center 145 | :alt: extra-fields 146 | 147 | Usage example 148 | ============= 149 | 150 | Have a "Status" and "Quantity" for some items in your database: 151 | 152 | .. code:: javascript 153 | 154 | { 155 | "extra_fields": { 156 | "Status": { 157 | "type": "select", 158 | "value": "In use", 159 | "options": [ 160 | "Not opened", 161 | "In use", 162 | "Need reorder", 163 | "Out of stock" 164 | ], 165 | "position": 2 166 | }, 167 | "Quantity": { 168 | "type": "number", 169 | "value": "12", 170 | "position": 1 171 | } 172 | } 173 | } 174 | 175 | 176 | This will produce the following inputs: 177 | 178 | .. image:: img/metadata-example.png 179 | :align: center 180 | :alt: metadata-example 181 | 182 | And if you're looking for all entries that have the status "Need reorder" you can do so from the search page! 183 | 184 | Schema description 185 | ================== 186 | 187 | In order to be processed by eLabFTW, the JSON contained in `metadata` must be in a particular format. It looks like this: 188 | 189 | .. code:: javascript 190 | 191 | { 192 | "extra_fields": { 193 | "Some extra field name": { 194 | "type": "date", 195 | "value": "2023-06-23", 196 | ... 197 | } 198 | }, 199 | "elabftw" { 200 | "display_main_text": false, 201 | "extra_fields_groups": [ 202 | { "id": 1, "name": "Some group" }, 203 | { "id": 2, "name": "Another group" }, 204 | ] 205 | } 206 | } 207 | 208 | In the `extra_fields` key object, you'll find all the extra fields. The name is the object key, and then it contains properties (described below). 209 | 210 | The `elabftw` key is a special key to hold the groups or if we want to display the main text. 211 | 212 | The rest will be ignored by eLabFTW, so you can have other things in there, too. 213 | 214 | Extra_fields objects 215 | -------------------- 216 | 217 | Here is a list and description of the properties that `extra_fields` objects can have: 218 | 219 | value (required) 220 | ^^^^^^^^^^^^^^^^ 221 | The field that will hold the selected/input value. You can set a default value here or leave it empty. It is the only required attribute for an `extra_field`. 222 | 223 | type (optional) 224 | ^^^^^^^^^^^^^^^ 225 | checkbox 226 | """""""" 227 | A box to check. A Step might be a better option here. 228 | 229 | date 230 | """" 231 | A date input. 232 | 233 | datetime-local 234 | """""""""""""" 235 | A date and time input. 236 | 237 | email 238 | """"" 239 | An email input: only a valid email address will be accepted. 240 | 241 | number 242 | """""" 243 | A text input that only accepts a number as value. 244 | 245 | radio 246 | """"" 247 | A radio input similar to select but all options are immediately visible. 248 | 249 | select 250 | """""" 251 | A dropdown element with options to choose from. 252 | 253 | text 254 | """" 255 | The default value if omitted. Use it for a short text. 256 | 257 | time 258 | """" 259 | A time input. 260 | 261 | url 262 | """ 263 | A text input that only accepts a valid URL. In view mode, the link will be clickable. By default, the link will open in a new tab. Add `"open_in_current_tab" : true` to make it open in the current tab. 264 | 265 | options (for type = select) 266 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 267 | An array of string (`[]`) with different options for the dropdown element. 268 | 269 | allow_multi_values (for type = select) 270 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 271 | A `boolean` attribute for allowing the selection of multiple values from the dropdown menu (which then becomes a multi select input). 272 | 273 | required 274 | ^^^^^^^^ 275 | A `boolean` attribute to indicate that filling this field is required. Please note that this won't prevent a user from leaving the page even if the value is empty. It will indicate visually that a value is required but won't block the workflow. 276 | 277 | description 278 | ^^^^^^^^^^^ 279 | A `string` attribute that will be displayed under the name of the field. 280 | 281 | units (for type = number) 282 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 283 | An array (`[]`) with different units for the units dropdown element. Requires a `unit` attribute to store the selected unit. 284 | 285 | unit 286 | ^^^^ 287 | An attribute used to store the selected unit, will be updated with a change from the `units` generated dropdown menu. 288 | 289 | position 290 | ^^^^^^^^ 291 | Add a number as a value to correctly order the extra fields how you want them. 292 | 293 | blank_value_on_duplicate 294 | ^^^^^^^^^^^^^^^^^^^^^^^^ 295 | Set to `true` for the value to be blanked when the entity is duplicated. 296 | 297 | group_id 298 | ^^^^^^^^ 299 | A number corresponding to the `id` of a group defined in the `elabftw.extra_fields_groups` object. Groups are defined as an array of objects with `id` and `name` properties. 300 | 301 | elabftw object 302 | -------------- 303 | 304 | Another object, with key `elabftw` is used to define some parameters. 305 | 306 | display_main_text 307 | ^^^^^^^^^^^^^^^^^ 308 | A boolean value indicating if we want to display the main text. 309 | 310 | extra_fields_groups 311 | ^^^^^^^^^^^^^^^^^^^ 312 | An array of objects that have an `id` and `name` and corresponds to groups. 313 | -------------------------------------------------------------------------------- /doc/saml.rst: -------------------------------------------------------------------------------- 1 | .. _saml: 2 | 3 | ****************************** 4 | Configure SAML2 authentication 5 | ****************************** 6 | 7 | .. image:: img/auth.png 8 | :align: center 9 | :alt: authentication 10 | 11 | This page describes the steps necessary to setup SAML2 authentication on eLabFTW with an IDentity Provider (IDP). It assumes that you already know what we're talking about. 12 | 13 | The IDP can lookup identity on an LDAP directory and deal with two factors authentication. 14 | 15 | Setup the Service Provider 16 | ========================== 17 | 18 | The service provider is the elabftw install. Head to the Sysadmin panel, click the SAML tab. 19 | 20 | * Debug mode: Set to "No". We don't want to print errors 21 | * Strict mode: Set to "Yes". Otherwise the mechanism is not secure 22 | * Base url: Where did you install elabftw? Example: https://elabftw.example.edu 23 | * entityId: The same as base URL 24 | * SAML protocol binding: basically it can be POST or HTTP-redirect. Depending on your IDP, set the correct value here 25 | * Single Logout Service: The same as entityId 26 | * Single Logout Service protocol binding: basically it can be POST or HTTP-redirect. Depending on your IDP, set the correct value here 27 | * NameIDFormat: match the supported NameIDFormat of the IDP, eLabFTW doesn't use this but it needs to be specified most of the time. Example values: 28 | 29 | - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress [default] 30 | - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent 31 | - urn:oasis:names:tc:SAML:2.0:nameid-format:transient 32 | - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified 33 | 34 | * x509 certificate: Generate a self-signed certificate and export it in PEM 35 | * Private key: the private key corresponding to the certificate 36 | * Rollover x509 certificate: Used when the x509 certificate is expiring. Can be set to a new certificate to publish in metadata. 37 | 38 | To generate a certificate, you can use this command: 39 | 40 | .. code-block:: bash 41 | 42 | openssl req -newkey rsa:2048 -nodes -keyout private.key -x509 -days 9999 -out cert.crt 43 | 44 | Use the content of `private.key` and `cert.crt`. 45 | 46 | Alternatively you can use `this site `_ to generate a self-signed certificate. 47 | 48 | Setup the IDentity Provider 49 | =========================== 50 | 51 | * Name: Visible to the user logging in. Example: "Institut Curie" 52 | * entityId: Example: https://idp1.agroparistech.fr/shibboleth 53 | * SSO url: Single Sign On URL 54 | * SSO binding: Example: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 55 | * SLO url: Single Log Out URL 56 | * SLO binding: Example: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 57 | * x509 cert: the public key of the IDP 58 | 59 | The SLO URL that the IDP needs to know to redirect the user to would be `/app/logout.php`. 60 | 61 | Attributes for the IDP 62 | ---------------------- 63 | We need to specify where to look in the attributes sent in the response for email, team and name of the user. You can use the FriendlyName or the Name from the table below. Note that this will depend on your IDP and using the SAML Tracer plugin (see below) to see the response will be helpful in determining what fields you want to use. 64 | 65 | .. list-table:: SAML attributes 66 | :widths: 25 25 25 25 67 | :header-rows: 1 68 | 69 | * - Attribute 70 | - FriendlyName 71 | - Name 72 | - Required 73 | * - Email 74 | - mail 75 | - urn:oid:0.9.2342.19200300.100.1.3 76 | - Yes 77 | * - Firstname 78 | - givenName 79 | - urn:oid:2.5.4.42 80 | - No 81 | * - Lastname 82 | - sn 83 | - urn:oid:2.5.4.4 84 | - No 85 | * - Userid (internal ID) 86 | - uid 87 | - urn:oid:0.9.2342.19200300.100.1.1 88 | - No 89 | 90 | If you cannot have information about the team, or do not wish to use it, make sure to have the setting "Let user select a team" when the user is created during first login. 91 | 92 | Note that the metadata.xml file (accessible at `/metadata.php`) will contain a section informing the IDP of the requested attributes. 93 | 94 | About the Userid / Internal ID 95 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 96 | 97 | If you configure the ``uid`` (Userid/Internal ID) parameter for an IDP, the value will be read from the SAML assertion and: 98 | 99 | - for user creation on the fly, the ``orgid`` (Organization ID) field of the user will contain the value of the ``uid`` attribute 100 | - for an existing user logging in, the ``orgid`` will not be modified 101 | 102 | If you enable "Fallback to internal id if existing user cannot be matched with email", then the ``uid`` will be used to try and match an existing user if, during login, the match could not be done on the ``email`` field (user changed email for instance). You can then chose to enable "If user is matched with internal id, update the email sent by IDP?" so that the email sent by the IDP is updated in the local database. 103 | 104 | Disable local login/register 105 | ============================ 106 | 107 | Go to the Server tab of the Sysadmin panel. From there you can disable local login (to force SAML auth) and also disable local registration. 108 | 109 | How does it work? 110 | ================= 111 | 112 | When a user successfully logins to the IDP, the email address is looked up. If it doesn't exist, the user is created. If the team doesn't exist either, it is created on the fly. You can configure this behavior from the Sysconfig panel. 113 | 114 | Debugging 115 | ========= 116 | 117 | SAML configuration can be tricky. I recommend that you use the SAML-tracer addon to see the requests and be able to verify what is sent and received. 118 | 119 | * `link to addon for Firefox `_ 120 | * `link to addon for Chrome `_ 121 | 122 | Looking at the PHP logs will also be helpful to get the complete error message. 123 | -------------------------------------------------------------------------------- /doc/thanks.rst: -------------------------------------------------------------------------------- 1 | .. _thanks: 2 | :title: Acknowledgements 3 | 4 | **************** 5 | Acknowledgements 6 | **************** 7 | 8 | A big thanks to early alpha testers and everyone who contributed through their ideas or 9 | suggestions to this project. 10 | 11 | Über thanks to the patrons from `Liberapay `_! 12 | 13 | Special thanks for the contributors on internationalization. There are more than 40 translators for the project :) 14 | 15 | eLabFTW uses open source code from others. A big thanks to them for making their code available! 16 | 17 | Look in `composer.json` and `package.json` to get a list of the dependencies. 18 | 19 | Other resources 20 | 21 | * `StackOverflow `_ probably the best site ever for any programmer 22 | * `SomaFM `_ especially DEF CON Radio 23 | * `Vim `_ 24 | -------------------------------------------------------------------------------- /doc/upgrade-to-docker.rst: -------------------------------------------------------------------------------- 1 | .. _upgrade-to-docker: 2 | 3 | ******************************************** 4 | Upgrade a normal install to a Docker install 5 | ******************************************** 6 | 7 | .. image:: img/docker.png 8 | :align: center 9 | :alt: docker 10 | 11 | Description 12 | =========== 13 | 14 | This guide is aimed at (GNU/Linux) users who have installed eLabFTW the old school way (git clone or zip archive) and want to benefit from Docker. 15 | If you are not familiar with Docker, take the time to read the documentation on the Docker website. And read also the :ref:`in-depth documentation for eLabFTW with Docker `. 16 | 17 | Preparation 18 | =========== 19 | 20 | Install Docker 21 | -------------- 22 | We will obviously need to `install Docker `_. 23 | 24 | Once this is done try a: 25 | 26 | .. code-block:: bash 27 | 28 | docker run hello-world 29 | 30 | If everything works, you should see a little message explaining what Docker did to print this message. 31 | 32 | Install elabftw normally 33 | ------------------------ 34 | Follow the steps described :ref:`here `, except the last one. Do not start the containers. 35 | 36 | Export current install 37 | ---------------------- 38 | Before going further, make sure you have backups of the existing installation. Read how to backup :ref:`here `. 39 | 40 | You should have a `dump.sql` file of the elabftw database. And your `uploads` folder is copied somewhere safe. 41 | 42 | Installation 43 | ============ 44 | 45 | You now have a configuration file `/etc/elabftw.yml`. Edit it with your favorite editor. 46 | 47 | Editing the config file 48 | ----------------------- 49 | * Open the `config.php` file located in your `elabftw` folder of the current install 50 | * Copy the SECRET_KEY value from the `config.php` file to `/etc/elabftw.yml` file 51 | * If your webserver (Apache, nginx) is only serving eLabFTW, turn it off now and also make sure it won't start after reboot. 52 | 53 | If you are using your webserver for something else, change the "ports:" value from "443:443" to "8080:443" or "444:443" or "9000:443" because your current server is already using port 443. 54 | 55 | Now, either you open a port on your server's firewall to accept traffic on the new port you set, or you might also want to use your current webserver as a proxy and forward packets to the docker container: see :ref:`documentation for unusual setups `. 56 | 57 | * If you are running MySQL 5.5 or 5.6, edit the 5.7 in the `image: mysql:5.7` line to the appropriate version. You can upgrade later. 58 | 59 | Copy the uploaded files 60 | ----------------------- 61 | * Rename your `uploads` folder to `/var/elabftw/web`: 62 | 63 | .. code-block:: bash 64 | 65 | mkdir -p /var/elabftw/web 66 | cp -r /path/to/uploads/* /var/elabftw/web 67 | # fix permissions 68 | chown -R 101:101 /var/elabftw/web 69 | 70 | About HTTPS (SSL/TLS) 71 | --------------------- 72 | As you know, eLabFTW can only run with HTTPS. So if you were running it before, there are good chances that you already have a certificate. If it's a self-signed one, nothing needs to be done. The Docker image will generate a new certificate when the container is created. But your users will get a warning when they access the website, which is not ideal. 73 | 74 | One solution to this is to request a certificate from `Let's Encrypt `_. It's free and you get a real proper certificate. See the documentation on Let's Encrypt website on how to request a certificate for your website. You will need to have a domain name pointing to the server. It doesn't work if you only have an IP address or if the server is not accessible from outside a company's network. 75 | 76 | Another solution is to use the certificate you already have. 77 | 78 | * Change the value of ENABLE_LETSENCRYPT to true in `/etc/elabftw.yml` 79 | * Uncomment the line `#- /etc/letsencrypt:/ssl` (remove the leading #) 80 | * If your domain is `elabftw.example.com`, do this: 81 | 82 | .. code-block:: bash 83 | 84 | # as root 85 | mkdir -p /etc/letsencrypt/live/elabftw.example.com/ 86 | cp /path/to/your/current-cert.pem /etc/letsencrypt/live/elabftw.example.com/fullchain.pem 87 | cp /path/to/your/current-key.pem /etc/letsencrypt/live/elabftw.example.com/privkey.pem 88 | 89 | Another way to do this is to `git clone` the `docker-elabftw` repo and edit the `src/run.sh` script to point to the correct directory, but this will not be covered in this guide. 90 | 91 | Starting the containers 92 | ----------------------- 93 | .. code-block:: bash 94 | 95 | elabctl start 96 | 97 | This will create an empty database in `/var/elabftw/mysql`. But of course, what we want is to have our old database in there! To do that we will copy our `dump.sql` file to the `mysql` container and import it in place of the freshly created database (which is empty!). 98 | 99 | .. code-block:: bash 100 | 101 | docker cp dump.sql mysql:/ 102 | docker exec -it mysql bash 103 | mysql -uroot -p 104 | # here you type the password you put in MYSQL_ROOT_PASSWORD in the /etc/elabftw.yml file 105 | Mysql> drop database elabftw; 106 | Mysql> create database elabftw character set utf8mb4 collate utf8mb4_0900_ai_ci; 107 | Mysql> use elabftw; 108 | Mysql> source dump.sql; 109 | Mysql> exit; 110 | 111 | You should now have your old database running. If you were upgrading from an old version, make sure to read the release note of each version. Specifically the 1.2.1 one where there is a manual step to copy the new SECRET_KEY to `/etc/elabftw.yml`. 112 | 113 | Test everything is working by clicking everything. Report any problem in the present documentation so it can be improved. 114 | 115 | As always, if you need help, open a github issue :) 116 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==8.1.3 2 | sphinx_rtd_theme==3.0.2 3 | sphinxcontrib-jquery 4 | --------------------------------------------------------------------------------