restructure of DEVELOPMENT.md and adding the new port 5080 localhost to it
This commit is contained in:
Xu
Igor Scheller
parent
ccdf1aa8d5
commit
21eafb7d26
221
DEVELOPMENT.md
221
DEVELOPMENT.md
|
|
@ -8,35 +8,16 @@ Please also read the [CONTRIBUTING.md](CONTRIBUTING.md).
|
|||
* Yarn (Development/Building only)
|
||||
* PHP Composer (Development/Building only)
|
||||
|
||||
## Local build
|
||||
The following instructions explain how to get, build and run the latest Engelsystem version directly from the git main branch (may be unstable!).
|
||||
|
||||
* Clone the main branch: `git clone https://github.com/engelsystem/engelsystem.git`
|
||||
* Install [Composer](https://getcomposer.org/download/) and [Yarn](https://yarnpkg.com/en/docs/install) (which requires [Node.js](https://nodejs.org/en/download/package-manager/))
|
||||
* Install project dependencies:
|
||||
```bash
|
||||
composer install
|
||||
yarn
|
||||
```
|
||||
On production systems it is recommended to use
|
||||
```bash
|
||||
composer install --no-dev
|
||||
composer dump-autoload --optimize
|
||||
```
|
||||
to install the Engelsystem
|
||||
* Build the frontend assets
|
||||
* All
|
||||
```bash
|
||||
yarn build
|
||||
```
|
||||
* Specific themes only by providing the `THEMES` environment variable, e.g.
|
||||
```bash
|
||||
THEMES=0,1 yarn build
|
||||
```
|
||||
* Generate translation files
|
||||
```bash
|
||||
find resources/lang/ -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \;
|
||||
```
|
||||
## Code style
|
||||
Please ensure that your pull requests follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) coding style guide.
|
||||
You can check that by running
|
||||
```bash
|
||||
composer run phpcs
|
||||
```
|
||||
You may auto fix reported issues by running
|
||||
```bash
|
||||
composer run phpcbf
|
||||
```
|
||||
|
||||
## Pre-commit hooks
|
||||
You should set up the pre-commit hook to check the code style and run tests on commit:
|
||||
|
|
@ -54,87 +35,10 @@ Host machine:
|
|||
ln -s ../../bin/pre-commit .git/hooks/pre-commit
|
||||
```
|
||||
|
||||
|
||||
## Testing
|
||||
To run the unit tests use
|
||||
```bash
|
||||
vendor/bin/phpunit --testsuite Unit
|
||||
```
|
||||
|
||||
If a database is configured and the Engelsystem is allowed to mess around with some files, you can run feature tests.
|
||||
The tests can potentially delete some database entries, so they should never be run on a production system!
|
||||
```bash
|
||||
vendor/bin/phpunit --testsuite Feature
|
||||
# or for unit- and feature tests:
|
||||
vendor/bin/phpunit
|
||||
```
|
||||
|
||||
To run code coverage reports its highly recommended to use [`pcov`](https://github.com/krakjoe/pcov) or
|
||||
at least `phpdbg -qrr`(which has problems with switch case statements) as using Xdebug slows down execution.
|
||||
```bash
|
||||
php -d pcov.enabled=1 -d pcov.directory=. vendor/bin/phpunit --testsuite Unit --coverage-text
|
||||
```
|
||||
|
||||
### Var Dump server
|
||||
Symfony Var Dump server is configured to allow for easier debugging. It is not meant as a replacement for xdebug but can actually be used together with xdebug.
|
||||
This Var Dump Server is especially useful for when you want to debug a request without messing up the output e.g API calls ot HTML layout.
|
||||
|
||||
To use simply call the method `dump` and pass the arguments in exactly the same way you would when using `var_dump`.
|
||||
|
||||
This will send the output to the Var Dump server which can be viewed in the terminal.
|
||||
This does however require that you start the var-dump-server otherwise the output will be printed in your browser
|
||||
|
||||
You can also `dump` and `die` if you wish to not let your code continue any further by calling the `dd` method
|
||||
|
||||
To view the output of `dump` call the following commands:
|
||||
|
||||
```bash
|
||||
vendor/bin/var-dump-server
|
||||
# or for running in docker
|
||||
docker-compose exec es_server vendor/bin/var-dump-server
|
||||
```
|
||||
|
||||
For more information check out the Var Dump Server documentation: [Symfony VarDumper](https://symfony.com/components/VarDumper)
|
||||
|
||||
## Translation
|
||||
We use gettext. You may use POEdit to extract new texts from the sourcecode.
|
||||
Please config POEdit to extract also the twig template files using the following settings: https://gist.github.com/jlambe/a868d9b63d70902a12254ce47069d0e6
|
||||
|
||||
## Code style
|
||||
Please ensure that your pull requests follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) coding style guide.
|
||||
You can check that by running
|
||||
```bash
|
||||
composer run phpcs
|
||||
```
|
||||
You may auto fix reported issues by running
|
||||
```bash
|
||||
composer run phpcbf
|
||||
```
|
||||
|
||||
## CI & Build Pipeline
|
||||
|
||||
The Engelsystem can be tested and automatically deployed to a testing/staging/production environment.
|
||||
This functionality requires a [GitLab](https://about.gitlab.com/) server with a working docker runner.
|
||||
|
||||
To use the deployment features the following secret variables need to be defined (if undefined the step will be skipped):
|
||||
```bash
|
||||
SSH_PRIVATE_KEY # The ssh private key
|
||||
STAGING_REMOTE # The staging server, e.g. user@remote.host
|
||||
STAGING_REMOTE_PATH # The path on the remote server, e.g. /var/www/engelsystem
|
||||
PRODUCTION_REMOTE # Same as STAGING_REMOTE but for the production environment
|
||||
PRODUCTION_REMOTE_PATH # Same as STAGING_REMOTE_PATH but for the production environment
|
||||
```
|
||||
|
||||
## Static code analysis
|
||||
|
||||
You can run a static code analysis with this command:
|
||||
|
||||
```bash
|
||||
composer phpstan
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
We suggest using Docker for the Development local build.
|
||||
|
||||
If unspecific issues appear try using Docker version >= 20.10.14.
|
||||
|
||||
This repo [ships a docker setup](docker/dev) for a quick development start.
|
||||
|
|
@ -180,6 +84,107 @@ docker-compose exec es_workspace yarn build:watch
|
|||
docker-compose exec -e THEMES=0,1 es_workspace yarn build:watch
|
||||
```
|
||||
|
||||
## Localhost
|
||||
You can find yout local Engelsystem on [http://localhost:5080](http://localhost:5080).
|
||||
|
||||
## Local build without Docker
|
||||
The following instructions explain how to get, build and run the latest Engelsystem version directly from the git main branch (may be unstable!).
|
||||
|
||||
* Clone the main branch: `git clone https://github.com/engelsystem/engelsystem.git`
|
||||
* Install [Composer](https://getcomposer.org/download/) and [Yarn](https://yarnpkg.com/en/docs/install) (which requires [Node.js](https://nodejs.org/en/download/package-manager/))
|
||||
* Install project dependencies:
|
||||
```bash
|
||||
composer install
|
||||
yarn
|
||||
```
|
||||
On production systems it is recommended to use
|
||||
```bash
|
||||
composer install --no-dev
|
||||
composer dump-autoload --optimize
|
||||
```
|
||||
to install the Engelsystem
|
||||
* Build the frontend assets
|
||||
* All
|
||||
```bash
|
||||
yarn build
|
||||
```
|
||||
* Specific themes only by providing the `THEMES` environment variable, e.g.
|
||||
```bash
|
||||
THEMES=0,1 yarn build
|
||||
```
|
||||
* Generate translation files
|
||||
```bash
|
||||
find resources/lang/ -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \;
|
||||
```
|
||||
|
||||
## Testing
|
||||
To run the unit tests use
|
||||
```bash
|
||||
vendor/bin/phpunit --testsuite Unit
|
||||
```
|
||||
|
||||
If a database is configured and the Engelsystem is allowed to mess around with some files, you can run feature tests.
|
||||
The tests can potentially delete some database entries, so they should never be run on a production system!
|
||||
```bash
|
||||
vendor/bin/phpunit --testsuite Feature
|
||||
# or for unit- and feature tests:
|
||||
vendor/bin/phpunit
|
||||
```
|
||||
|
||||
To run code coverage reports its highly recommended to use [`pcov`](https://github.com/krakjoe/pcov) or
|
||||
at least `phpdbg -qrr`(which has problems with switch case statements) as using Xdebug slows down execution.
|
||||
```bash
|
||||
php -d pcov.enabled=1 -d pcov.directory=. vendor/bin/phpunit --testsuite Unit --coverage-text
|
||||
```
|
||||
|
||||
### Var Dump server
|
||||
Symfony Var Dump server is configured to allow for easier debugging. It is not meant as a replacement for xdebug but can actually be used together with xdebug.
|
||||
This Var Dump Server is especially useful for when you want to debug a request without messing up the output e.g API calls ot HTML layout.
|
||||
|
||||
To use simply call the method `dump` and pass the arguments in exactly the same way you would when using `var_dump`.
|
||||
|
||||
This will send the output to the Var Dump server which can be viewed in the terminal.
|
||||
This does however require that you start the var-dump-server otherwise the output will be printed in your browser
|
||||
|
||||
You can also `dump` and `die` if you wish to not let your code continue any further by calling the `dd` method
|
||||
|
||||
To view the output of `dump` call the following commands:
|
||||
|
||||
```bash
|
||||
vendor/bin/var-dump-server
|
||||
# or for running in docker
|
||||
docker-compose exec es_server vendor/bin/var-dump-server
|
||||
```
|
||||
|
||||
For more information check out the Var Dump Server documentation: [Symfony VarDumper](https://symfony.com/components/VarDumper)
|
||||
|
||||
## Translation
|
||||
We use gettext. You may use POEdit to extract new texts from the sourcecode.
|
||||
Please config POEdit to extract also the twig template files using the following settings: https://gist.github.com/jlambe/a868d9b63d70902a12254ce47069d0e6
|
||||
|
||||
|
||||
## CI & Build Pipeline
|
||||
|
||||
The Engelsystem can be tested and automatically deployed to a testing/staging/production environment.
|
||||
This functionality requires a [GitLab](https://about.gitlab.com/) server with a working docker runner.
|
||||
|
||||
To use the deployment features the following secret variables need to be defined (if undefined the step will be skipped):
|
||||
```bash
|
||||
SSH_PRIVATE_KEY # The ssh private key
|
||||
STAGING_REMOTE # The staging server, e.g. user@remote.host
|
||||
STAGING_REMOTE_PATH # The path on the remote server, e.g. /var/www/engelsystem
|
||||
PRODUCTION_REMOTE # Same as STAGING_REMOTE but for the production environment
|
||||
PRODUCTION_REMOTE_PATH # Same as STAGING_REMOTE_PATH but for the production environment
|
||||
```
|
||||
|
||||
## Static code analysis
|
||||
|
||||
You can run a static code analysis with this command:
|
||||
|
||||
```bash
|
||||
composer phpstan
|
||||
```
|
||||
|
||||
**Hint for using Xdebug with *PhpStorm***
|
||||
|
||||
For some reason *PhpStorm* is unable to detect the server name.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ services:
|
|||
APP_NAME: Engelsystem DEV
|
||||
env_file: deployment.env
|
||||
ports:
|
||||
- "5000:80"
|
||||
- "5080:80"
|
||||
networks:
|
||||
- database
|
||||
- internet
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ services:
|
|||
MYSQL_PASSWORD: engelsystem
|
||||
MYSQL_DATABASE: engelsystem
|
||||
ports:
|
||||
- "5000:80"
|
||||
- "5080:80"
|
||||
env_file: deployment.env
|
||||
networks:
|
||||
- database
|
||||
|
|
|
|||
Loading…
Reference in New Issue