Skip to content
Snippets Groups Projects

mDIS Project

frontend coverage

backend coverage

This project is merging two frontend and backend technology together in the same repository. It uses Yii2 and Vue in order to get the most benefit from both frameworks.

The template contains the basic features including user login/logout and a contact page. It includes all commonly used configurations that would allow you to focus on adding new features to your application.

DIRECTORY STRUCTURE

The application structure is similar to a Vue project created by the vue-cli with the command vue create <app name>. There are two remarkable differences:

  • an extra backend directory that contains Yii2 code,

  • the dist folder (containing the build version) was renamed to web.

    +-- backend                 Yii2 Code (Server Side / API)
    |   +-- assets/              Assets definition
    |   +-- behaviors/           Special-Purpose Calculation, e.g. IGSN, AutoIncr
    |   +-- bin/                 Command line scripts (e.g. for auto printing reports)
    |   +-- commands/            yii console commands (controllers)
    |   +-- components/          Several components and helpers used elsewhere
    |   +-- config/              Application configurations (web, db backends, igsn, ldap, ...)
    |   +-- controllers/         Web controller classes
    |   +-- data/                Uploaded files (associated to database table archive_file)
    |   +-- dis_migration/       Migration classes for Legacy DIS import
    |   +-- dis_templates/       Json files defining models and forms as Json files
    |       +-- defaults/        Default models and forms 
    |       +-- forms/           Customized form templates (initially copied from defaults/forms) 
    |       +-- models/          Customized model templates (initially copied from defaults/models) 
    |   +-- forms/               Form PHP classes
    |   +-- models/              Model PHP classes that can be customized
    |       +-- base/            Base model PHP classes (twoway-data bindings) automatically generated from template manager
    |       +-- core/            Core model PHP classes
    |   +-- modules/             Modules (Code Generator as an example)
    |       +-- api/             Rest API used from frontend and elsewhere to access data
    |       +-- cg/              Code generator to create PHP model and vue form files
    |   +-- rbac/                Specialisations for user and rights management
    |   +-- reports/             Report-, export- and action scripts called from forms
    |   +-- resources/           Overriden data model classes for the API (User.php)
    |   +-- runtime/             Files generated during runtime (cache, logs, debug info...)
    |   +-- vendor/              Dependent 3rd-party PHP packages
    |   +-- views/               View files for the Web application
    |   +-- widgets/             General purpose components (Alert.php)
    +-- public                   Public static assets (index.html, index.php, favicons)
    +-- src                      Vue source code
    |   +-- assets               Logos, etc.
    |   +-- components           Display components and input components
    |   +-- forms                Input forms generated from template manager or customized
    |   +-- mixins               Input validators (not really components or screens)
    |   +-- pages                Screens: Login, CoreSection, Dashboard
    |   +-- plugins              User interface components, like vuetify.js
    |   +-- services             BackendService (Auth), CrudService (data manipulation), etc.
    |   +-- store                State management like: is logged in, isDark, snackbar, ...
    |   +-- style                Stylus directives, will be compiled to css
    |   +-- util                 Utility javascripts 
    +-- tests                    Frontend tests
    +-- web                      Output folder for command `npm run build` + customized logos, etc.

REQUIREMENTS

The minimum requirement by this project template that your Web server supports PHP 7.1. PHP 8.1 is not supported (yet).

INSTALLATION

Security Note

mDIS code contains some default users and passwords. If you plan to run mDIS as a WebApp on the public internet, please change these passwords.

Do so either before installation or after installation.

Before Installation

Change usernames and passwords

  • either check the file backend/commands/SeedController.php. Change default usernames and passwords according to your preferences.
  • or change the mode of installation to LDAP. See the files backend/config/web.php and backend/config/ldap-example.php for instructions. This way default usernames and passwords will not be used.

After mDIS installation

Change usernames and passwords

Change usernames and passwords using the mDIS web interface. Login as admininstrator and change the passwords of the default users. The password manager is reachable via Sidebar item "Settings" -> "User Manager".

Install via Composer

@TODO

Install from an Archive File

@TODO

Install with Docker

This is only a basic installation. Depending on your environment, Docker version and Docker skills, you might need to adapt the docker-compose.yml and related files (e.g., .env).

Clone the repository and cd into the dis folder.

Prepare docker environment file by copying .env-dev to .env.

Update your vendor packages

docker-compose run --rm php composer update --prefer-dist

Run the installation scripts (this is a standard composer command)

docker-compose run --rm php composer install

Run post project creation triggers (set required permissions)

docker-compose run --rm php composer run-script post-create-project-cmd

Install frontend dependencies (3rd party Javascript code)

npm install

To generate frontend bundle (the mDIS webapp), use one of the following commands

# for production build
# This command produces a production-ready bundle in the /web directory 
# (see https://cli.vuejs.org/guide/cli-service.html#vue-cli-service-build)
npm run build 

# for JavaScript development (advanced)
# starts Webpack dev server, builds JS sourcemaps and other things
# (see https://cli.vuejs.org/guide/cli-service.html#vue-cli-service-serve)
npm run serve 

Start the containers

docker-compose up # add -d to run as deamon (in the background)

You can then access the application at http://127.0.0.1:8000

After adding NodeJS to the PHP container, first build time was increased. Take the build option out and uncomment the image line if do not need NodeJS in the container. check here and here for suggested solutions.

On the command line you should execute something like this:

docker ps | grep dis

Result:


CONTAINER ID        IMAGE                             COMMAND                  CREATED             STATUS              PORTS                    NAMES
71b25a7418dd        yiisoftware/yii2-php:7.3-apache   "docker-php-entrypoi…"   23 hours ago        Up 13 seconds       0.0.0.0:8000->80/tcp     dis_php_1
57cdf5ca735e        mariadb                           "docker-entrypoint.s…"   23 hours ago        Up 23 hours         0.0.0.0:8001->3306/tcp   dis_db_1
7424a0f9f6a7        adminer                           "entrypoint.sh docke…"   3 days ago          Up 3 days           0.0.0.0:8002->8080/tcp   dis_adminer_1

Rightmost Column NAMES signifies:

  • dis_php_1 - Webserver with PHP/Yii2 Application
  • dis_db_1 - Mariadb, Database Server
  • dis_adminer_1 - Adminer, Web-based Database Administration Tool

Optionally, stop the containers with docker stop dis_php_1 dis_db_1 dis_adminer_1.

Apply database migrations to create required tables and seed data

# bash into php container
docker exec -it dis_php_1 bash
# then call yii migrations
./yii migrate
# seed users accounts
yii seed/users
# load DSEIS data
yii seed/example-dump 
# seed users forms permissions
yii seed/form-permissions

The mariadb container stores persistent mDIS data inside Docker volume dis_dbvolume:

docker volume inspect dis_dbvolume

This enables the container to "survive" restarts, keeping data created by both the yii migrate command and data eventually entered by the DIS user.

NOTES:

  • Minimum required Docker engine version 17.04 for development (see Performance tuning for volume mounts)
  • The default configuration uses a host-volume in your home directory .composer-docker for php-composer caches

CONFIGURATION

Database

This configuration is not needed for docker installation.

Edit the file config/db.php with real data, for example:

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=your_host;dbname=your_db_name',
    'username' => 'your_db_user',
    'password' => 'your_db_password',
    'charset' => 'utf8',
];

UPGRADE TO V3

In January 2022 we decided to remove several files from the repository that where automatically generated or usually modified in an instance. Additionally several separately developed branches have been merged including the new standard data model of ICDP. The Branch "mDIS V2" keeps the version before that braking changes. To update an exisiting instance to the new Version 3.x, please follow these steps:

  1. Make sure you are on the master branch, type git pull in order to update the project.
  • If you do a git pull, various modified files will probably be criticized.
  • All files in backend/models/base can be restored via "git restore" (they will be deleted on pull)
    • All files in backend/models and backend/forms that have not been specialized can be reset (they will be deleted on pull)
    • All files src/forms/*.vue.generated can be reset (they will be deleted on pull)
    • The specialized files in backend/models/ and /backend/forms/ can be detached from the repository: git rm -cached <path-to-file-that-dont-want-to track>
    • Now git pull should work
  1. Type composer install in the console.
  2. Type ./yii upgrade 3 in the console.
    • This command will do the following:
      • Copy the default models templates to ‘backend/dis_templates/models’.
      • Copy the default forms templates to ‘backend/dis_templates/models’.
      • Create the missing tables in the data base according to the already copied models templates.
      • Apply the migrations of usuario library.
      • Update the PHP models and form as also the *.vue.generated files.
  3. Delete the folder node_modules from your project root.
  4. Type npm install in the console, to rebuild the node_modules folder.
  5. Type npm run build in order to create a new build or npm run serve to serve.