Add COMPOSER_EXTRA_PACKAGES env var for runtime package installation in Docker (#1138)

* Initial plan

* Add COMPOSER_EXTRA_PACKAGES environment variable support for Docker containers

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

* Add shellcheck disable comment for intentional word splitting

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

* Add documentation for installing mailer packages in email.md

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

* Add --no-dev flag to composer require to prevent dev packages installation

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

* Use --no-install with require and run separate install command

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

.docker/frankenphp/docker-entrypoint.sh

@@ -26,6 +26,28 @@ if [ "$1" = 'frankenphp' ] || [ "$1" = 'php' ] || [ "$1" = 'bin/console' ]; then
 		composer install --prefer-dist --no-progress --no-interaction
 	fi
 
+	# Install additional composer packages if COMPOSER_EXTRA_PACKAGES is set
+	if [ -n "$COMPOSER_EXTRA_PACKAGES" ]; then
+		echo "Installing additional composer packages: $COMPOSER_EXTRA_PACKAGES"
+		# Note: COMPOSER_EXTRA_PACKAGES is intentionally not quoted to allow word splitting
+		# This enables passing multiple package names separated by spaces
+		# shellcheck disable=SC2086
+		composer require $COMPOSER_EXTRA_PACKAGES --no-install --no-interaction --no-progress
+		if [ $? -eq 0 ]; then
+			echo "Running composer install to install packages without dev dependencies..."
+			composer install --no-dev --no-interaction --no-progress --optimize-autoloader
+			if [ $? -eq 0 ]; then
+				echo "Successfully installed additional composer packages"
+			else
+				echo "Failed to install composer dependencies"
+				exit 1
+			fi
+		else
+			echo "Failed to add additional composer packages to composer.json"
+			exit 1
+		fi
+	fi
+
 	if grep -q ^DATABASE_URL= .env; then
 		echo "Waiting for database to be ready..."
 		ATTEMPTS_LEFT_TO_REACH_DATABASE=60

.docker/partdb-entrypoint.sh

@@ -39,6 +39,28 @@ if [ -d /var/www/html/var/db ]; then
     fi
 fi
 
+# Install additional composer packages if COMPOSER_EXTRA_PACKAGES is set
+if [ -n "$COMPOSER_EXTRA_PACKAGES" ]; then
+    echo "Installing additional composer packages: $COMPOSER_EXTRA_PACKAGES"
+    # Note: COMPOSER_EXTRA_PACKAGES is intentionally not quoted to allow word splitting
+    # This enables passing multiple package names separated by spaces
+    # shellcheck disable=SC2086
+    sudo -E -u www-data composer require $COMPOSER_EXTRA_PACKAGES --no-install --no-interaction --no-progress
+    if [ $? -eq 0 ]; then
+        echo "Running composer install to install packages without dev dependencies..."
+        sudo -E -u www-data composer install --no-dev --no-interaction --no-progress --optimize-autoloader
+        if [ $? -eq 0 ]; then
+            echo "Successfully installed additional composer packages"
+        else
+            echo "Failed to install composer dependencies"
+            exit 1
+        fi
+    else
+        echo "Failed to add additional composer packages to composer.json"
+        exit 1
+    fi
+fi
+
 # Start PHP-FPM (the PHP_VERSION is replaced by the configured version in the Dockerfile)
 php-fpmPHP_VERSION -F &
 

docs/installation/email.md

@@ -15,13 +15,75 @@ To make emails work you have to properly configure a mail provider in Part-DB.
 ## Configuration
 
 Part-DB uses [Symfony Mailer](https://symfony.com/doc/current/mailer.html) to send emails, which supports multiple
-automatic mail providers (like MailChimp or SendGrid). If you want to use one of these providers, check the Symfony
+mail providers (like Mailgun, SendGrid, or Brevo). If you want to use one of these providers, check the Symfony
 Mailer documentation for more information.
 
 We will only cover the configuration of an SMTP provider here, which is sufficient for most use-cases.
 You will need an email account, which you can use to send emails from via password-based SMTP authentication, this account
 should be dedicated to Part-DB.
 
+### Using specialized mail providers (Mailgun, SendGrid, etc.)
+
+If you want to use a specialized mail provider like Mailgun, SendGrid, Brevo (formerly Sendinblue), Amazon SES, or 
+Postmark instead of SMTP, you need to install the corresponding Symfony mailer package first.
+
+#### Docker installation
+
+If you are using Part-DB in Docker, you can install additional mailer packages by setting the `COMPOSER_EXTRA_PACKAGES` 
+environment variable in your `docker-compose.yaml`:
+
+```yaml
+environment:
+  - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer
+  - MAILER_DSN=mailgun+api://API_KEY:DOMAIN@default
+  - EMAIL_SENDER_EMAIL=noreply@yourdomain.com
+  - EMAIL_SENDER_NAME=Part-DB
+  - ALLOW_EMAIL_PW_RESET=1
+```
+
+You can install multiple packages by separating them with spaces:
+
+```yaml
+environment:
+  - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
+```
+
+The packages will be installed automatically when the container starts.
+
+Common mailer packages:
+- `symfony/mailgun-mailer` - For [Mailgun](https://www.mailgun.com/)
+- `symfony/sendgrid-mailer` - For [SendGrid](https://sendgrid.com/)
+- `symfony/brevo-mailer` - For [Brevo](https://www.brevo.com/) (formerly Sendinblue)
+- `symfony/amazon-mailer` - For [Amazon SES](https://aws.amazon.com/ses/)
+- `symfony/postmark-mailer` - For [Postmark](https://postmarkapp.com/)
+
+#### Direct installation (non-Docker)
+
+If you have installed Part-DB directly on your server (not in Docker), you need to manually install the required 
+mailer package using composer.
+
+Navigate to your Part-DB installation directory and run:
+
+```bash
+# Install the package as the web server user
+sudo -u www-data composer require symfony/mailgun-mailer
+
+# Clear the cache
+sudo -u www-data php bin/console cache:clear
+```
+
+Replace `symfony/mailgun-mailer` with the package you need. You can install multiple packages at once:
+
+```bash
+sudo -u www-data composer require symfony/mailgun-mailer symfony/sendgrid-mailer
+```
+
+After installing the package, configure the `MAILER_DSN` in your `.env.local` file according to the provider's 
+documentation (see [Symfony Mailer documentation](https://symfony.com/doc/current/mailer.html) for DSN format for 
+each provider).
+
+## SMTP Configuration
+
 To configure the SMTP provider, you have to set the following environment variables:
 
 `MAILER_DSN`: You have to provide the SMTP server address and the credentials for the email account here. The format is

docs/installation/installation_docker.md

@@ -80,7 +80,11 @@ services:
       #- BANNER=This is a test banner<br>with a line break
     
       # If you use a reverse proxy in front of Part-DB, you must configure the trusted proxies IP addresses here (see reverse proxy documentation for more information):
-      # - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16  
+      # - TRUSTED_PROXIES=127.0.0.0/8,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+      
+      # If you need to install additional composer packages (e.g., for specific mailer transports), you can specify them here:
+      # The packages will be installed automatically when the container starts
+      # - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
 ```
 
 4. Customize the settings by changing the environment variables (or adding new ones). See [Configuration]({% link
@@ -149,6 +153,9 @@ services:
       # Override value if you want to show a given text on homepage.
       # When this is commented out the webUI can be used to configure the banner
       #- BANNER=This is a test banner<br>with a line break
+      
+      # If you need to install additional composer packages (e.g., for specific mailer transports), you can specify them here:
+      # - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
 
   database:
     container_name: partdb_database
@@ -169,6 +176,38 @@ services:
 
 ```
 
+### Installing additional composer packages
+
+If you need to use specific mailer transports or other functionality that requires additional composer packages, you can 
+install them automatically at container startup using the `COMPOSER_EXTRA_PACKAGES` environment variable.
+
+For example, if you want to use Mailgun as your email provider, you need to install the `symfony/mailgun-mailer` package.
+Add the following to your docker-compose.yaml environment section:
+
+```yaml
+environment:
+  - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer
+  - MAILER_DSN=mailgun+api://API_KEY:DOMAIN@default
+```
+
+You can specify multiple packages by separating them with spaces:
+
+```yaml
+environment:
+  - COMPOSER_EXTRA_PACKAGES=symfony/mailgun-mailer symfony/sendgrid-mailer
+```
+
+{: .info }
+> The packages will be installed when the container starts. This may increase the container startup time on the first run.
+> The installed packages will persist in the container until it is recreated.
+
+Common mailer packages you might need:
+- `symfony/mailgun-mailer` - For Mailgun email service
+- `symfony/sendgrid-mailer` - For SendGrid email service  
+- `symfony/brevo-mailer` - For Brevo (formerly Sendinblue) email service
+- `symfony/amazon-mailer` - For Amazon SES email service
+- `symfony/postmark-mailer` - For Postmark email service
+
 ### Update Part-DB
 
 You can update Part-DB by pulling the latest image and restarting the container.