Adding your own start up scripts
We provide a few default scripts to get you going, but sometimes you want to just add your own. We've made it easy to do that with our entrypoint.d
directory.
Entrypoint Script Requirements
Before you write your entry point script, be aware of the following requirements:
Your script should:
- Be executable (755 permissions)
- Located in the
/etc/entrypoint.d
directory - Have the file extension ending in
.sh
We recommend writing your script in /bin/sh
for the best compatibility between Alpine and Debian. If you choose to use /bin/bash
, your script will only be able to run on Debian-based images.
Choose your execution order
Since we provide default entrypoint scripts, you may want to choose the order in which your scripts are executed. We've made it easy to do that by prefixing your script with a number. The lower the number, the earlier it will be executed.
If you want to disable our entrypoint scripts, you can set DISABLE_DEFAULT_CONFIG
to true
in your environment variables.
Example: Create a custom entrypoint script
In this example, let's create a 99-my-script.sh
so it executes after all the other default scripts.
First, let's take a look at our project structure:
Project Structure
.
āāā Dockerfile
āāā docker-compose.yml
āāā entrypoint.d
ā āāā 99-my-script.sh
āāā public
āāā index.php
Let's take a look at the script that we want to run. We can keep this simple for now.
99-my-script.sh
#!/bin/sh
echo "š Hello, world!"
Now, let's take a look at our Dockerfile
:
Dockerfile
FROM serversideup/php:8.3-unit
COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/
In the above file, we're copying our entrypoint.d
directory to /etc/entrypoint.d/
in the container. We're also setting the permissions to 755
so our scripts are executable.
Finally, let's take a look at our docker-compose.yml
file:
docker-compose.yml
version: '3'
services:
php:
build:
context: .
dockerfile: Dockerfile
ports:
- 80:8080
volumes:
- .:/var/www/html
In the above file, we're building our image using the Dockerfile
in the current directory. We're also mounting our current directory to /var/www/html
in the container.
Running our example
When we run docker compose up
, we should see the following output:
Output of "docker compose up"
example-project | init-unit: Stopping Unit daemon after initial configuration...
example-project | 2023/12/05 19:52:37 [notice] 29#29 process 33 exited with code 0
example-project | init-unit: Waiting for control socket to be removed...
example-project | 2023/12/05 19:52:37 [notice] 29#29 process 34 exited with code 0
example-project |
example-project | init-unit: Unit initial configuration complete; ready for start up...
example-project |
example-project | š Hello, world!
example-project | 2023/12/05 19:52:38 [info] 1#1 unit 1.31.1 started
example-project | 2023/12/05 19:52:38 [info] 65#65 discovery started
example-project | 2023/12/05 19:52:38 [notice] 65#65 module: php 8.3.0 "/usr/lib/unit/modules/php.unit.so"
example-project | 2023/12/05 19:52:38 [info] 1#1 controller started
example-project | 2023/12/05 19:52:38 [notice] 1#1 process 65 exited with code 0
example-project | 2023/12/05 19:52:38 [info] 67#67 router started
example-project | 2023/12/05 19:52:38 [info] 67#67 OpenSSL 3.0.11 19 Sep 2023, 300000b0
You can see our š Hello, world!
is executing after the initialization of 10-init-unit.sh
.
Additional Steps For FPM-Apache & FPM-NGINX (S6 Overlay based images)
If the image you're working with is using S6 Overlay (fpm-nginx
and fpm-apache
), you'll need to take additional steps to get your scripts to execute.
Background
S6 Overlay uses a set of directories to execute scripts at different stages of the container's life cycle. You can read more about it in S6 Overlay's documentation.
Our Solution
Instead of reading through the complexities of S6 Overlay, we wrote a script called docker-php-serversideup-s6-init
that will automatically configure your script located in /etc/entrypoint.d
to execute correctly with S6 Overlay.
docker-php-serversideup-s6-init
Usage
The only thing you need to do is call docker-php-serversideup-s6-init
after your script is copied. Here's an example:
Depending on your usecase, you may want to set S6_CMD_WAIT_FOR_SERVICES
to 1
in your environment variables. This will make sure your script doesn't execute until all the services are ready. Learn more about this in S6 Overlay's documentation.
Dockerfile
FROM serversideup/php:8.3-fpm-nginx
ENV S6_CMD_WAIT_FOR_SERVICES=1
COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/
# Change to root, so we can do root things
USER root
# As root, run the docker-php-serversideup-s6-init script
RUN docker-php-serversideup-s6-init
# Change back to the www-data user
USER www-data
The above Dockerfile
will copy scripts from our entrypoint.d
directory to /etc/entrypoint.d/
and then run docker-php-serversideup-s6-init
, which will then take any scripts in /etc/entrypoint.d/
and configure them to execute correctly with S6 Overlay.