feat: add eLabFTW Cloudron package (Business-Apps) [#669]

Official-image wrapper of elabftw/elabimg 5.6.12 (tag+digest pinned); localstorage + mysql + ldap addons; httpPort 443 via DISABLE_HTTPS. No OIDC upstream -> native LDAP flagged auth-risk. First mysql-addon and first Business-Apps package; 15/~57. Build verified green under ukrrs-batch.slice. Docs synced (JOURNAL s15, README, STATUS). Detail + verification: https://projects.knownelement.com/issues/669#note-3938
2026-09-02 19:58:59 -05:00
parent 8a613b4f7d
commit 1cc0063e03
11 changed files with 366 additions and 11 deletions
@@ -0,0 +1,90 @@
+# eLabFTW — Cloudron Package
+
+[eLabFTW](https://www.elabftw.net/) is an open-source electronic lab
+notebook (ELN) and inventory manager for research teams: experiments with
+revisions, resources database, scheduler, MFA / API keys, timestamping and
+PDF export pipelines. Packaged as an **official-image wrapper** around the
+upstream `elabftw/elabimg:5.6.12` image (nginx + php-fpm + s6-overlay,
+digest pinned).
+
+- **Upstream:** https://github.com/elabftw/elabftw (AGPL-3.0)
+- **Ticket:** [#669](https://projects.knownelement.com/issues/669)
+- **Category:** Business-Apps · **Pattern:** official-image wrapper +
+  `start.sh` env mapping
+
+## Authentication (auth gate verdict: ⚠️ LDAP — auth-risk flag)
+
+eLabFTW 5.x auth methods are **local, SAML and LDAP — there is no OIDC
+support** (verified in `src/Enums/AuthMethod.php`; no OIDC client anywhere
+upstream). Per the AGENTS.md policy this package ships with the
+**LDAP path** and carries the auth-risk flag:
+
+1. The manifest enables the Cloudron **`ldap`** addon, so the container
+   holds `CLOUDRON_LDAP_*` credentials (inspect them with
+   `cloudron exec env | grep LDAP` in the app terminal).
+2. Log in once as the sysadmin account created during first-run setup.
+3. Open **Sysconfig → Server → LDAP** and map the panel to the Cloudron
+   directory:
+
+| eLabFTW LDAP panel | Cloudron value |
+|--------------------|----------------|
+| Toggle LDAP login | on |
+| Scheme | `ldap` |
+| Host | `CLOUDRON_LDAP_HOST` |
+| Port | `CLOUDRON_LDAP_PORT` (3002) |
+| Use TLS | off (plain LDAP on the box) |
+| Base DN | `CLOUDRON_LDAP_USERS_BASE_DN` |
+| Username (bind DN) | `CLOUDRON_LDAP_BIND_DN` |
+| Password | `CLOUDRON_LDAP_BIND_PASSWORD` |
+| Search attr | `mail` (or `username`) |
+| Email attribute | `mail` |
+| Firstname / Lastname | `givenname` / `sn` |
+
+**auth-risk: LDAP** — this must be validated on the live Cloudron before
+production use (see STATUS.md). SAML remains available as an alternative
+against an external IdP, but the Cloudron platform provider is OIDC-only,
+so LDAP is the only platform-integrated SSO path today.
+
+## Addons & ports
+
+| Concern | Cloudron wiring |
+|---------|-----------------|
+| Database | `mysql` addon → `DB_*` (schema auto-installed / auto-updated) |
+| Files | `localstorage`: `/app/data/uploads`, `/app/data/exports` |
+| SSO directory | `ldap` addon (`CLOUDRON_LDAP_*`, see above) |
+| Web | single HTTP port `443` (`DISABLE_HTTPS=true`; TLS at the proxy) |
+
+## Runtime layout
+
+- `start.sh` waits for MySQL, maps `CLOUDRON_MYSQL_*` → elabimg `DB_*`,
+  sets `SITE_URL` from `CLOUDRON_APP_ORIGIN`, and hands over to the
+  upstream s6 `/init`, which applies config and runs
+  `bin/init db:install` / `bin/console db:update` (`AUTO_DB_INIT` /
+  `AUTO_DB_UPDATE`).
+- The `SECRET_KEY` (encrypts SMTP / timestamping passwords) is generated
+  once and persisted at `/app/data/.secret_key` — hex, because the image
+  entrypoint injects it via unescaped `sed`.
+- First boot: open the app URL and complete the initial setup (create the
+  sysadmin + first team); afterwards do the LDAP wiring above.
+
+## Environment knobs (.env.example)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ELABFTW_TZ` | `UTC` | PHP / container timezone |
+| `ELABFTW_MAX_UPLOAD_SIZE` | `100M` | nginx + PHP upload limit |
+| `ELABFTW_PHP_MAX_CHILDREN` | `15` | php-fpm workers (tuned for 1536 MB) |
+| `ELABFTW_MAX_PHP_MEMORY` | `512M` | per-worker PHP memory limit |
+| `ELABFTW_AUTO_DB_INIT` | `true` | run `db:install` at boot |
+| `ELABFTW_AUTO_DB_UPDATE` | `true` | run `db:update` at boot |
+
+## Build & install
+
+```bash
+docker build --cgroup-parent ukrrs-batch.slice -t elabftw-cloudron:test \
+  Package-Workspace/Business-Apps/elabftw/
+```
+
+`cloudron build && cloudron install` on the Cloudron VPS for real
+deployment. First start waits for MySQL, installs the schema and serves
+the setup wizard on the app domain.