Overview & links

Tags and respective Dockerfile links

centos-6

The latest CentOS-6 Standard Package based release can be pulled from the centos-6 Docker tag. It is recommended to select a specific release tag - the convention is centos-6-1.10.4 or 1.10.4 for the 1.10.4 release tag. This build of Apache, (httpd CentOS package), uses the mpm_prefork_module and php5_module modules for handling PHP.

centos-6-httpd24u-php56u

The latest CentOS-6 IUS Apache 2.4, PHP-FPM 5.6 based release can be pulled from the centos-6-httpd24u-php56u Docker tag. It is recommended to select a specific release tag - the convention is centos-6-httpd24u-php56u-2.2.4 or 2.2.4 for the 2.2.4 release tag. This build of Apache, (httpd24u package), uses the mpm_prefork_module and php-fpm for handling PHP. This version has the option of using the worker or event MPM.

Supervisor is used to start the httpd (and, if applicable, php-fpm) daemon when a docker container based on this image is run. To enable simple viewing of stdout for the service's subprocess, supervisor-stdout is included. This allows you to see output from the supervisord controlled subprocesses with docker logs {docker-container-name}.

If enabling and configuring SSH access, it is by public key authentication and, by default, the Vagrantinsecure private key is required.

SSH Alternatives

SSH is not required in order to access a terminal for the running container. The simplest method is to use the docker exec command to run bash (or sh) as follows:

$ docker exec -it {docker-name-or-id} bash

For cases where access to docker exec is not possible the preferred method is to use Command Keys and the nsenter command. See command-keys.md for details on how to set this up.

Quick Example

Run up a container named apache-php.pool-1.1.1 from the docker image jdeathe/centos-ssh-apache-php on port 8080 of your docker host.

Now point your browser to http://{docker-host}:8080 where {docker-host} is the host name of your docker server and, if all went well, you should see the "Hello, world!" page.

To be able to access the server using the "app-1.local" domain name you need to add a hosts file entry locally; such that the IP address of the Docker host resolves to the name "app-1.local". Alternatively, you can use the elinks browser installed in the container. Note that because you are using the browser from the container you access the site over port 80.

$ docker exec -it apache-php.pool-1.1.1 \
elinks http://app-1.local

To verify the container is initialised and running successfully by inspecting the container's logs.

$ docker logs apache-php.pool-1.1.1

On first run, the bootstrap script, (/usr/sbin/httpd-bootstrap), will check if the DocumentRoot directory is empty and, if so, will populate it with the example app scripts and app specific configuration files.

The apachectl command can be accessed as follows.

$ docker exec -it apache-php.pool-1.1.1 apachectl -h

Instructions

Running

To run the a docker container from this image you can use the standard docker commands. Alternatively, you can use the embedded (Service Container Manager Interface) scmi that is included in the image since centos-6-1.7.2 or, if you have a checkout of the source repository, and have make installed the Makefile provides targets to build, install, start, stop etc. where environment variables can be used to configure the container options and set custom docker run parameters.

SCMI Installation Examples

The following example uses docker to run the SCMI install command to create and start a container named apache-php.pool-1.1.1. To use SCMI it requires the use of the --privileged docker run parameter and the docker host's root directory mounted as a volume with the container's mount directory also being set in the scmi--chroot option. The --setopt option is used to add extra parameters to the default docker run command template; in the following example a named configuration volume is added which allows the SSH host keys to persist after the first container initialisation. Not that the placeholder {{NAME}} can be used in this option and is replaced with the container's name.

SCMI Systemd Support

If your docker host has systemd (and optionally etcd) installed then scmi provides a method to install the container as a systemd service unit. This provides some additional features for managing a group of instances on a single docker host and has the option to use an etcd backed service registry. Using a systemd unit file allows the System Administrator to use a Drop-In to override the settings of a unit-file template used to create service instances. To use the systemd method of installation use the -m or --manager option of scmi and to include the optional etcd register companion unit use the --register option.

SCMI Fleet Support

Deprecation Notice: The fleet project is no longer maintained. The fleet --manager option has been deprecated in scmi.

If your docker host has systemd, fleetd (and optionally etcd) installed then scmi provides a method to schedule the container to run on the cluster. This provides some additional features for managing a group of instances on a fleet cluster and has the option to use an etcd backed service registry. To use the fleet method of installation use the -m or --manager option of scmi and to include the optional etcd register companion unit use the --register option.

SCMI Image Information

Since release centos-6-1.7.2 the install template has been added to the image metadata. Using docker inspect you can access scmi to simplify install/uninstall tasks.

NOTE: A prerequisite of the following examples is that the image has been pulled (or loaded from the release package).

$ docker pull jdeathe/centos-ssh-apache-php:2.2.4

To see detailed information about the image run scmi with the --info option. To see all available scmi options run with the --help option.

It may be desirable to prevent the startup of the httpd-bootstrap, httpd-wrapper, and/or, php-fpm-wrapper scripts. For example, when using an image built from this Dockerfile as the source for another Dockerfile you could disable services from startup by setting APACHE_AUTOSTART_HTTPD_WRAPPER and APACHE_AUTOSTART_PHP_FPM_WRAPPER to false. The benefit of this is to reduce the number of running processes in the final container. Another use for this would be to make use of the packages installed in the image such as ab, curl, elinks, php-cli etc.

APACHE_SERVER_NAME & APACHE_SERVER_ALIAS

The APACHE_SERVER_NAME and APACHE_SERVER_ALIAS environmental variables are used to set the VirtualHost ServerName and ServerAlias values respectively. If the value contains the placeholder {{HOSTNAME}} it will be replaced with the system hostname value; by default this is the container id but the hostname can be modified using the --hostname docker create|run parameter.

In the following example the running container would respond to the host names app-1.local or app-1.

APACHE_EXTENDED_STATUS_ENABLED

The variable APACHE_EXTENDED_STATUS_ENABLED allows you to turn ExtendedStatus on. It is turned off by default as it has an impact on the server's performance but with it enabled you can gather more statistics.

...
--env "APACHE_EXTENDED_STATUS_ENABLED=true" \
...

You can view the output from Apache server-status either using the elinks browser from onboard the container or by using watch and curl to monitor status over time. The following command shows the server-status updated at a 1 second interval given an APACHE_SERVER_NAME or APACHE_SERVER_ALIAS of "app-1.local".

APACHE_HEADER_X_SERVICE_UID

The APACHE_HEADER_X_SERVICE_UID environmental variable is used to set a response header named X-Service-UID that lets you identify the container that is serving the content. This is useful when you have many containers running on a single host using different ports or if you are running a cluster and need to identify which host the content is served from. If the value contains the placeholder {{HOSTNAME}} it will be replaced with the system hostname value; by default this is the container id but the hostname can be modified using the --hostname docker create|run parameter.

...
--env "APACHE_HEADER_X_SERVICE_UID={{HOSTNAME}}" \
...

APACHE_LOAD_MODULES

The variable APACHE_LOAD_MODULES defines all Apache modules to be loaded from /etc/httpd/conf/http.conf. The default is the minimum required so you may need to add more as necessary. To add the "mod_rewrite" Apache Module you would add it's identifier rewrite_module to the array as follows.

APACHE_MOD_SSL_ENABLED

By default SSL support is disabled but a second port, (mapped to 8443), is available for traffic that has been been through upstream SSL termination (SSL Offloading). If you want the container to support SSL directly then set APACHE_MOD_SSL_ENABLED=true this will then generate a self signed certificate and will update Apache to accept traffic on port 443.

APACHE_RUN_USER & APACHE_RUN_GROUP

APACHE_PUBLIC_DIRECTORY

The public directory is relative to the APACHE_CONTENT_ROOT and together they form the Apache DocumentRoot path. The default value is public_html and should not be changed unless changes are made to the source of the app to include an alternative public directory such as web or public.

...
--env "APACHE_PUBLIC_DIRECTORY=web" \
...

APACHE_SSL_CERTIFICATE

The APACHE_SSL_CERTIFICATE environment variable is used to define a PEM, (and optionally base64), encoded certificate bundle. Base64 encoding of the PEM file contents is recommended. To make a compatible certificate bundle use the cat command to combine the certificate files together.

Note: The base64 command on Mac OSX will encode a file without line breaks by default but if using the command on Linux you need to include use the -w option to prevent wrapping lines at 80 characters. i.e. base64 -w 0 -i {certificate-path}.

APACHE_SSL_CIPHER_SUITE

Use the APACHE_SSL_CIPHER_SUITE environment variable to define an appropriate Cipher Suite. The default "intermediate" selection should be suitable for most use-cases where support for a wide range browsers is necessary.

APACHE_SSL_PROTOCOL

Use the APACHE_SSL_PROTOCOL environment variable to define the supported protocols. The default protocols are suitable for most "intermediate" use-cases however you might want to restrict the TLS version support for example.

APACHE_SYSTEM_USER

Use the APACHE_SYSTEM_USER environment variable to define a custom service username.

...
--env "APACHE_SYSTEM_USER=app-1" \
...

PHP_OPTIONS_DATE_TIMEZONE

The default timezone for the container, and the PHP app, is UTC however the operator can set an appropriate timezone using the PHP_OPTIONS_DATE_TIMEZONE variable. The value should be a timezone identifier, like UTC or Europe/London. The list of valid identifiers is available in the PHP List of Supported Timezones.

To set the timezone for the UK and account for British Summer Time you would use:

Using PHP_OPTIONS_SESSION_SAVE_HANDLER and PHP_OPTIONS_SESSION_SAVE_PATH together it's possible to configure PHP to use an alternative session.save_handler and session.save_path. For example if you have a Memcached server running on the host memcached-server on the default port 11211 the following configuration will allow session data to be stored in Memcached, allowing session data to be shared between multiple PHP containers.

Using PHP_OPTIONS_SESSION_NAME a session name can be defined - otherwise the default name "PHPSESSID" is used.