Startup scripts
Give an image an entrypoint that runs the scripts in /docker-entrypoint.d/ before its command. The image then stays generic, and each place that runs it adds its own setup as a file: a derived image, a mounted volume or a Kubernetes ConfigMap. The official nginx image works this way, and so do our CKAN and agents images.
Entrypoint
The entrypoint runs the scripts in name order and then replaces itself with the command:
#!/bin/bash
set -e
for script in /docker-entrypoint.d/*.sh; do
[ -e "$script" ] || continue
echo "docker-entrypoint.sh: running $script" >&2
. "$script" >&2
done
if [ "$#" -gt 0 ]; then
exec "$@"
fiCOPY --chmod=755 docker-entrypoint.sh /usr/local/bin/
COPY docker-entrypoint.d/ /docker-entrypoint.d/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["bash"]Each part has a reason:
execmakes the command the container's PID 1, so it gets theSIGTERMfromdocker stop. Without it, Docker waits out the stop timeout and then kills the process (Dockerfile reference: ENTRYPOINT).set -estops the container at the first script that fails, instead of starting the command without its setup.- The log and the scripts' output go to stderr, so a caller that reads the command's stdout, such as JSON from a CLI, gets only the command's output.
- A number in front of each name (
10-,20-) makes the order visible in a directory listing. - Without a command, the entrypoint only runs the scripts, so a CI job can call it when its own setup is done (see GitLab CI).
Sourcing
Sourcing a script lets its exports reach the command, and the file needs no execute bit, which a mounted ConfigMap file often lacks. A sourced script runs under the entrypoint's set -e, and an exit in it ends the entrypoint: exit 0 skips the command and the container stops with success, so leave a script early with return. Running each script in its own process keeps one script's variables and exit away from the others. nginx does both: it runs executable *.sh files, sources executable *.envsh files, and skips files without the execute bit (docker-nginx entrypoint). Pick one and document it in the image's README.
Adding scripts
Derived image
Tools go in a derived image, because a script that installs them repeats the install on every start:
FROM registry.example.com/agents:claude
RUN apk add --no-cache python3
COPY 30-instructions.sh /docker-entrypoint.d/Mounted file
Configuration that differs per run goes in a mounted file. Mount single files: a volume on the whole directory hides the scripts the image ships.
docker run --rm \
--volume "$PWD/30-instructions.sh:/docker-entrypoint.d/30-instructions.sh:ro" \
registry.example.com/agents:claudeConfigMap
In Kubernetes, mount a ConfigMap key with subPath. A subPath mount doesn't receive ConfigMap updates (ConfigMaps), which doesn't matter for a script that only runs at start:
volumes:
- name: startup
configMap:
name: agent-startup
containers:
- name: agent
image: registry.example.com/agents:claude
volumeMounts:
- name: startup
mountPath: /docker-entrypoint.d/30-instructions.sh
subPath: 30-instructions.shRepeated starts
The scripts run on every start, so write them to run twice: clone a repository when its directory is missing and pull it when it's there. The PostgreSQL image's /docker-entrypoint-initdb.d/ is the other kind. Its scripts only run when the data directory is empty, and a database that already exists is left alone (postgres on Docker Hub). Use that kind for one-time setup of state that persists.
GitLab CI
GitLab's Docker executor starts the job container with the image's entrypoint and expects it to start a shell for the job script (GitLab: Docker images). The entrypoint then runs before the job script, so it can't use credentials that the script sets up. Turn it off and source it once the script is ready, so the scripts' exports reach the commands after it:
agent:
image:
name: registry.example.com/agents:claude
entrypoint: [""]
script:
- export GITLAB_TOKEN="$AGENT_GITLAB_AUTH_TOKEN"
- . docker-entrypoint.sh
- claude --print "Review the changes on this branch"Agents image
Our agents image runs AI coding agents in GitLab CI jobs and Kubernetes CronJobs with the same scripts:
| Script | What it does |
|---|---|
10-git-credentials.sh | Gives git the GITLAB_TOKEN, so it can clone private repositories |
20-repositories.sh | Clones the git URLs in GIT_REPOSITORIES and AGENT_SKILLS, or pulls them when an earlier start cloned them |
50-claude.sh | Links the skills into ~/.claude/skills and lets Claude Code read the checkouts; only the image with Claude Code has it |
A GitLab group sets the lists as CI/CD variables and a CronJob as environment variables. A mounted 30- script adds the rest, such as the agent instructions a developer uses on their own machine.