mDIS Project
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 toweb
.+-- 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 filesbackend/config/web.php
andbackend/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:
- Make sure you are on the
master
branch, typegit 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
andbackend/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
- All files in
- Type
composer install
in the console. - 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.
- This command will do the following:
- Delete the folder
node_modules
from your project root. - Type
npm install
in the console, to rebuild thenode_modules
folder. - Type
npm run build
in order to create a new build ornpm run serve
to serve.