2019-01-13 13:00:09 +01:00
[![pipeline status ](https://chaos.expert/engelsystem/engelsystem/badges/master/pipeline.svg )](https://chaos.expert/engelsystem/engelsystem/commits/master)
[![coverage report ](https://chaos.expert/engelsystem/engelsystem/badges/master/coverage.svg )](https://chaos.expert/engelsystem/engelsystem/commits/master)
2016-08-21 17:26:03 +02:00
[![Codacy Badge ](https://api.codacy.com/project/badge/Grade/20b3b0b4e93344a29da6bec77f329e7a )](https://www.codacy.com/app/engelsystem/engelsystem)
2016-08-24 17:58:39 +02:00
[![GPL ](https://img.shields.io/github/license/engelsystem/engelsystem.svg?maxAge=2592000 )]()
2016-08-21 17:24:04 +02:00
2017-07-16 18:41:57 +02:00
# Engelsystem
Please visit https://engelsystem.de for a feature list.
2017-12-04 13:25:44 +01:00
To report bugs use [engelsystem/issues ](https://github.com/engelsystem/engelsystem/issues )
2017-07-16 18:41:57 +02:00
## Installation
2019-01-13 13:00:09 +01:00
### Requirements
2018-10-01 18:30:13 +02:00
* PHP >= 7.1
2018-10-19 02:43:12 +02:00
* Required modules:
* gettext
* json
* PDO
2019-01-19 00:02:01 +01:00
* mysql
2018-10-19 02:43:12 +02:00
* xml/libxml/SimpleXML
2018-10-01 18:30:13 +02:00
* MySQL-Server >= 5.7.8 or MariaDB-Server >= 10.2.2
2017-07-16 18:41:57 +02:00
* Webserver, i.e. lighttpd, nginx, or Apache
2019-01-13 13:00:09 +01:00
### Additional requirements if you want to build the project by yourself
2018-05-03 17:33:49 +02:00
* Node >= 8 (Development/Building only)
* Yarn (Development/Building only)
2017-07-16 18:41:57 +02:00
2019-01-13 13:00:09 +01:00
### Download
#### Stable
* Go to the [Releases ](https://github.com/engelsystem/engelsystem/releases ) page and download the latest stable release file.
* Extract the files to your webroot and continue with the directions for configurations and setup.
2019-01-13 13:11:50 +01:00
#### Latest unstable
2019-01-13 13:00:09 +01:00
The following instructions explain how to get, build and run the latest engelsystem version directly from the git master branch (may be unstable!).
2017-07-16 18:41:57 +02:00
* Clone the master branch: `git clone https://github.com/engelsystem/engelsystem.git`
2018-08-03 05:09:11 +02:00
* 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/ ))
2017-12-04 13:25:44 +01:00
* Install project dependencies:
```bash
composer install
2018-05-03 17:33:49 +02:00
yarn
2017-12-04 13:25:44 +01:00
```
On production systems it is recommended to use
```bash
composer install --no-dev
2017-12-25 23:12:52 +01:00
composer dump-autoload --optimize
2017-12-04 13:25:44 +01:00
```
to install the engelsystem
2018-05-03 17:33:49 +02:00
* Build the frontend assets
```bash
yarn build
```
2018-05-03 18:06:54 +02:00
2019-01-13 13:00:09 +01:00
### Configuration and Setup
2018-11-24 16:27:49 +01:00
* The webserver must have write access to the ```import``` and ```storage``` directories and read access for all other directories
2018-01-28 14:29:13 +01:00
* The webserver must point to the ```public``` directory.
* The webserver must read the ```.htaccess``` file and ```mod_rewrite``` must be enabled
2017-07-16 18:41:57 +02:00
* Recommended: Directory Listing should be disabled.
* There must a be MySQL database created with a user who has full rights to that database.
2018-01-28 14:29:13 +01:00
* If necessary, create a ```config/config.php``` to override values from ```config/config.default.php```.
2018-10-27 12:11:37 +02:00
* To remove values from the `footer_items` , `available_themes` , `locales` , `tshirt_sizes` or `headers` lists the config file has to be renamed.
2019-01-13 13:05:07 +01:00
* To import the database the ```bin/migrate``` script has to be called. If you are not allowed to execute scripts, then execute the ```install-< version > .sql``` script. Download at [Releases ](https://github.com/engelsystem/engelsystem/releases ) page.
2018-01-28 14:29:13 +01:00
* In the browser, login with credentials ```admin```:```asdfasdf``` and change the password.
2017-07-16 18:41:57 +02:00
Engelsystem can now be used.
2005-11-06 18:24:58 +01:00
2017-07-16 18:41:57 +02:00
### Session Settings:
* Make sure the config allows for sessions.
* Both Apache and Nginx allow for different VirtualHost configurations.
2014-11-12 19:45:55 +01:00
2017-07-16 18:41:57 +02:00
## Development
Since the engelsystem is open source, you can help to improve the system. We really love to get pull requests containing fixes or implementations of our Github issues.
2007-11-04 16:52:25 +01:00
2017-07-16 18:41:57 +02:00
Please create single pull requests for every feature instead of creating one big monster of pull request containing a complete rewrite.
2015-08-26 14:11:08 +02:00
2017-12-04 13:25:44 +01:00
### Testing
To run the unit tests use
```bash
vendor/bin/phpunit --testsuite Unit
```
2018-10-01 18:30:13 +02:00
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!
2017-12-04 13:25:44 +01:00
```bash
vendor/bin/phpunit --testsuite Feature
# or for unit- and feature tests:
vendor/bin/phpunit
```
### 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 running docker minion.
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
2018-08-03 05:09:11 +02:00
STAGING_REMOTE_PATH # The path on the remote server, e.g. /var/www/engelsystem
2017-12-04 13:25:44 +01:00
PRODUCTION_REMOTE # Same as STAGING_REMOTE but for the production environment
PRODUCTION_REMOTE_PATH # Same as STAGING_REMOTE_PATH but for the production environment
```
2018-08-12 16:23:35 +02:00
### Docker container
To build the `engelsystem` and the `engelsystem-nginx` container:
```bash
cd contrib
docker-compose build
```
or to build the containers separately
```bash
docker build -f contrib/nginx/Dockerfile . -t engelsystem-nginx
2018-09-23 14:18:24 +02:00
docker build -f contrib/Dockerfile . -t engelsystem
2018-08-12 16:23:35 +02:00
```
2018-08-12 19:20:26 +02:00
Import database
```bash
2018-10-01 18:30:13 +02:00
docker exec -it engelsystem bin/migrate
2018-08-12 19:20:26 +02:00
```
2018-08-07 16:47:47 +02:00
#### Scripts
##### bin/deploy.sh
The `bin/deploy.sh` script can be used to deploy the engelsystem. It uses rsync to deploy the application to a server over ssh.
2017-12-04 13:25:44 +01:00
2018-08-07 16:47:47 +02:00
For usage see `./bin/deploy.sh -h`
2017-12-04 13:25:44 +01:00
2018-08-30 16:07:50 +02:00
##### bin/migrate
The `bin/migrate` script can be used to import and update the database of the engelsystem.
2018-09-03 21:56:49 +02:00
For more information on how to use it call `./bin/migrate help`
2018-08-30 16:07:50 +02:00
2017-07-16 18:41:57 +02:00
### Codestyle
Please ensure that your pull requests follow [PSR-2 ](http://www.php-fig.org/psr/psr-2/ ) and [PSR-4 ](http://www.php-fig.org/psr/psr-4/ ).