docker-development.md

Development in docker environment

Purpose of this document is to describe how to set up and use the application in docker environment.

Table of contents

• Installation
• Testing

Installation

The application comes with a built-in containerized development environment built on top of OAT Docker Stack. In order to install it please follow the installation steps in it's README file.

Next step is to create your .env.local file in application root directory.

$ printf '%s\n%s\n' 'COMPOSER_AUTH={"github-oauth":{"github.com":"your token here"}}' 'COMPOSER_HOME=~/.composer' >> .env.local

Then update your Composer settings such as path to your COMPOSER_HOME and COMPOSER_AUTH GitHub credentials.

It should look something like this:

COMPOSER_AUTH={"github-oauth":{"github.com":"your token here"}}
COMPOSER_HOME=~/.composer

The application uses JWT tokens for API authentication. You must generate your private/public keypair to make it work.

To generate private key:

$ docker container exec -it simple-roster-phpfpm openssl genpkey -aes-256-cbc -algorithm RSA -pass pass:devpassphrase -out config/secrets/docker/jwt_private.pem

To generate public key:

$ docker container exec -it simple-roster-phpfpm openssl pkey -in config/secrets/docker/jwt_private.pem -passin pass:devpassphrase -out config/secrets/docker/jwt_public.pem -pubout

The rest of the configuration is pre-configured with the .env.docker file, so next step is to set up the containers:

$ docker-compose --env-file .env.local up -d

Then install application dependencies:

$ docker container exec -it simple-roster-phpfpm composer install

The following section is optional and is applicable only if you are using OAT Docker Stack. In order to install it please follow the installation steps in it's README file.

The application is NOT exposed on any port by default. It be automatically available at https://simple-roster.docker.localhost DNS host. If your system cannot resolve the domain, you might want to check this article about how to redirect .docker.localhost DNS queries to your localhost.

Testing

PHPUnit

To run the full test suite execute:

$ docker container exec -it simple-roster-phpfpm bash -c "source .env.test && bin/phpunit"

To run the full test suite with all the necessary coverage reports (for Infection and coverage checker):

$ docker container exec -it simple-roster-phpfpm bash -c "source .env.test && XDEBUG_MODE=coverage bin/phpunit --coverage-xml=var/log/phpunit/coverage/coverage-xml --coverage-clover=var/log/phpunit/coverage.xml --log-junit=var/log/phpunit/coverage/junit.xml"

Tip: If you receive an error message about not finding the bootstrap files:

(bin/.phpunit/phpunit-8.3-0/vendor/composer/../symfony/phpunit-bridge/bootstrap.php): failed to open stream: No such file or directory ...)

try to delete the autogenerated phpunit folder:

$ docker container exec -it simple-roster-phpfpm rm -rf bin/.phpunit

and execute the command again.

Infection

To run infection suite execute:

$ docker container exec -it simple-roster-phpfpm bash -c "source .env.test && XDEBUG_MODE=coverage vendor/bin/infection --threads=$(nproc)"

Tip: If you receive an error message about not finding the bootstrap files:

(bin/.phpunit/phpunit-8.3-0/vendor/composer/../symfony/phpunit-bridge/bootstrap.php): failed to open stream: No such file or directory ...)

try to delete the autogenerated phpunit folder:

$ docker container exec -it simple-roster-phpfpm rm -rf bin/.phpunit

and execute the command again.

To run infection suite without re-running the entire test suite every time:

Make sure tests are in passing state and coverage report is generated:

$ docker container exec -it simple-roster-phpfpm bash -c "source .env.test && XDEBUG_MODE=coverage bin/phpunit --coverage-xml=var/log/phpunit/coverage/coverage-xml --log-junit=var/log/phpunit/coverage/junit.xml"

Then run infection and provide the coverage xml files as parameters:

$ docker container exec -it simple-roster-phpfpm bash -c "source .env.test && vendor/bin/infection --threads=$(nproc) --skip-initial-tests --coverage=var/log/phpunit/coverage"

Tip 1: If you want to run infection against individual files, you can use the --filter option.

Tip 2: If you want to run infection only on changed files, you can use the --git-diff-filter option.