Improve documentation: comprehensive README and technical architecture reference

[rafaelfariasbsb]

Context

The current README covers the essentials for getting started, which is great. This proposal suggests expanding it with additional sections that would help users get the most out of the Docker image without needing to read the source code.

Proposal

1. Expand README.md

Add the following sections to complement the existing content:

• Image Architecture — Overview of the multi-stage build, entrypoint flow, included PHP extensions, and security features
• Environment Variables — Complete reference table with all supported variables, defaults, and descriptions (database, installation control, cron, paths)
• Volumes and Data Persistence — Full directory tree under /var/glpi, named volumes vs bind mounts guidance, and GLPI 10.x marketplace path notes
• Default PHP Settings — Table of the production settings applied by the image
• Custom Apache Configuration — How to mount and enable custom Apache configs
• Managing Cron Tasks — Dedicated cron container pattern for horizontal scaling and Kubernetes deployments
• Reverse Proxy and HTTPS — Examples with Nginx and Traefik for TLS termination
• Upgrading — Automatic and manual upgrade procedures with backup steps
• Multi-Architecture Support — Available platforms, registries, and tag scheme
• Troubleshooting — Common scenarios: logs, database connection, permissions, PHP config, console commands, supported DB engines

2. Add docs/architecture.md

A technical reference document for contributors and advanced users, covering:

• Dockerfile stages breakdown (downloader, builder, application)
• Entrypoint scripts analysis (init-volumes, forward-logs, wait-for-db, install)
• Supervisor configuration and the custom jobs extension point
• Scheduler system internals (interval and daily modes)
• Log forwarding mechanism
• Apache and PHP configuration details
• Security model (non-root execution, setcap, hardened headers, session cookies)
• Complete volume layout with file descriptions
• Full environment variable and build argument reference with examples
• CI/CD pipeline architecture
• Supporting images catalog (GitHub Actions, databases, dev environment)

Motivation

Several issues in this repository suggest that expanded documentation could help users find answers more quickly:

• PHP settings (Docker - Change php memory limit has no effect #221)
• Custom cron jobs ([Question] How to add custom cron job #232)
• Volume permissions (Got error chown: changing ownership of 'xxxx': Operation not permitted #234)
• Marketplace directory (docker-compose.yml template is missing directory for marketplace plugins #264)
• Environment variables (custom variables .env #219)

Having this information readily available in the docs would make the project even more accessible and reduce the need for users to dig into the source code.

I'm happy to submit a PR with these changes if the maintainers are interested.

[rafaelfariasbsb]

Hi,

Thanks for the feedback on #278. I've reworked the approach based on the maintainers' guidance — focusing strictly on what system administrators need to configure and operate, without documenting internals.

The new PR adds only docs/architecture.md (an operations guide), covering:

• Environment variables reference
• Volume structure and data persistence
• Startup behavior (what happens, not how)
• Scheduled jobs configuration with examples
• Log access and Docker logging limits
• PHP and Apache customization
• Reverse proxy setup (Nginx, Traefik)
• Backup and restore procedures
• Security considerations
• Horizontal scaling patterns
• Troubleshooting common issues

No changes to the README. No internal documentation (build stages, scripts, CI/CD).

New PR: #279