Customization

Adding start up scripts

Every .sh file in /etc/entrypoint.d/ runs when the container starts, before PHP or the web server. Add your own script there to run a command at startup, such as an Artisan command after migrations.

Add a script

Write the script and copy it into the image:

Dockerfile
FROM serversideup/php:8.5-fpm-nginx

COPY entrypoint.d/ /etc/entrypoint.d/

APP_BASE_DIR is /var/www/html by default. The 60- prefix runs this script after Laravel automations, which are 50-.

How scripts run

The entrypoint, docker-php-serversideup-entrypoint, sources each script with . under /bin/sh. That has a few consequences:

  • No execute bit needed. The file only needs to be readable and end in .sh.
  • The entrypoint ignores the shebang line. A script that starts with #!/bin/bash still runs under sh. Start every script with #!/bin/sh anyway, because S6 needs it (see below).
  • Write POSIX sh, not Bash. Bash syntax such as [[ ]] or arrays fails on Debian too, not only on Alpine.
  • exit 0 ends only your script. The next script runs.
  • Any other exit code stops the container before PHP or the web server starts.
  • Any failing command stops the container. Scripts inherit set -e from the entrypoint, so a command that returns non-zero, such as a grep with no match, ends the script with an error. Add || true to a command that is allowed to fail.
  • Variables don't carry over. Each script runs in its own subshell, so a variable you set or export isn't visible to later scripts or to PHP. Set it with ENV or in your Compose file instead.
  • Scripts run for every command, including one-off commands like docker compose run php php artisan tinker. If your script should skip those, check $SERVERSIDEUP_DEFAULT_COMMAND. It is true only when the command is /init, php-fpm, or frankenphp, the default commands of the server images.

If you convert the scripts to S6 services with docker-php-serversideup-s6-init, S6 runs them instead, in the same order. S6 executes each script rather than sourcing it, so the shebang matters: #!/bin/sh is rewritten to load the container's environment, and a script without one fails to start. See using S6 Overlay.

Scripts should finish quickly. For a process that keeps running, such as a queue worker, run another container or run it as an S6 service.

Choose a number

Scripts run in version-sort order (sort -V) of their file names, so 10- comes after 9-. Scripts with the same number sort by the rest of the name: 1-my-script.sh runs after 1-log-output-level.sh, not before it. Pick a number between the default scripts you want to run between.

ScriptImagesWhat it does
0-container-info.shAllPrints the startup banner. Off with SHOW_WELCOME_MESSAGE=false.
1-log-output-level.shAllApplies LOG_OUTPUT_LEVEL=debug to PHP and PHP-FPM.
5-fpm-pool-user.shfpm, fpm-nginx, fpm-apacheWhen running as root, sets the user PHP-FPM workers run as.
5-generate-ssl.shfpm-nginx, fpm-apache, frankenphpCreates a self-signed certificate when SSL_MODE isn't off. See configuring SSL.
10-init-webserver-config.shfpm-nginx, fpm-apacheWrites the NGINX or Apache configuration from environment variables.
50-laravel-automations.shAllRuns Laravel automations when AUTORUN_ENABLED=true.

For example, 20- runs after the web server configuration and before Laravel automations, and 60- runs after everything.

DISABLE_DEFAULT_CONFIG=true makes every default script exit without doing anything. Your own scripts still run.

To replace a default script, copy a file with the same name into /etc/entrypoint.d/.

Check that it ran

Start the container and look for your script's output in the logs:

Terminal
docker compose up --build

Set LOG_OUTPUT_LEVEL=debug to log each script's name and exit code as it runs.