200ms/phpapache_dev2 repository overview

⁠PHP Apache Dev^2 container

This project is a source of 200ms/phpapache_dev2 docker image. 200ms/phpapache_dev2 belongs to a set of images that can be described as "Dev^2 suit". The idea behind this is to develop Docker images and complementing tools aimed to ease development and testing of LAMP applications.

The main goals are:

• Eliminate password hassle and boring tasks (e.g. manual account creation)
• Provide debugging out-of the box
• Add network insight capabilities

200ms/phpapache_dev2 holds Apache server pre-configured to support development with XDebug, verbose messaging and more.

Docker image can be pulled with:

docker pull 200ms/phpapache_dev2

Other images implementing that idea are:

• 200ms/wpapache_dev2⁠ - Wordpress with WPC-CLI and more
• 200ms/mariadb_dev2⁠ - MariaDB database with automatic DB creation and more
• 200ms/prestashop_dev2⁠ - Prestashop with helper scripts

⁠NOTE 1: 200ms/phpapache_dev2 image has NOT been tested on other OS then Linux. Therefore at this point only this OS is supported.

⁠NOTE 2: Some functionalities are under development, however current version is very useful support for my everyday work as developer. Feature requests, bug reports can be reported here: BitBucket⁠.

⁠FUSE and extra permissions

This image internally uses Dev2FS⁠ that requires Linux FUSE⁠ module to be loaded but also elevated privileges for each Docker container based on this image. It might be required to modprobe fuse prior to using all features of the image. Moreover it is required to run container with:

docker ... --cap-add SYS_ADMIN --device /dev/fuse ...

parameters. Or in the case of docker-compose.yaml:

services:
  proj:
    ...
    cap_add: ['SYS_ADMIN']
    devices:
      - /dev/fuse
    ...

This elevates container's permissions allowing FUSE based Dev2FS to work.

Dev2FS has been developed to fix mismatch of shared file permissions, therefore it is actually one of the key elements of Dev2 suit.

⁠Special directory

PHP code and other files must be shared between container and host. For 200ms/phpapache_dev2 directory named:

/code

has been chosen as a code share point. Data shared with /code is accessed by Apache server, additionally container will handle proper uid:gid remapping.

⁠Usage

To create container call:

docker run --cap-add SYS_ADMIN --device /dev/fuse \
           -it -p 8080:80 -v $(pwd)/src:/code \
           200ms/phpapache_dev2

As indicated just above, --cap-add SYS_ADMIN --device /dev/fuse is to elevate permissions.

/code is a path to be shared with a host. $(pwd)/src is a source directory for PHP app see example below⁠.

⁠Optional MySQL Database

MySQL database is a very common for PHP projects, thus 200ms/phpapache_dev2 image provides an option to run it among with Apache server. To launch MySQL (MariaDB fork):

1. set LOCALMYSQL variable to yes (or y, on, 1), like bellow:

docker run --cap-add SYS_ADMIN --device /dev/fuse \
           -e LOCALMYSQL=yes \
           -it -p 8080:80 -v $(pwd)/src:/code \
           200ms/phpapache_dev2

1. or, set MYSQL_HOST to 'localhost':

docker run --cap-add SYS_ADMIN --device /dev/fuse \
           -e MYSQL_HOST=localhost \
           -it -p 8080:80 -v $(pwd)/src:/code \
           200ms/phpapache_dev2

This triggers new container to launch both: Apache and MariaDB services. Database is configured automatically, settings can be changed (from default) or read via environment variables⁠.

⁠PHP modules

Functionalities of Apache server can be tuned with PHP modules. 200ms/phpapache_dev2 comes with the following installed - bold font, and available (for installation) - regular font, modules:

• PHP core modules: date
• PHP specific modules: opcache, phar, tokenizer, xdebug
• PDO DB driver modules: pdo, pdo_mysql, pdo_pgsql, pdo_sqlite
• DB-specific driver modules: mysqli(old driver⁠), mysqlnd, pgsql, sqlite3
• filesystem and system: posix
• Image read and manipulation: gd, iconv, exif
• Locale and text manipulation/validation: ctype, filter, gettext, intl, mbstring, pcre
• Text formats: json, simplexml, xml, xmlreader, xmlwriter
• Document and data formats: dom, fileinfo
• Web-app support modules: session
• Cryptography extensions: hash, sodium
• Network protocols modules: curl, ftp, openssl
• Archive formats: bz2, zip

Additional modules can be installed with dev2_docker-apache-ext.sh, or trough EXTR_MOD variable, e.g.:

# install GD and Intl extensions:
docker <Dev2 PHP Apache container> dev2_docker-apache-ext.sh gd intl

# ext. names can be separated by commas:
docker <Dev2 PHP Apache container> dev2_docker-apache-ext.sh gd,intl

and trough EXTR_MOD:

docker run --cap-add SYS_ADMIN --device /dev/fuse \
           -e EXTR_MOD=gd,intl \
           -it -p 8080:80 -v $(pwd)/src:/code \
           200ms/phpapache_dev2

Module names can be separated by space, or commas, commas are more convenient in command line, spaces in Docker/configuration files see example below⁠.

⁠Project example

This is an example of LAMPhp project organisation with Docker and Dev2 PHP Apache:

.
├── ReadMe.md
├── doc/
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yaml
│   └── settings.env
├── src/
└── test/

Content of Dockerfile:

FROM 200ms/phpapache_dev2

LABEL maintainer="..." \
      version="..." \
      dev2.framework="PHP app"

# install packages:
RUN dev2_addtools.sh $PACKGS
# install Apache extensions:
RUN dev2_docker-apache-ext.sh $EXTR_MOD

and docker-compose.yaml

services:
  proj:
    build: .
    ports:
      - 8080:80
    volumes:
      - ../src:/code
    cap_add: ['SYS_ADMIN']
    devices:
      - /dev/fuse
    env_file:
      - settings.env

Variables PACKGS and EXTR_MOD are not defined neither in Dockerfile nor docker-compose.yaml. This to separate configuration from docker 'build' files, here last file of this example settings.env:

# Additional packages (if needed):
PACKGS=sl tree

#  and Apache extensions:
# Note: by default 'xdebug' is already
# installed, add extensions needed by
# your project, such as gd, intl
EXTR_MOD=gd

Finally run Apache with XDebug and other dev. features:

cd docker
docker compose up

As in the example, host's ./src directory is shared with container's /code. This opens an access for Apache with Xdebug to source files making debugging a pleasure.

⁠Environment variables

⁠LOCALMYSQL

If set to yes, y, or on container will initialise MySQL server to be run locally through container's lifetime.

⁠MYSQL_HOST

This variable can be used to indicate database host name or address. If LOCALMYSQL is set to yes, MYSQL_HOST is set automatically to localhost. But if MYSQL_HOST is set to localhost container will initialise MySQL server for local usage as it would do if LOCALMYSQL would be set to yes.

⁠MYSQL_PORT

MySQL port number of socket path (for local DB). If LOCALMYSQL is set to yes, or MYSQL_HOST points to localhost or other destination default port 3306 is assigned. Otherwise variable is not set.

⁠DB_ROOT_PASS

MySQL root user password. If LOCALMYSQL is set to yes, or MYSQL_HOST points to localhost but value has not been set, random password is assigned. Otherwise variable is not set. If MySQL is set for local usage, appropriate action is performed to set password as indicated.

⁠DB_NAME

MySQL database name. If LOCALMYSQL is set to yes, or MYSQL_HOST points to localhost but value has not been set, 'mydb' is assigned. Otherwise variable is not set. If MySQL is set for local usage, appropriate action is performed to create desired database.

⁠DB_USER

MySQL standard user name. If LOCALMYSQL is set to yes, or MYSQL_HOST points to localhost but value has not been set, 'user' is assigned. Otherwise variable is not set. If MySQL is set for local usage, appropriate action is performed to create desired user granted with all permissions to database defined in DB_NAME.

⁠DB_PASS

Password for DB_USER. If LOCALMYSQL is set to yes, or MYSQL_HOST points to localhost but value has not been set, random password is assigned. Otherwise variable is not set. If MySQL is set for local usage, appropriate action is performed to set password as indicated.

⁠DEV2_DEBUG (for Dev^2 debugging)

If set to yes, y, on or 1 prints a lot of debugging messages. Used for Dev2 development purposes and bug hunting.

⁠Extending by own scripts

User can define own scripts that will be called at the launch time:

1. dev2app-deploy.sh* - scripts called at the first container launch (just after it has been created)
2. dev2app-start.sh* - scrips called each time container starts

Scripts should be located in /usr/local/bin. Scripts are launched in alphabetical order, naming convention can be such as dev2app-deploy-stage0.sh, dev2app-deploy-stage1.sh etc.

First 'deploy' scripts are launched, followed by 'start' scripts. At the second and later container's launches only 'start' is executed.

⁠Variable 'HTROOT'

Apache web root directory is stored in HTROOT that is available for 'deploy' and 'start' scripts. It points to standard /var/www/html - it's recommended to use variable as rather then fixed path.

Enjoy!