You can pass arguments to multiple services in Docker by defining a custom entrypoint script that parses command-line flags and routes them to specific service initialization processes. This approach allows a single container image to behave differently based on how it is invoked, supporting complex multi-service environments without requiring separate images for each configuration.
Understanding the Default Behavior
By default, Docker containers execute a single primary process defined by the
ENTRYPOINT or
CMD instruction in the
Dockerfile. When you run
docker run myimage arg1 arg2, those arguments are passed directly to that main process. However, modern applications often require multiple background services, such as a web server and a database connector, to start simultaneously. If these services expect their own configuration files or environment variables rather than raw command-line arguments, simply passing arguments to the container will not configure them correctly. The challenge lies in bridging the gap between user-provided inputs and the internal requirements of each subsystem.
Creating a Custom Entrypoint Script
The most robust solution involves creating a shell script that serves as the container's entry point. This script acts as a router, interpreting the arguments provided at runtime and configuring each service accordingly. Start by creating a file named
entrypoint.sh in your project directory. This script must be executable and should begin with the standard shebang line
#!/bin/bash. Inside this script, you will parse the
$@ variable, which contains all arguments passed to the container. For example, you might check if a flag like
--service-a-config exists and then write its value to a temporary configuration file or set an environment variable that Service A reads during startup.
To ensure the script runs correctly, you need to integrate it into your
Dockerfile. Use the
COPY instruction to move
entrypoint.sh into the container image, and then use
RUN chmod +x /entrypoint.sh to make it executable. Finally, define the entrypoint using the JSON array format:
ENTRYPOINT ["/entrypoint.sh"]. This format ensures that arguments are not interpreted by a shell wrapper but are passed directly to your script, preserving spaces and special characters.
Handling Multiple Services with Systemd or Supervisor
If your application relies on traditional Linux service management, you might use
systemd or
supervisord to manage multiple processes within a single container. In this scenario, the entrypoint script does not start the services directly but instead configures their respective configuration files before launching the service manager. For instance, if you are using
supervisord, your script could generate a
supervisord.conf file dynamically based on the arguments. It might insert specific paths or connection strings into the
[program:webapp] section and another set of parameters into the
[program:worker] section. Once the configuration is generated, the script executes
exec supervisord -n to start the supervisor daemon in the foreground, keeping the container alive while managing the child processes.
This method separates concerns effectively. The entrypoint handles configuration logic, while the service manager handles process lifecycle. This is particularly useful when dealing with dependencies between services, such as ensuring a database service is ready before starting the application server. You can also implement health checks within the entrypoint script to verify that each service has started successfully before proceeding, adding an extra layer of reliability to your deployment.
Best Practices for Argument Parsing
When parsing arguments in bash, avoid using simple positional parameters like
$1 or
$2 because they are fragile and depend on the order of arguments. Instead, use a loop to iterate through
$@ and match known flags. For example:
while [[ $# -gt 0 ]]; do
case $1 in
--db-host)
DB_HOST="$2"
shift 2
;;
--app-port)
APP_PORT="$2"
shift 2
;;
*)
echo "Unknown option: $1"
exit 1
;;
esac
done
This pattern makes your script extensible and easier to maintain. You can add new flags without breaking existing functionality. Additionally, always provide sensible defaults for optional arguments so that the container works out-of-the-box even if no arguments are passed. This improves the developer experience and reduces the likelihood of misconfiguration errors.
For more insights on managing system configurations, see our guide on
Ubuntu 20 LTS: Understanding the 'bash-l' Default Login User.
Frequently Asked Questions
Can I use environment variables instead of command-line arguments?
Yes, environment variables are often preferred for static configuration, while command-line arguments are better for dynamic overrides. You can combine both by having your entrypoint script read from
$ENV_VAR first and then override with any matching
$@ flags. This provides flexibility for different deployment scenarios, such as Kubernetes pods versus local development.
How do I debug issues with my entrypoint script?
Add
set -x at the top of your script to enable verbose tracing. This will print each command as it is executed, allowing you to see exactly where the script fails. You can also run the container in interactive mode with
docker run -it myimage /bin/bash to manually test the script after copying it into the container.
Is it possible to pass arguments to only one specific service?
Absolutely. Your entrypoint script can inspect the arguments and decide which services to configure. For example, if the argument
--start-worker-only is present, the script might skip generating configuration for the web server and only start the worker process. This conditional logic allows a single image to serve multiple distinct purposes.
What happens if I forget to include the exec keyword in my entrypoint?
Without
exec, the shell process remains the parent of your services, which can prevent proper signal handling (like SIGTERM for graceful shutdowns). Using
exec replaces the shell process with the actual service manager, ensuring that signals are forwarded correctly and that the container stops cleanly when requested.
Can I use Docker Compose to pass these arguments?
Yes, Docker Compose supports passing arguments via the
command directive in your
docker-compose.yml file. These commands override the
CMD in the
Dockerfile and are passed to your entrypoint script just like manual
docker run arguments. This makes testing different configurations locally much easier without modifying the underlying image.