Skip to content

v2.3.0 — trusted-proxy hardening and in-place extension updates

Choose a tag to compare

@fmadore fmadore released this 13 Oct 09:34
· 102 commits to main since this release

Upgrading? Check two settings before you redeploy.

  1. Serving the site directly over HTTP, with no reverse proxy (NGINX_BIND=0.0.0.0)? Add this to .env:

    NGINX_TRUSTED_PROXY_CIDR=192.0.2.1/32

    That trusts no real peer, so no visitor can forge their address with an X-Forwarded-For header. Until you set it, the default (172.16.0.0/12) applies. The one-click installer already writes it for HTTP-only installs.

  2. Behind a reverse proxy on a custom 10.x or 192.168.x Docker network? Set NGINX_TRUSTED_PROXY_CIDR to that network, or better, the proxy's own address. Otherwise nginx ignores the proxy's X-Forwarded-For and X-Forwarded-Proto headers. The login rate limit then counts every visitor as one client, and Omeka generates http:// links. Proxies on Docker's default bridges need no change.

If you update modules with scripts/update-module.sh, switch to scripts/update-extensions.sh. On the default layout, modules and themes live on volumes. update-module.sh only rewrites the pins and rebuilds the images, which never reach those volumes, so the site would keep running the old versions.

Security

  • nginx trusts one proxy address you choose instead of every private network. v2.2.0 accepted forwarded client addresses from all of 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. The new NGINX_TRUSTED_PROXY_CIDR setting names the one address or network allowed to send them. X-Forwarded-Proto: https is honoured only from that proxy too.
  • PHP can run only through /index.php. Requests for .php, .phtml, .phar and numbered .php5-style files are refused, including path-info variants such as upload.php/photo.jpg.
  • Omeka's secret key can live in .env. Omeka encrypts stored secrets with a key it tries to write into config/, which is read-only here. That write always failed and left a warning on every admin page. Generate a value once with openssl rand -base64 32, set it as OMEKA_SECRET_KEY, and never change it.
  • The database now flushes every commit to disk (innodb-flush-log-at-trx-commit=1). A host crash can no longer lose the last second of edits.
  • The web container's tmpfs directories are root-owned 0755 instead of world-writable 1777.

Features

  • scripts/update-extensions.sh is the one command for updating modules and themes. It backs up first, moves every pinned release archive to its newest release, and refreshes the live volumes. It then applies pending module migrations. On volume-backed stacks it no longer rebuilds the images, since the volumes take precedence over them; pass --rebuild or --pull to rebuild anyway. --dry-run reports without changing anything.
  • Backup retention: backup.sh --keep N (or BACKUP_KEEP=N in .env) deletes older snapshots once the new one is complete and checksummed. Unfinished snapshots are never counted.
  • backup.sh --quiesce stops web and PHP for the backup's duration, so the database dump and media archive come from the same moment. They restart afterwards.
  • scripts/health-report.sh prints a read-only summary of every container: state, health, restarts, out-of-memory kills, and current CPU and memory use.
  • Resource limits are set in .env: PHP_CONTAINER_MEMORY, PHP_CPU_LIMIT, WEB_*, DB_* and SEARCH_*, for hosts larger or smaller than the defaults assume.
  • New guide for institutions: docs/INSTITUTION_SETUP.md covers adapting the template for your own institution.
  • Modules can be installed from their published release archives (a .zip URL in modules.txt or themes.txt). That gives a clean packaged copy instead of a git checkout of the module's development tree.

Fixes

  • nginx follows PHP to its new address. Recreating only the php container used to leave nginx on the old IP, and the site returned 502 until web was restarted too.
  • Updated extensions reach visitors immediately. Static files are now revalidated instead of cached for a year, and PHP re-reads changed code within two seconds. Admin-panel and command-line module updates take effect without a restart.
  • Backups are safer to rely on:
    • An interrupted backup is marked incomplete, and restore.sh refuses to restore it.
    • backup.sh refuses to write into a non-empty directory.
    • Volumes are found from the active Compose configuration, not guessed from the project name.
    • The Typesense search index is no longer archived, since a live copy of it is not a reliable snapshot. Rebuild the index from Omeka after a restore. restore.sh --restore-search still reads older archives that include it.
  • update-extensions.sh no longer downgrades pinned modules through the Omeka module registry. It also no longer unpacks duplicate copies of a module under differently cased folder names.
  • update-module.sh exits with an error when it cannot check a pinned archive. It reads only the manifests your active Compose configuration uses, not other institutions' files.
  • The PHP-FPM pool settings are checked at startup (min_spare ≤ start ≤ max_spare ≤ max_children). A bad combination now fails with a clear message instead of crash-looping.
  • The database healthcheck works with passwords that contain shell-special characters.

AMIRA deployment

These changes affect only sites that use the AMIRA overlay (compose.amira.yml):

  • The MCP server rate-limits each visitor separately instead of counting everyone as one client. Visitors can no longer forge their address to get around the limit.
  • DRE-Visualizations keeps its generated files on a private volume, dre_visualizations_private. After upgrading, press DRE Visualizations → Regenerate now once. The old dre_visualizations_data volume can be removed after that succeeds.
  • /favicon.ico serves the DRE-theme icon.
  • Pins: DRESearch 1.28.1, DRE-Visualizations 2.35.0, DRE-SEO 0.11.0, DRE-theme 2.35.3, amira-mcp v1.23.0.

Base images and docs

  • PHP 8.5.11, nginx 1.30.5, Alpine 3.24.2 and Composer 2.10.3. Omeka S stays at 4.2.1. Dependabot now also tracks the Composer and php-extension-installer images.
  • The README is now a shorter getting-started guide. Reference material moved to docs/CONFIGURATION.md, docs/CUSTOMISING.md and docs/PRODUCTION.md.
  • The backup cron example in BACKUP_RESTORE.md is fixed. The old find … -exec rm -rf line also matched backups/ itself, and after one failed run it would have deleted every backup.

Full changelog: v2.2.0...v2.3.0