1.Installation
1.1.Requirements
To use Myddleware you need the following on your web server :
- A web server such as Apache
- PHP version 7.4 or above
- composer https://getcomposer.org/download/
- MySQL version 5.7 or above
- yarn https://yarnpkg.com/getting-started/install
Myddleware uses Doctrine so you will need to have the PDO driver installed for the database server you intend to use.
1.2.Downloading Myddleware
Please download the latest version of Myddleware here or go to section 1.6 Install from Github.
1.3.Copying files to web server
Once you have downloaded the Myddleware package, copy and extract the ‘myddleware’ folder contents on your web server.
Please do NOT change the ‘myddleware’ subdirectory name.
You should have these directories inside the ‘myddleware’ folder :
1.4.Install Myddleware via wizard
You can install Myddleware by adding “myddleware/public” to your Myddleware URL:
http://<path_to_myddleware>/myddleware/public/
You should be redirected to http://<path_to_myddleware>/myddleware/public/install/requirements but if not, simply click the ‘Install Myddleware’ button :
Here, Myddleware will analyse your server’s configuration to check it against requirements. A prompt will let you know whether your server is ready to install Myddleware or if further action is required to begin the installation process.
Once you have fixed the potential errors, simply click ‘Next’ to get to the database setup section.
Here, fill in the form with the values corresponding to your database. Click ‘Save’ then ‘Next’. Myddleware will then attempt to connect to your database.
WARNING: before submitting this form, please ensure you have already created an empty Myddleware database on your host server.
If Myddleware was able to connect to your database, it will have automatically updated it with the necessary schema and the following message will be displayed :
Simply click ‘Next’ again. Myddleware will now attempt to load the configuration data it needs to be able to run. The following message should then be displayed :
Once you’ve clicked ‘Next’ again, the fifth and final step to install Myddleware will be to create your Myddleware user :
Once this is done, you should automatically be redirected to your Myddleware admin dashboard. You are now ready to use Myddleware.
http://<path_to_myddleware>/myddleware/public/
We advise you to set up your web server, you will find help here.
WARNING : please be aware that once you’ve installed Myddleware and registered your user, you will no longer be able to access this installation wizard.
1.5.Install from Github
To get Myddleware from Github, use this command :
git clone https://github.com/Myddleware/myddleware.git
Go to the Myddleware root directory:
cd myddleware
Install the vendors :
composer install
Install assets :
yarn install
Build assets :
yarn build
Then you can either follow this tutorial to install Myddleware using your browser or continue the installation using command line.
1.6.Install via command
Before starting, make sure your configuration is correct : open a command shell from your myddleware subdirectory and run this command :
symfony check:requirements
Change your configuration until your system is ready to install Myddleware :
Create a .env.local file at the root of your myddleware subdirectory. This file will override the configuration defined in the .env file. Inside this file, add the following line :
DATABASE_URL=”mysql://username:password@host:port/dbname”
APP_ENV=prod
APP_DEBUG=false
APP_SECRET=ChangeMeToWhatYouWant
Change the APP_SECRET to a random string of 32 characters (more info here)
Create a database on your server and replace each value from the DATABASE_URL variable with your database connection parameters :
- username : the username used to login to your database
- password: the password associated with that username
- host: your database host (if you installed Myddleware locally on your server, it will be ‘localhost’
- port: your database port (usually 3306 or 3307 if localhost)
- dbname: the name of your database
For example :
DATABASE_URL=”mysql://root:@localhost:3306/myddleware”
APP_ENV=prod
APP_DEBUG=false
APP_SECRET=9db76d471d22660250c3b0c259775d63
Then, go to your Myddleware directory and run these commands :
- Connect to the database
php bin/console doctrine:schema:update --force
- Load Myddleware fixtures :
php bin/console doctrine:fixtures:load --append
- Create your Myddleware credentials
php bin/console myddleware:add-user
or if you want to have a ROLE_SUPER_ADMIN directly :
php bin/console myddleware:add-user --superadmin
You will be prompted to create your username, email & password. You can still add a role to your user after its creation with the command :
php bin/console myddleware:promote-user <email> ROLE_SUPER_ADMIN
The installation process is now complete. You can login to Myddleware using your credentials in your browser.
We advise you to set up your web server, you will find help here.
You can now access Myddleware with this URL :
http://<path_to_myddleware>/myddleware/public/
2.Optional : changing Myddleware user privileges
Myddleware allows you to modify privileges for each of your users. To do so, you will need to open a terminal from your web server and access the myddleware folder by typing the following command:
cd myddleware
- Adding Super Admin privileges
Some advanced Myddleware features such as cancelling or deleting all documents from a rule are restricted to Super Admin users. To enable these privileges for a Myddleware user, once in the myddleware directory, type the following command :
php bin/console myddleware:promote-user
Type the user’s email address, press Enter then type ROLE_SUPER_ADMIN and press Enter again.
- Demoting a user
If you wish to remove some special roles from a user privileges (such as ROLE_SUPER_ADMIN), use the following command :
php bin/console myddleware:demote-user
- Add a new user
If you wish to add another Myddleware user, type the following command from your myddleware directory :
php bin/console myddleware:add-user
3.Setting up a cron task
Myddleware can work with background tasks to sync your data, send notifications, clean data, and more.
If you wish to do so, you will have to set up some background tasks using the crontab.
Before creating the crontask, make sure your configuration is correct, open a command shell and run this command :
php bin/symfony_requirements
Change your file permission or PHP configuration in case of permission error or missing PHP requirement :
You can now start the following tasks depending on your needs :
cd <myddleware directory>; php bin/console myddleware:synchro ALL --env=background > /dev/null 2>&1
- This program will synchronise the data by running every active rule.
- Parameter => ALL or rule_name_slug :
cd <myddleware directory>; php bin/console myddleware:rerunerror 100 5 --env=background > /dev/null 2>&1
- This program will read the documents in error and will try to send them again
- 1st parameter => limitation on the number of documents in error that the program will read. In this particular case, the program will read a maximum of 100 documents in error
- 2nd parameter => limitation on the number of attempts : documents that Myddleware tried to send maximum 5 times will be read.
cd <myddleware directory>; php bin/console myddleware:cleardata --env=background > /dev/null 2>&1
- This program will clear all data depending on whether the parameter “Deleting data” is set on the rule.
- Don’t run this program if you don’t want to clear data.
cd <myddleware directory>; php bin/console myddleware:notification --env=background > /dev/null 2>&1
- This program will send a notification if some documents are in error. An e-mail will be sent to the email address set up in the file myddleware/app/config/config_background.yml , parameter notification_emailaddress
Here is an example of the crontab :
4.Upgrading Myddleware
We suggest you use git to update Myddleware. If you don’t have git on your server, here are the instructions on how to install it : https://git-scm.com/download/linux
Before doing anything else, create a backup of your Myddleware before updating.
After the backup, go to the root directory of Myddleware and run the command as stated below to update all the Myddleware files.
If you have never used git with Myddleware, please run these commands from your Myddleware root directory:
git init git remote add -t master origin https://github.com/Myddleware/myddleware.git git fetch git checkout origin/master -ft
Then you can upgrade Myddleware with this command :
php bin/console myddleware:upgrade --env=background
If you have a problem during the upgrade you can do it step by step by following this tutorial :
git pull
If you get this message below during the pull, you have probably changed at least one file in the Myddleware standard code. Please read the good practices article to learn how to add custom upgraded & safe code in Myddleware. It will help you manage the conflicts. You can also delete these files, run the pull and you will get the latest version of this files. However, you will loose your custom code.
Then update Symfony vendors and their dependencies:
php composer.phar install --no-plugins
At this stage, if it is your first upgrade with git, you will have to answer “yes” several times to this question:
Then run this command to update Myddleware’s database:
php bin/console doctrine:schema:update --force --env=background php bin/console doctrine:fixtures:load --append --env=background
Then, please change your myddleware version parameter “myd_version” into the file <myddleware>\app\config\parameters.yml using the version number in the file <myddleware>\app\config\parameters.yml.dist
Finally clear the cache and refresh css and js files with these commands:
rm -rf var/cache/* php bin/console assetic:dump --env=background --no-debug php bin/console assets:install web --env=background
If you encounter any difficulties updating Myddleware, please contact us on our forum : https://github.com/Myddleware/myddleware/issues