Containerize the application

Set up tools to easily use docker to run our application in prd, dev and
tst environments.

We use a base dockerfile to set up a base image for our project, with
all the system requirements as these are the ones changing less often.
This way we do not have to install all these dependencies every time
we build a new prd image to deploy.

prd is the production environment although running on the builtin php
web server, it is enough for the purposes of this project, for the
time being. We made "symfony/web-server-bundle" a requirement so that
we can run it for production.The generated container image is
completely self contained, it contains all, and only, the code needed
to run on prd. There is one volume configured so that we can have
persistent state between deployments (sqlite DB).

dev is used during development and includes xdebug. It also has a
volume configured so we can change the project files in the host and
have the container immediately run them without needing to create a
new container.

tst is the environment used to run the tests during development. As the
dev environment it uses a volume to run tests on the src files under
development and has xdebug configured so we can debug the tests.

Author: hgraca

.dockerignore

@@ -0,0 +1,3 @@
+no-vcs
+var
+.env

.env.dist

@@ -2,6 +2,8 @@
 # Set variables here that may be different on each deployment target of the app, e.g. development, staging, production.
 # https://symfony.com/doc/current/best_practices/configuration.html#infrastructure-related-configuration
 
+ENV=dev
+
 ###> symfony/framework-bundle ###
 APP_ENV=dev
 APP_DEBUG=1

.gitignore

@@ -1,4 +1,3 @@
-/build/
 /node_modules/
 /var/*
 !/var/cache

Makefile

@@ -7,11 +7,18 @@
 #
 # For example in a format like `subject-action-environment`, ie:
 #
+#   box-build-base:     # box is a generic term, we don't care if it is a virtual machine or a container
+#   box-build-ci:
+#   box-build-dev:
+#   box-push-base:
+#   box-push-prd:
 #   cs-fix:             # here we don't use the env because we only do it in dev
 #   dep-install:        # again, by default the env is dev
+#   dep-install-ci:
 #   dep-install-prd:
 #   dep-update:
 #   test:               # here we don't even have a subject because it is the app itself, and by default the env is dev
+#   test-ci:            # here we don't even have a subject because it is the app itself
 #
 
 # Mute all `make` specific output. Comment this out to get some debug information.
@@ -37,42 +44,76 @@ help:
 
 ########################################################################################################################
 
+CONTAINER_NAME_BASE="hgraca/explicit-architecture:app.sfn.base"
+CONTAINER_NAME_PRD="hgraca/explicit-architecture:app.sfn.prd"
 COVERAGE_REPORT_PATH="var/coverage.clover.xml"
 DB_PATH='var/data/blog.sqlite'
 
+box-build-base:
+	docker build -t ${CONTAINER_NAME_BASE} -f ./build/container/app.base.dockerfile .
+
+box-build-dev:
+	docker-compose -f build/container/dev/docker-compose.yml build --force-rm app
+
+box-build-prd:
+	docker-compose -f build/container/prd/docker-compose.yml build --force-rm app
+
+box-push-base:
+	docker push ${CONTAINER_NAME_BASE}
+
+box-push-prd:
+	docker push ${CONTAINER_NAME_PRD}
+
 #   We run this in tst ENV so that we never run it with xdebug on
 cs-fix:
-	php vendor/bin/php-cs-fixer fix --verbose
+	ENV='tst' ./bin/run php vendor/bin/php-cs-fixer fix --verbose
 
 db-setup:
-	mkdir -p var/data
+	ENV='dev' ./bin/run make db-setup-guest
+
+db-setup-guest:
+	mkdir -p ./var/data
 	php bin/console doctrine:database:drop -n --force
 	php bin/console doctrine:database:create -n
 	php bin/console doctrine:schema:create -n
 	php bin/console doctrine:fixtures:load -n
 
-dep-clearcache:
+dep-clearcache-guest:
 	composer clearcache
 
 dep-install:
-	composer install
+	ENV='dev' ./bin/run composer install
 
-dep-install-prd:
+#   We use this only when building the box used in PRD
+dep-install-prd-guest:
 	composer install --no-dev --optimize-autoloader --no-ansi --no-interaction --no-progress --no-scripts
 
 dep-update:
-	composer update
+	ENV='dev' ./bin/run composer update
+
+shell:
+	docker exec -it app.sfn.dev sh
 
 test:
-	$(MAKE) db-setup
-	php vendor/bin/phpunit
+	- ENV='tst' ./bin/stop # Just in case some container is left over stopped, as is the case after PHPStorm runs tests
+	ENV='tst' ./bin/run
+	ENV='tst' ./bin/run make db-setup-guest
+	ENV='tst' ./bin/run php vendor/bin/phpunit
 	$(MAKE) cs-fix
+	ENV='tst' ./bin/stop
 
 #   We use phpdbg because is part of the core and so that we don't need to install xdebug just to get the coverage.
 #   Furthermore, phpdbg gives us more info in certain conditions, ie if the memory_limit has been reached.
 test_cov:
-	phpdbg -qrr vendor/bin/phpunit --coverage-text --coverage-clover=${COVERAGE_REPORT_PATH}
+	ENV='tst' ./bin/run phpdbg -qrr vendor/bin/phpunit --coverage-text --coverage-clover=${COVERAGE_REPORT_PATH}
 
 up:
 	if [ ! -f ${DB_PATH} ]; then $(MAKE) db-setup; fi
-	php bin/console server:run 0.0.0.0:8000
+	$(eval UP=ENV=dev docker-compose -f build/container/dev/docker-compose.yml up -t 0)
+	$(eval DOWN=ENV=dev docker-compose -f build/container/dev/docker-compose.yml down -t 0)
+	- bash -c "trap '${DOWN}' EXIT; ${UP}"
+
+up-prd:
+	$(eval UP=ENV=prd docker-compose -f build/container/prd/docker-compose.yml up -t 0)
+	$(eval DOWN=ENV=prd docker-compose -f build/container/prd/docker-compose.yml down -t 0)
+	- bash -c "trap '${DOWN}' EXIT; ${UP}"

README.md

@@ -61,5 +61,19 @@ $ cd symfony-demo/
 $ make test_cov
 ```
 
+Integration with PHPStorm
+-------------------------
+
+Integration with PHPStorm is straight forward.
+
+Configure the servers so we can debug a request made from the browser:
+![PHPStorm servers config](docs/IDE/PHPStorm/IDE_PHPSTORM_servers.png)
+
+Configure the CLI so we can run the tests:
+![PHPStorm CLI config](docs/IDE/PHPStorm/IDE_PHPSTORM_cli_interpreter.png)
+
+Configure the test run itself:
+![PHPStorm tests config](docs/IDE/PHPStorm/IDE_PHPSTORM_tests_run.png)
+
 [1]: https://symfony.com/doc/current/reference/requirements.html
 [2]: https://symfony.com/doc/current/cookbook/configuration/web_server_configuration.html

bin/lib/docker.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+function isContainerRunning(string $containerName): bool
+{
+    if (
+        isContainerExists($containerName)
+        && 'true' === trim(shell_exec("docker inspect -f '{{.State.Running}}' $containerName 2>/dev/null"))
+    ) {
+        return true;
+    }
+
+    return false;
+}
+
+function isContainerStopped(string $containerName): bool
+{
+    if (
+        isContainerExists($containerName)
+        && 'false' === trim(shell_exec("docker inspect -f '{{.State.Running}}' $containerName 2>/dev/null"))
+    ) {
+        return true;
+    }
+
+    return false;
+}
+
+function isContainerExists(string $containerName): bool
+{
+    if ('' === shell_exec("docker ps -a | grep $containerName")) {
+        return false;
+    }
+
+    return true;
+}

bin/run

@@ -0,0 +1,55 @@
+#!/usr/bin/env php
+<?php
+/**
+ * This script allows us to start the container and related containers, and then run other commands against it.
+ * With no arguments, the container will be started and kept alive for 1h
+ * With arguments, if the container is running it will send the commands to it and leave it running
+ * With arguments, if the container is NOT running it will start it, send the commands to it and terminate it
+ */
+
+include_once('lib/docker.php');
+
+$env = getenv('ENV') ?: 'dev';
+$argumentList = array_slice($argv, 1);
+$rootDir = __DIR__ . '/..';
+$returnVal = 0;
+$containerWasRunning = false;
+$detached = '';
+
+$containerName = 'app.sfn.' . $env;
+$yamlFile = "$rootDir/build/container/$env/docker-compose.yml";
+$downCommand = "docker-compose -f $yamlFile down -t 0"; // we use the "-t 0" so that we don't have a timeout of 10s
+
+if (empty($argumentList) && isContainerRunning($containerName)) {
+    exit($returnVal);
+}
+
+if (empty($argumentList)) {
+    // If no command is given to execute, just keep the container running in the background for 1h
+    $detached = '-d';
+    $guestCommand =  "sleep 3600";
+} else {
+    $guestCommand =  implode(' ', $argumentList);
+}
+
+// We wrap the $guestCommand in /bin/sh so that we get the full output if it breaks, ie with a segfault
+$hostCommand = "docker-compose -f $yamlFile run $detached -u $(id -u):$(id -g) --name $containerName app /bin/sh -c '$guestCommand'";
+
+if (!$detached) {
+    // We wrap the host command in bash trap so that we can trap a signal and destroy the stopped containers
+    // We only wrap it if it's not detached, otherwise detaching will make the container stop immediately
+    $hostCommand = "bash -c \"trap 'echo Trapped exit! Exit code: $? \n $downCommand' SIGINT SIGTERM ERR; $hostCommand\"";
+}
+
+if (isContainerRunning($containerName)) {
+    $containerWasRunning = true;
+    system("docker exec -it $containerName $guestCommand", $returnVal);
+} else {
+    system($hostCommand, $returnVal);
+}
+
+if (!$detached && !$containerWasRunning && isContainerExists($containerName)) {
+    system($downCommand);
+}
+
+exit($returnVal);

bin/stop

@@ -0,0 +1,20 @@
+#!/usr/bin/env php
+<?php
+
+include_once('lib/docker.php');
+
+$env = getenv('ENV') ?: 'dev';
+$rootDir = __DIR__ . '/..';
+$returnVal = 0;
+
+$containerName = 'app.sfn.' . $env;
+$yamlFile = "$rootDir/build/container/$env/docker-compose.yml";
+
+// we use the "-t 0" so that we don't have a timeout of 10s
+$downCommand = "docker-compose -f $yamlFile down -t 0";
+
+if (isContainerExists($containerName)) {
+    system($downCommand, $returnVal);
+}
+
+exit($returnVal);

build/container/app.base.dockerfile

@@ -0,0 +1,18 @@
+FROM php:7.1-alpine
+
+# `apk --update`    updates indexes before installing
+# `apk --no-cache`  doesn't put stuff in the cache, so we don't need to remove it at the end
+# `apk --virtual`   lets us uninstall temporary dependencies in one go at the end
+RUN apk --update add --no-cache --virtual build-dependencies autoconf g++ && \
+    apk add --no-cache make zlib-dev curl && \
+    mkdir -p /tmp/pear/cache && \
+    docker-php-ext-configure pcntl && \
+    docker-php-ext-install pcntl && \
+    docker-php-ext-configure bcmath && \
+    docker-php-ext-install bcmath && \
+    docker-php-ext-configure zip && \
+    docker-php-ext-install zip && \
+    curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/bin --filename=composer && \
+    apk del build-dependencies && \
+    rm -rf /var/cache/apk/* && \
+    pecl clear-cache

build/container/dev/app.dockerfile

@@ -0,0 +1,11 @@
+FROM hgraca/explicit-architecture:app.sfn.prd
+
+ENV ENV="dev"
+
+RUN apk --update add --no-cache --virtual build-dependencies autoconf g++ && \
+    pecl install xdebug-2.6.0 && \
+    apk del build-dependencies && \
+    rm -rf /var/cache/apk/* && \
+    pecl clear-cache
+
+COPY build/container/dev/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

build/container/dev/docker-compose.yml

@@ -0,0 +1,41 @@
+version: '3'
+
+services:
+  app:
+    image: hgraca/explicit-architecture:app.sfn.dev
+    container_name: app.sfn.dev
+    working_dir: /opt/app
+    build:
+      context: ../../../
+      dockerfile: ./build/container/dev/app.dockerfile
+    tty: true # fix for symfony saying: "proc_open(/dev/tty): failed to open stream: No such device or address"
+    ports:
+      - '80:8000' # This way we can run the application locally at http://localhost
+    volumes:
+      - ../../../:/opt/app
+      - ~/.composer:/.composer                            # so we can use the host composer cache
+      - ./php.ini:/usr/local/etc/php/php.ini              # so we can easily change php config
+      - ./xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini # so we can easily change xdebug config
+    environment:
+      PHP_IDE_CONFIG: 'serverName=docker' # This is needed to debug from CLI (ie. while running tests)
+      ENV: 'dev'
+
+      ###> symfony/framework-bundle ###
+      APP_ENV: 'dev'
+      APP_DEBUG: 1
+      APP_SECRET: '67d829bf61dc5f87a73fd814e2c9f629'
+      ###< symfony/framework-bundle ###
+
+      ###> doctrine/doctrine-bundle ###
+      # Format described at http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
+      # For a sqlite database, use: "sqlite:///%kernel.project_dir%/var/data.db"
+      # Set "serverVersion" to your server version to avoid edge-case exceptions and extra database calls
+      DATABASE_URL: 'sqlite:///%kernel.project_dir%/var/data/blog.sqlite'
+      ###< doctrine/doctrine-bundle ###
+
+      ###> symfony/swiftmailer-bundle ###
+      # For Gmail as a transport, use: "gmail://username:password@localhost"
+      # For a generic SMTP server, use: "smtp://localhost:25?encryption=&auth_mode="
+      # Delivery is disabled by default via "null://localhost"
+      MAILER_URL: 'null://localhost'
+      ###< symfony/swiftmailer-bundle ###

build/container/dev/php.ini

@@ -0,0 +1 @@
+memory_limit = 1024M

build/container/dev/xdebug.ini

@@ -0,0 +1,35 @@
+zend_extension = xdebug.so
+
+xdebug.var_display_max_depth = 5
+xdebug.var_display_max_data = 250
+xdebug.var_display_max_children = 5
+xdebug.max_nesting_level = 250
+xdebug.cli_color = 1
+xdebug.show_exception_trace = 0
+xdebug.dump_globals = 1
+xdebug.dump_once = 1
+xdebug.show_local_vars = 1
+
+xdebug.remote_autostart = 1            ; If 0, CLI debug will not work. If 1, always try to start a remote debugging session and connect to a client, regardless of the GET/POST/COOKIE variable being present.
+xdebug.remote_enable = 1               ; trigger: cookie:XDEBUG_SESSION_START=PHPSTORM
+xdebug.remote_host = '172.17.0.1'      ; Host where the debug client is running, you can either use a host name, IP address, or 'unix:///path/to/sock' for a Unix domain socket. This setting is ignored if xdebug.remote_connect_back is enabled.
+xdebug.remote_connect_back = 0         ; If enabled, the xdebug.remote_host setting is ignored and Xdebug will try to connect to the client that made the HTTP request. This setting does not apply for debugging through the CLI
+xdebug.remote_port = 9000
+xdebug.remote_handler = dbgp
+xdebug.remote_mode = req
+
+xdebug.profiler_enable = 0
+xdebug.profiler_enable_trigger = 1     ; trigger: cookie:XDEBUG_PROFILE => 1
+xdebug.profiler_output_dir = '/tmp'
+xdebug.profiler_output_name = "%H.profiler"
+
+xdebug.auto_trace = 0
+xdebug.trace_enable_trigger = 1        ; trigger: cookie:XDEBUG_TRACE => 1
+xdebug.trace_options = 0
+xdebug.trace_format = 2
+xdebug.trace_output_dir = '/tmp'
+xdebug.trace_output_name = "%H.trace"
+xdebug.collect_params = 4
+xdebug.collect_return = 1
+
+xdebug.idekey = "PHPSTORM"

build/container/docker-compose.yml

@@ -0,0 +1,10 @@
+version: '3.2'
+
+services:
+  app:
+    image: hgraca/explicit-architecture:app.sfn.base
+    container_name: app.sfn.base
+    working_dir: /opt/app
+    build:
+      context: ../../
+      dockerfile: ./build/container/app.base.dockerfile