Running PHP Scripts in BlueSpice Docker Environment

To run PHP scripts in your BlueSpice Docker environment, you must execute them inside the container where PHP is already installed. The bluespice-wiki-task image contains PHP 8.4.15, so you don’t need to reinstall anything - you just need to use the correct Docker command to execute your scripts inside the container where PHP is available.

Contents

• Understanding the BlueSpice Docker PHP Environment
• Executing PHP Scripts Inside the Container
• Common Issues and Solutions
• Alternative Methods for PHP Execution
• Maintenance Scripts and Cronjobs
• Best Practices for BlueSpice Docker PHP Management
• Sources
• Conclusion

Understanding the BlueSpice Docker PHP Environment

When you install BlueSpice using Docker, PHP 8.4.15 is already baked into the bluespice-wiki-task image. This means PHP is available inside the container but not on your host system. The error message “PHP cannot be found” occurs when you’re trying to execute PHP scripts from your host machine outside of the Docker container environment.

The official BlueSpice documentation clearly states: “PHP 8.4.15 is baked into the bluespice-wiki-task image. To execute any PHP script (e.g. maintenance scripts, custom scripts, or CLI tools) you must run it inside the container.”

This architecture provides security benefits by isolating the PHP environment within the container, preventing potential conflicts with your host system’s PHP installations. When working with docker php environments, remember that each container has its own isolated filesystem and environment variables.

Executing PHP Scripts Inside the Container

To run your PHP script in the BlueSpice Docker environment, you need to use Docker commands to execute the script inside the appropriate container. Here’s the step-by-step process:

Basic Command Structure

The fundamental command you’ll need is:

docker exec -it <container_name> php <path_to_script>

• <container_name>: The name of your BlueSpice container (usually something like bluespice_wiki)
• <path_to_script>: The path to your PHP script inside the container

Working Directory Inside Container

When you execute commands inside the container, you’ll be working from /app/bluespice/w, which is the wiki code base. For example:

docker exec -it bluespice_wiki php maintenance/run.php update --quick

This command executes the MediaWiki maintenance script run.php with the update --quick parameters directly inside the container where PHP is available.

Interactive PHP Shell

If you need to test PHP code interactively, you can start a PHP shell inside the container:

docker exec -it bluespice_wiki php -a

This will give you an interactive PHP shell where you can execute PHP commands directly, which is useful for debugging and testing.

Common Issues and Solutions

“PHP not found” Error

The most common issue you’re experiencing happens when you try to run PHP from your host system. The solution is always to specify the container name when using docker exec php commands.

Container Name Unknown

If you don’t know your container name, run:

docker ps

This will show all running containers with their names and IDs. Use the name (usually bluespice_wiki) in your docker exec commands.

File Path Issues

When referencing files, remember you’re working inside the container’s filesystem. The typical path structure for BlueSpice in Docker is:

• /app/bluespice/w - Main wiki code
• /app/bluespice/w/maintenance - MediaWiki maintenance scripts
• /app/bluespice/w/extensions - Extensions directory

Permission Issues

If you encounter permission errors, the container may be running as a different user. You can specify the user with the -u flag:

docker exec -u root -it bluespice_wiki php your_script.php

Alternative Methods for PHP Execution

Using Docker Run with Volumes

For one-off script execution, you can use docker run with volume mounts:

docker run -it --rm -v /path/to/your/scripts:/scripts bluespice/bluespice-free php /scripts/your_script.php

This creates a temporary container, mounts your local scripts into it, executes the PHP script, then removes the container. The --rm flag ensures the container is removed after execution.

Using Docker Compose

If you’re using docker compose for your BlueSpice setup, you can execute commands like this:

docker-compose exec wiki php maintenance/update.php

This targets the service named wiki in your docker-compose.yml file.

Creating a Custom PHP Script Container

For frequent PHP execution needs, you can create a custom Dockerfile that extends the base BlueSpice image with additional PHP packages:

FROM bluespice/bluespice-free:latest
RUN docker-php-ext-install mysqli pdo pdo_mysql

Then build and use this custom image for your PHP script executions.

Maintenance Scripts and Cronjobs

BlueSpice requires regular maintenance tasks that are executed via PHP scripts. The official documentation provides the standard cronjob command:

php <installpath-bluespice>/vendor/mwstake/mediawiki-component-processmanager/maintenance/processRunner.php <installpath-bluespice>/maintenance/Maintenance.php --max-processes=100 --wait

In a Docker environment, this would be executed as:

docker exec -it bluespice_wiki php /app/bluespice/w/vendor/mwstake/mediawiki-component-processmanager/maintenance/processRunner.php /app/bluespice/w/maintenance/Maintenance.php --max-processes=100 --wait

This command should be set up in your system’s crontab to run every minute for optimal performance.

Best Practices for BlueSpice Docker PHP Management

Script Organization

Keep your custom PHP scripts organized within the container’s filesystem. A good practice is to create a custom directory within /app/bluespice/w/ for your custom scripts.

Error Logging

PHP errors in Docker containers are typically logged to stdout/stderr, which you can view with:

docker logs bluespice_wiki

For more detailed logging, you might need to configure PHP inside the container or mount a log volume.

Security Considerations

When executing PHP scripts in Docker containers, remember that containers provide isolation but aren’t inherently secure. Follow security best practices:

1. Use specific container names rather than random ones
2. Limit the scope of volume mounts
3. Use read-only volumes where possible
4. Run containers with minimal necessary privileges

Performance Optimization

For frequent PHP execution, consider keeping containers running rather than starting/stopping them each time. The startup overhead for docker containers can be significant, as noted in the Sarulabs guide.

Sources

• Setup:Installation Guide/Docker - BlueSpice Helpdesk
• Create a PHP command based on docker - Sarulabs
• Cronjobs - BlueSpice Helpdesk
• How to run a PHP script on docker? - Stack Overflow
• BlueSpice free (Support archive) - Discussion thread

Conclusion

Running PHP scripts in a BlueSpice Docker environment is straightforward once you understand that PHP exists inside the container, not on your host system. The key solution is using docker exec commands to execute your PHP scripts inside the bluespice-wiki-task container where PHP 8.4.15 is already installed and ready to use. By following the methods outlined above, you can efficiently run maintenance scripts, custom PHP code, and MediaWiki CLI tools without the need to reinstall PHP or modify your Docker setup. Remember that docker php execution requires proper container targeting and understanding of the container’s filesystem structure to avoid path-related errors.