Desk Crisim

This repository holds the source code of the crisis simulation Game: Desk CriSim. Desk CriSim is a web application that allows students to simulate crisis situations. Teachers can assign students as certain actors in a crisis situation and monitor the choices that the students make on events that happen during a crisis.

Table of contents

• The Development Team
• Setup a docker container
• Installing
  • Read detailed instructions on:
• Quick setup
  • Step 1
  • Step 2
  • Step 3
  • Step 4
• Running
  • Yarn
  • Php webserver from the commandline:
• Required Dependencies
  • Required Php modules:
• ❤️ Proudly build with open-source technology:
• A few notes referenced above
• Known issues
• Licencing

The Development Team

• Back-end:
  • Planner Lennart Pikijn 📧
  • secondary lead Niek Luttikhof 📧
  • Repository Manger Joris Rietveld 📧
• Front-end:
  • secretary Soner Mulder 📧
  • Project Lead Sander Paping 📧

Setup a docker container

You could run everything in a Docker Container this way you don't have to install everything by hand and are guaranteed to have everything setup properly. See our instructions for more information about installing Docker.

Installing

To much text, take me to the quick setup!

The application is platform independent and should run on Linux 🐧, Mac OS and even on windows. However our production server and automated tests (Unit tests, security tests, continues integration and code quality tests) run on Linux servers (specifically: Ubuntu 18.04/18.10) .

This means that it is guarantied to work on Linux, because we would catch the failing builds. This is also our initial target setup for the production server. It should also work on any unix-like operating system like BSD or Mac OSX but you should validate that your php version is compiled with the same arguments as the version in the ubuntu repositories and that you have the correct php extensions installed.

The main programming language of the project is PHP and Java script, but also builds on: (X)HTML, Twig, Markdown, XML, CSS and SCSS mainly for the presentation of the application. For faster development we choose to use the symfony framework instead of rolling our own. This means that the project has to install several dependencies in order to run. Composer is a widely used dependency manager for PHP that can install the required dependencies using the configuration in ./composer.json see this for information about installing composer.

For loading, pre-processing and compiling the front-end components we use the webpack and the yarn package manager based on nodeJS. It is not required to be installed on a production server but it is certainly easier to install or update the application later on.

Storing data can be done on every database server that is compatible with doctrine ORM by configuring your database connection parameters in .local.env or by setting them as environment variables. Make sure that you don't include them in version control! during development we use MySQL 5.7 but any later version will do, previous versions are also possible but require you to alter the doctrine settings because 5.7 introduced the json field type that is used in the application.

Because the routes in the application are dynamically matched inside of the application, it needs a rewrite capable web server like: Nginx or apache (with mod_rewrite) including some with special configuration for it to function properly.

Read detailed instructions on:

• Working with version controll
  • Cloning, updating, pushing and pulling
  • Cloning for production
  • Forking for development
    • Updating your fork
  • Committing and pushing
  • Creating a pull request
• The structure of the project
  • Where is index.php?
    • Front Controller and url rewriting
    • Public assets
      • Webpack, webpack encore and babel
      • Images
      • CSS prepossessing and scss
  • Security
    • Webserver rules
    • Symfony Firewall & environment variables
    • Securing the database
  • Testing
    • Travis CI
    • PHP Unit
    • Code Climate
• development_in_docker
  • The problem with every other developer
    • So... hire a separate team that builds build scripts?
  • Installing Docker
    • Installing Docker on Linux 🐧
      • Adding apt over HTTPS (required to talk to there repo)
      • Add and verify the official GBG key
      • Add the repository and install Docker CE
      • Verify our hard work
      • (Optionally) Post-installation steps for Linux
      • (Optionally) Configure Docker to start on boot
    • Installing Docker on MacOS
      • Running on MacOS
    • Installing Docker on Windows
      • Running the desktop app
    • Installing Docker Compose
  • Getting a develop environment
• Migrating the project to production
  • Connection to the production server
    • Connecting over SSH
    • Configuring ssh keys instead of a password
    • Connection with FTP
    • Connection with FTP over SSH _(SFTP)__
    • Configuring PHPStorm deployment server over SFTP
    • Connect to the database with the MySQL Workbench
    • Connect to the database with Datagrip & PhpStrom
  • Installing PHP and the required PHP extensions
  • Installing a database server
  • Installing a web server
  • Installing the dependency managers
  • Installing the dependencies
  • Generating web assets
• Setting up the development tools
  • PhpStrom IDE
    • Installing additional plugins in PHPStrom
    • Setting up Docker run configuration.
  • Setting up testing (Unit tests, Security tests and Continues Integration
    • Testing Locally
    • Testing Remotely With Travis CI
    • Checking the code quality

Quick setup

Step 1

First clone the repository from github:

$ git clone https://github.com/jorisrietveld/Desk-Crisim.git

Step 2

After that change the directory to the project root:

$ cd Desk-Crisim

Step 3

Now install the required composer dependencies:

$ composer install

Step 4

and for the front-end packages, run:

$ yarn install
$ yarn run encore --dev

Running

Yarn

I have created several yarn scripts to run webpack and php servers for development. To run webpack for asset compilation run webpack-run from PhpStorm or with the commandline:

$ yarn run webpack-run

To watch files (watch for change) and automatic re compilation run webpack-watch from PhpStorm or with the commandline:

$ yarn run webpack-watch

To stop watching the assets run webpack-watch from PhpStorm or with the commandline:

$ webpack-unwatch

Php webserver from the commandline:

To run the php buildin webserver from the command-line, you can run:

$ bin/console server:run    # Optionally add a ip:port like, 127.0.0.1:8000
$ bin/console server:start  # Same as run, but runes in th background.
# or on windows:
$ php bin/console server:run
$ php bin/console server:start

To terminate the process when server:run is used you can just press crtl+c to exit, alternatively run:

$ bin/console server:stop
# or on windows:
$ php bin/console server:stop

Required Dependencies

You could also run everything in a Docker Container this way you don't have to install everything by hand and are guaranteed to have everything setup properly. See our instructions on how to install and configure Docker.

• PHP >=7.2

  compiled with the –with-password-argon2, see this for an explanation. >there are knows issues

  • Required Php modules:

  Required Php Modules Needs to be reviewed, not everything is required!
  php-amqp	php-fpm	php-xdebug	php7.2-dev	php7.2-soap
  php-apcu	php-intl	php-xml	php7.2-fpm	php7.2-xml
  php-apcu-bc	php-json	php-xmlrpc	php7.2-intl	php7.2-xmlrpc
  php-cli	php-mbstring	php-zip	php7.2-json	php7.2-zip
  php-common	php-mongodb	php7.2-cli	php7.2-mbstring	php7.2-mysql
  php-curl	php-pear	php7.2-common	php7.2-opcache
  php-dev	php-soap	php7.2-curl	php7.2-readline

• Composer - A PHP Dependency manager.

• NodeJS - A port of the V8 javascript engine to run JS applications natively.

• NPM - The default nodeJS package manager.

• Yarn - A much faster and cached version of NPM.

• Webservers:

  • Nginx - A powerful
  • Apache
  • IIS ‼️ currently not supported, will require intermediate knowledge.

• Database servers:

  • Mysql >= 5.7 or MariaDB
  • >= SQL Server
  • >= Postgre
  • >= SQLite

❤️ Proudly build with open-source technology:

• Linux
• Ubuntu
• PHP
• Nginx
• Composer
• NodeJS
• NPM
• Symfony Framework
• Doctrine
• Docker
• Webpack
• Sass
• Travis Ci
• Yarn

A few notes referenced above

• Notes about the requirements
  • Why use Php 7.2 compiled with the –with-password-argon2 flag? It is also possible

    (But not recommended) to run the application without argon2 and falling back to the previous php hashing standard BCrypt. Its not unsafe but argon2 will be the next standard because it offers better protection against a few specific attacks., and was the winner of a password hashing competition. If you still want to you to change the password hashing configuration change the following in ./config/bundles/security.yaml Replace the line algorithm: argon2 to algorithm: BCrypt.

Known issues

Known issues in the project, please open a issue and if it is confirmed I will add it in this list, so I can investigate and patch it

PHP segfault

• The bin/console server:run command or the php daemon crashes when when a web page is served to the client.

  If you don't change the algorithm: argon2 line to algorithm: bcrypt when running a Php version that is compiled without the -with-password-argon2 flag (libsodium). it will execute seeming without problems, but it will crash (Segfault) your entire php process when a page is served (sometimes it serves a error page with an unrelated error message and then segfault on the second request, Still figuring out what causes this, it should not be possible).

Licencing

Desk CriSim - A crisis simulation Game. Copyright (C) 2018 Members of the INF2H project group

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

---

This page (the documentation) is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.