brainbitsgmbh/dist repository overview

⁠dist script wrappers

⁠Installation

docker run -it --rm -v $PWD:/app brainbitsgmbh/dist:latest /dist/sync

After successful installation of the wrapper scripts you can use the bin/wrapper/dist-sync script instead of the docker-call.

Required configuration values:

• Gitlab project path: Gitlab project path, e.g. docker/dist
• Exposed port: Exposed port, only needed when using server scripts
• Container port: Internal container port, only needed when using server scripts
• Devtools image: Devtools image to be used. Replace with project-devtools when needed
• App image: Application image to be build
• Checks: Check-scripts that are run by bin/all-checks
• Warning Checks: Check-scripts that only produce a warning on failure.

⁠Local includes

• bin/local/include-all-checks Included in bin/all-checks script
• bin/local/include-build Included in bin/image/build script
• bin/local/include-build-post Included at the end of bin/image/build script
• bin/local/include-composer Included in bin/composer script
• bin/local/include-config Included in config, see Local config
• bin/local/include-server Included in all server-scripts that start/run the server
• bin/local/include-server-run Included in all server-scripts that run the server
• bin/local/include-server-run-blackfire Included in all server-scripts that run the server with blackfire
• bin/local/include-server-run-debug Included in all server-scripts that run the server with debug
• bin/local/include-server-run-prod Included in all server-scripts that run the server in prod mode
• bin/local/include-server-start Included in all server-scripts that start the server
• bin/local/include-server-stop Included in all server-scripts that stop the server

It is possible to create user specific overrides for every include script. The file name of the user specific include script has to end with the postfix -user, e.g. bin/local/include-config-user.

Add the user specific include scripts to your .gitignore file.

/bin/local/include-*-user

⁠Local config

⁠Composer authentication

The wrapper scripts support composer repository authentication, either with env vars, or with a local composer auth.json.

• COMPOSER_AUTH_ENABLED=1 Enable composer authentication
• COMPOSER_AUTH_REPO=<host> Hostname for composer repository credentials
• COMPOSER_AUTH_USER=<username> Username for composer repository credentials
• COMPOSER_AUTH_PASSWORD=<password> Password for composer repository credentials

When authentication is enabled, and all 3 vars COMPOSER_AUTH_REPO, COMPOSER_AUTH_USER and COMPOSER_AUTH_PASSWORD are set, they are used to generate a COMPOSER_AUTH env var, with the json formatted credetials. Alternatively, if the vars are not set, a local composer auth.json is used from $HOME/.composer/auth.json. When the auth.json file is not found, an error will be raised.

When building with enabled authentication and a auth.json is used, a mount secret with id composer-auth-json is provided, which can be mounted to /composer/auth.json in the build container. See https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information⁠ for further information.

⁠Tool flavors

In bin/local/include-config you can configure which tool will be used for checks and generators.

• APIDOC=[phpdocumentor|sami] (default=phpdocumentor) Choose generate/apidoc tool
• CODE_STYLE=[phpcs|phpcs-baseline] (default=phpcs) Choose check/code-style tool
• SECURITY=[local-php-security-checker|symfony] (default=phpstan) Choose check/security tool
• STATIC_ANALYSIS=[phpstan|psalm] (default=phpstan) Choose check/static-analysis tool
• TESTS_COVERAGE=[xdebug|phpdbg|pcov] (default=pcov) Choose check/tests-coverage tool
• KARATE_TEST_DIR= (default=/app/e2e) Set directory containing karate-dsl test cases

⁠Install flags (FLAGS config)

• +server Install server scripts
• +symfony Install symfony related scripts
• +composer Install composer related scripts
• +licenses Install license related scripts
• +end-to-end Install end-to-end-testing scripts
• +acceptance Install acceptance-testing scripts
• +renovate Install renovate scripts
• +automation Install automation scripts
• +scan-image Install scan-image scripts

⁠Required env vars for wrapper-scripts

⁠bin/wrapper/dist-bot

• GITLAB_TOKEN=<token> with <token> being a valid gitlab api token

⁠bin/wrapper/klar

• KLAR_USER=<username> with <username> being the username of a user which is allowed to access the docker registry
• KLAR_PASSWORD=<password> with <password> being the password of a user which is allowed to access the docker registry

⁠bin/wrapper/renovate

• GITLAB_TOKEN=<token> with <token> being a valid gitlab api token

⁠Available env vars for check-scripts

⁠bin/check/code-style

• CODE_STYLE_REPORT_FILE=<file> with <file> being a gitlab-compatible codequaltity-report-file, e.g. CODE_STYLE_REPORT_FILE=build/codequality-phpcs.json

⁠bin/check/scan-source

• TSFINDER_DIRS=<dir1> ... <dirN> with <dir1> ... <dirN> only given directories are scanned, e.g. TSFINDER_DIRS="src tests vendor"
• TSFINDER_EXCLUDES_FILE=<file> with <file> being a text file containing one path per line to exclude, e.g. TSFINDER_EXCLUDES_FILE=.tsfinder-excludes

⁠bin/check/static-analysis

• STATIC_ANALYSIS_REPORT_FILE=<file> with <file> being a gitlab-compatible codequaltity-report-file, e.g. STATIC_ANALYSIS_REPORT_FILE=build/codequality-phpstan.json

⁠bin/check/tests

• TESTS_REPORT_FILE=<file> with <file> being a gitlab-compatible junit-report-file, e.g. TESTS_REPORT_FILE=build/junit-phpunit.xml

⁠bin/check/tests-coverage

• TESTS_REPORT_FILE=<file> with <file> being a gitlab-compatible junit-report-file, e.g. TESTS_REPORT_FILE=build/junit-phpunit.xml
• TESTS_COVERAGE_DIR=<dir>: with <dir> being directory for the html-code-coverage-report, e.g. TESTS_COVERAGE_DIR=build/coverage

⁠Unmanaged files

Calling /dist/sync will show a list of unmanaged files in bin/. Unmanaged files are all files that are not installed via dist. To suppress output of well known files, create a file bin/.dist-ignore and enter a glob pattern on each line, relative from bin/. Each glob pattern will be expanded and removed fromn the list of unmanaged files.

Example:

# bin/.dist-ignore
console
image/*-fpm
image/*-nginx
ops
stack

This would exclude the following example files:

• bin/console
• bin/image/build-nginx
• bin/image/test-fpm
• bin/image/test-nginx
• bin/stack/start
• bin/stack/stop
• bin/stack/run/import
• bin/ops/production/deploy
• bin/ops/staging/status