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 @@
+repo/
@@ -0,0 +1,19 @@
+# eLabFTW Cloudron package — optional runtime knobs.
+# Set with: cloudron env set ELABFTW_TZ=America/Chicago --app <app-id>
+# (then restart the app). Everything has a sane default; empty = unset.
+
+# PHP / container timezone (IANA name)
+ELABFTW_TZ=UTC
+
+# nginx + PHP upload limit (also raises client_max_body_size)
+ELABFTW_MAX_UPLOAD_SIZE=100M
+
+# php-fpm worker count (defaults tuned for the 1536 MB memory limit)
+ELABFTW_PHP_MAX_CHILDREN=15
+
+# per-worker PHP memory limit
+ELABFTW_MAX_PHP_MEMORY=512M
+
+# run `bin/init db:install` / `bin/console db:update` at boot
+ELABFTW_AUTO_DB_INIT=true
+ELABFTW_AUTO_DB_UPDATE=true
@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.0.0 — 2026-09-01
+
+Initial Cloudron package (eLabFTW 5.6.12, ticket
+[#669](https://projects.knownelement.com/issues/669)).
+
+- Official-image wrapper around `elabftw/elabimg:5.6.12` (digest
+  pinned); no additions to the runtime image.
+- `start.sh`: MySQL addon wait loop, `CLOUDRON_MYSQL_*` → `DB_*`
+  mapping, `SITE_URL` from `CLOUDRON_APP_ORIGIN`, plain-HTTP mode
+  (`DISABLE_HTTPS=true`, internal port 443), persistent `SECRET_KEY`
+  under `/app/data`, uploads/exports bound into the localstorage volume.
+- Schema lifecycle via upstream `AUTO_DB_INIT` / `AUTO_DB_UPDATE`
+  (runs after the DB wait in `start.sh`).
+- Auth: no OIDC upstream — `ldap` addon enabled and documented mapping
+  table for the sysconfig LDAP panel (**auth-risk: LDAP**); SAML
+  available for an external IdP.
+- Env knobs: `ELABFTW_TZ`, `ELABFTW_MAX_UPLOAD_SIZE`,
+  `ELABFTW_PHP_MAX_CHILDREN`, `ELABFTW_MAX_PHP_MEMORY`,
+  `ELABFTW_AUTO_DB_INIT`, `ELABFTW_AUTO_DB_UPDATE`.
@@ -0,0 +1,23 @@
+{
+  "manifestVersion": 2,
+  "type": "app",
+  "id": "io.cloudron.elabftw",
+  "title": "eLabFTW",
+  "description": "Open-source electronic lab notebook (ELN) and lab inventory manager for research teams: experiments, resources database, scheduling, digital signatures and timestamps, PDF/export pipelines. MySQL stores all state; uploads and exports persist in Cloudron localstorage. Auth note: eLabFTW has no OIDC support; single sign-on is provided via the Cloudron LDAP directory configured in the admin panel (auth-risk: LDAP).",
+  "author": "Nicolas CARPi / Deltablot",
+  "website": "https://www.elabftw.net/",
+  "contactEmail": "cloudron@tsys.dev",
+  "tagline": "Electronic lab notebook and inventory for research teams",
+  "version": "5.6.12",
+  "healthCheckPath": "/",
+  "httpPort": 443,
+  "memoryLimit": 1536,
+  "addons": {
+    "localstorage": true,
+    "mysql": {},
+    "ldap": {}
+  },
+  "mediaLinks": [],
+  "changelog": "Initial Cloudron package for eLabFTW 5.6.12 (official-image wrapper of elabftw, digest pinned). start.sh waits for the MySQL addon, maps CLOUDRON_MYSQL_* into elabimg DB_* variables, persists the SECRET_KEY under /app/data and binds uploads/exports into the localstorage volume; the schema is installed and updated automatically (AUTO_DB_INIT/AUTO_DB_UPDATE). Plain HTTP on the internal port via DISABLE_HTTPS (TLS terminates at the Cloudron proxy). No OIDC upstream: the ldap addon is enabled and the admin wires CLOUDRON_LDAP_* into Admin panel - LDAP (auth-risk flag); SAML also available for an external IdP.",
+  "icon": "file://logo.png"
+}
@@ -0,0 +1,40 @@
+# eLabFTW Cloudron Package
+#
+# eLabFTW is an open-source electronic lab notebook (ELN) for research
+# teams: experiments, inventory, scheduling, timestamps and PDF export,
+# backed by MySQL. Packaged as an official-image wrapper around the
+# upstream elabimg image (nginx + php-fpm + s6-overlay in one container).
+#
+# Upstream: https://github.com/elabftw/elabftw
+#   - The elabimg build lives in-tree (containers/elabimg/) but compiles
+#     nginx, OpenBabel and the whole yarn/composer asset pipeline from
+#     source; the published image is the supported distribution channel.
+#   - elabimg 5.6.12 with DISABLE_HTTPS=true serves plain HTTP on port
+#     443 (Cloudron terminates TLS at the platform proxy).
+#   - DB schema: AUTO_DB_INIT / AUTO_DB_UPDATE run `bin/init db:install`
+#     / `bin/console db:update` from the image entrypoint; start.sh
+#     gates them behind a MySQL wait loop.
+#
+# Authentication: NO OIDC upstream (v5.6 auth methods: local, SAML, LDAP).
+# Verdict per AGENTS.md: native LDAP = acceptable with auth-risk flag.
+# The manifest enables the `ldap` addon so CLOUDRON_LDAP_* credentials are
+# available; the sysconfig admin wires them into Admin panel -> LDAP (see
+# README). SAML is also available for an external IdP.
+#
+# Pattern: official-image wrapper. Image pinned by tag AND digest (amd64
+# manifest digest of the 5.6.12 tag, from the Docker Hub registry API).
+FROM elabftw/elabimg:5.6.12@sha256:e91fcc92f0c9a3190ac4f8db7fad03703f1662b33856a53baba9b5a06d71a51d
+
+# start.sh waits for the mysql addon, persists the SECRET_KEY, maps the
+# Cloudron env into elabimg's DB_*/SITE_URL/DISABLE_HTTPS variables,
+# binds uploads + exports under /app/data and execs the s6 init.
+# Made executable on the host, not at build time (Cloudron builds hit
+# permission errors on RUN chmod). bash ships with elabimg.
+COPY start.sh /app/start.sh
+
+# elabimg HTTP mode (DISABLE_HTTPS=true) listens here; no other listener.
+EXPOSE 443
+
+# s6-overlay must run as root: the upstream entrypoint creates the
+# unprivileged nginx/php user and drops privileges for the services.
+ENTRYPOINT ["/bin/bash", "/app/start.sh"]
@@ -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.
@@ -0,0 +1,80 @@
+#!/bin/bash
+set -euo pipefail
+
+# eLabFTW runtime setup for Cloudron:
+#   1. bind persistent storage: /elabftw/{uploads,exports} -> /app/data
+#   2. wait for the Cloudron mysql addon (the image entrypoint runs
+#      db:install / db:update immediately, without any DB wait)
+#   3. persist the SECRET_KEY (rotating it would lose the encrypted
+#      SMTP / timestamping passwords stored in the DB)
+#   4. map the Cloudron env into elabimg's runtime variables
+#   5. exec the upstream s6-overlay init (nginx + php-fpm + invoker +
+#      chronos), which applies the config and starts the web server
+#
+# Authentication: eLabFTW has NO OIDC support (auth methods: local, SAML,
+# LDAP). Cloudron SSO therefore goes through the platform LDAP directory:
+# the manifest enables the `ldap` addon and the sysconfig admin maps
+# CLOUDRON_LDAP_* into Admin panel -> LDAP (see package README). This is
+# flagged auth-risk: LDAP in STATUS.md / README.md.
+
+DATA_DIR="/app/data"
+SECRET_FILE="${DATA_DIR}/.secret_key"
+
+# --- 1. persistent uploads / exports -----------------------------------------
+mkdir -p "${DATA_DIR}/uploads" "${DATA_DIR}/exports"
+# replace the in-image directories with symlinks into the Cloudron volume;
+# the upstream entrypoint will chown/chmod them for the nginx user
+rm -rf /elabftw/uploads /elabftw/exports
+ln -sfn "${DATA_DIR}/uploads" /elabftw/uploads
+ln -sfn "${DATA_DIR}/exports" /elabftw/exports
+
+# --- 2. wait for the mysql addon ----------------------------------------------
+wait_tcp() {
+  local host="$1" port="$2" name="$3"
+  echo "Waiting for ${name} at ${host}:${port} ..."
+  until (exec 3<>"/dev/tcp/${host}/${port}") 2>/dev/null; do
+    echo "${name} is unavailable - sleeping"
+    sleep 2
+  done
+  echo "${name} is up"
+}
+
+wait_tcp "${CLOUDRON_MYSQL_HOST:-127.0.0.1}" "${CLOUDRON_MYSQL_PORT:-3306}" "MySQL"
+
+# --- 3. persistent SECRET_KEY --------------------------------------------------
+# hex on purpose: the image entrypoint substitutes it into the php-fpm pool
+# config with an unescaped `sed s/.../.../`, so the value must not contain
+# `/`, `&` or other sed metacharacters (base64 would break it).
+if [[ ! -s "${SECRET_FILE}" ]]; then
+  ( umask 077; openssl rand -hex 32 > "${SECRET_FILE}" )
+  echo "Generated new eLabFTW secret key"
+fi
+export SECRET_KEY="$(cat "${SECRET_FILE}")"
+
+# --- 4. Cloudron -> elabimg environment ----------------------------------------
+export DB_HOST="${CLOUDRON_MYSQL_HOST:-127.0.0.1}"
+export DB_PORT="${CLOUDRON_MYSQL_PORT:-3306}"
+export DB_NAME="${CLOUDRON_MYSQL_DATABASE:-elabftw}"
+export DB_USER="${CLOUDRON_MYSQL_USERNAME:-elabftw}"
+export DB_PASSWORD="${CLOUDRON_MYSQL_PASSWORD:-}"
+
+# Cloudron terminates TLS at the platform proxy; elabimg serves plain HTTP
+export DISABLE_HTTPS=true
+export SITE_URL="${CLOUDRON_APP_ORIGIN:-http://localhost}"
+export SERVER_NAME="${CLOUDRON_APP_DOMAIN:-localhost}"
+
+export TZ="${ELABFTW_TZ:-UTC}"
+export PHP_TIMEZONE="${ELABFTW_TZ:-UTC}"
+
+# schema lifecycle handled by the image entrypoint (runs after this script
+# hands over): db:install on first boot, db:update on every boot
+export AUTO_DB_INIT="${ELABFTW_AUTO_DB_INIT:-true}"
+export AUTO_DB_UPDATE="${ELABFTW_AUTO_DB_UPDATE:-true}"
+
+# resource knobs (defaults tuned for the 1536 MB manifest memory limit)
+export MAX_UPLOAD_SIZE="${ELABFTW_MAX_UPLOAD_SIZE:-100M}"
+export PHP_MAX_CHILDREN="${ELABFTW_PHP_MAX_CHILDREN:-15}"
+export MAX_PHP_MEMORY="${ELABFTW_MAX_PHP_MEMORY:-512M}"
+
+# --- 5. hand over to the upstream init ------------------------------------------
+exec /init