README

Crunz-ui starts from the most famous GitHub Crunzphp/Crunz project and it's proposed to be its natural graphical interface, developed to make its usage more accessible and easy to use. Designed to be extremely light, it uses lucatacconi/silly-vue-scaffolding which guarantees the project its elastic and dynamic structure.

Table of Contents (click to expand)

What Crunz is and how Crunz-ui connects to it
What else can Crunz-ui do
Browser Support
System Requirements
Pre-installation safety warnings
Installation and application setup
First login
Contributing informations
Roadmap
FAQ / Troubleshooting
Lazy Developer Shortcuts

ℹ️ Use the link below if you want to skip information about Crunz and Crunz-ui and go straight to setup procedures:

Shortcuts to Docker and Composer setup procedure

What Crunz is and how Crunz-ui connects to it

Crunz is an application that allows users to schedule tasks natively written in PHP, programming date and time of start, interval and conditions of execution, and init.

You can find details about Crunz and how to write and schedule tasks at the following address: https://github.com/crunzphp/crunz

Crunz task example:

<?php
// tasks/backupTasks.php

use Crunz\Schedule;

$schedule = new Schedule();
$task = $schedule->run('cp project project-bk');
$task->daily();

return $schedule;

Crunz-ui natively uses Crunz libraries and functions to read and interpret the configured tasks; then presents tasks in a tabular or graphical display, showing them on a monthly or daily view.

What else can Crunz-ui do?

In addition to displaying tasks in tabular or graphic format, Crunz-ui allows you to:

Manage tasks through easy-to-use interfaces (create, modify, archive, delete tasks)
Upload or download tasks with an intuitive and simple file manager system
Quick display of results of the tasks that have been executed (The indicator icons easily show whether the task was performed with errors or successfully)
Search and display the outcome of task execution on a specific date or selected through various search parameters
Forced run of the task, even outside the scheduled time with an eventual display of the log once the execution is completed

Browser Support

System Requirements

Linux OS and Bash shell
Service ntp enabled
Apache and PHP 7.4 or newer, with rewrite.load module enabled
Composer
Sudo capabilities

Pre-installation safety warnings

⚠️ Crunz and Crunz-ui need that the operator has the permissions to set up crontab entry to schedule the regular execution of the task management process. Crontab entry owner must be carefully selected: using high permissions level user (ex root) could allow tasks to access sensitive files or perform malicious operations on the entire server file system.

⚠️ It is very important to change as soon as possible the default password of the Crunz-ui admin user. Leaving the default password could allow malicious users to access the Crunz-ui task manager and load dangerous tasks with the capability to access sensitive files or perform malicious operations on the entire server file system.

⚠️ It is important to keep system clock synchronized. In the case of an unsynchronized clock, there could be misalignments in the execution of the tasks or the management of the user sessions.

⚠️ For browser security configurations, copy to clipboard buttons are available only if Crunz-ui is released in localhost or in an https domain.

⚠️ In countries where is present daylight saving time switch, there may be discrepancies in the task execution time and task outcome display on the day of the time switch.

Installation and application setup

The two quickest ways to install Crunz-ui are with a Docker container or by installing via Composer

Docker setup

If it is not necessary to install Crunz-ui alongside an existing Crunz installation, the simplest way to install it is to configure the software and do its startup through Docker. The Crunz-ui Docker container is the quickest way to have a running and ready-to-use application.

First of all, download both files to Github server.

Dockerfile - Docker container configuration file
Crunz.yml - Crunz standard configuration file

Manually edit Crunz configurations present in the Crunz.yml file. Inside the file, there are suggestions about the individual configuration parameters. Please refer to Crunzphp/Crunz for more details on the configuration.

Initialize Crunz-iu Docker container. Be careful to select the correct timezone before running the command. (ex. TIMEZONE=Europe/Rome)

sudo docker build -t crunz-ui --build-arg TIMEZONE=Europe/Rome:

Start Crunz-iu Docker container indicating the port through which to access the web interface (ex. DEST_PORT:ORIG_PORT 80:80 ):

sudo docker run -dp 80:80 --name crunz-ui-app crunz-ui

Access the application via browser (Refer to First login section for connection details)

http://LOCAL_IP/crunz-ui (Ex. http://192.168.1.127/crunz-ui)

Please refer to Ubuntu/Debian Docker setup example for suggestion.

Composer setup

Otherwise It's recommended that you use Composer to install Crunz-ui.

Starting from your Apache Server's Document Root folder or from a directory served by a virtual host, begin the application setup by Composer command:

composer create-project lucatacconi/crunz-ui

This will install Crunz-ui and all required dependencies.

ℹ️ There is no need to set a large max_execution_time property in your php.ini: Crunz performs tasks as if they were run from the console. When running PHP from the command line the default setting is 0 therefore without time limits.

Cruz-ui installed by Composer can work using the Crunz embedded in the packages or using the tasks and configurations of Crunz previously installed on the user's system.

If you have never used Crunz before or want to use the Crunz integrated into the packages, refer to the Never used Crunz before section. If you want to use Cruz-ui on a version of Crunz previously installed on the user's systems, refer to the Usage on a previous installation of Crunz section.

ℹ️ By default Crunz checks the correctness of the php code before considering the task file. In case of servers with less computing power, checking the syntax of the tasks considerably slows down the display of tables and statistics. You can set the .env parameter CHECK_PHP_TASKS_SYNTAX to false to inhibit syntax checking. In case of syntax errors in the tasks, configuring parameter CHECK_PHP_TASKS_SYNTAX to false could cause anomalous behavior in the Crunz-ui interfaces

Crunz-ui can also be used with Xampp. However, it is necessary to create a symbolic link of the Xampp's PHP in your system executables folder:

sudo ln -s /opt/lampp/bin/php /usr/bin/

Using Crunz-ui on Xampp with PHP already present on the server in a separate installation from XAMPP, functions "Execute and wait log" present in the Tasks table section menu will fail with the following error: Unable to load dynamic library 'curl.so'. Check FAQ to solve the problem.

Never used Crunz before

Cruz-ui has Crunz packages embedded in its libraries. Once configured, the application can then start viewing, managing and executing tasks.

To configure the application in this way, once Crunz-ui is installed, proceed as follows:

By accessing the project folder, you can use the specific function of Crunz to generate the basic configuration file of Crunz itself:

./vendor/bin/crunz publish:config

The procedure will ask the user to provide default timezone for task run date calculations; execution will generate the Crunz configuration file with the default settings. For more advanced configurations, refer to the Crunz manual.

At this point it is necessary to configure all the users who must be able to access the application. Refer to Accounts configuration section to configure users. By default, in the basic configuration, the admin user is configured with the temporary password password.

Then set an ordinary cron job (a crontab entry) which runs every minute, and delegates the responsibility to Crunz-ui event runner:

* * * * * cd /[BASE_CRUNZUI_PATH] && ./crunz-ui.sh

By default the configured log folder is ./var/logs inside Crunz-ui folder. To use custom log folder configure the .env file with the path of new log folder. The folder must be accessible and writeable by the Apache user.

If you have configured a custom log folder, the crontab configuration must be changed as follows:

* * * * * cd /[BASE_CRUNZUI_PATH] && ./crunz-ui.sh -l [LOGS_PATH]

Please refer to Ubuntu/Debian setup example for suggestion.

Usage on a previous installation of Crunz

First of all you need to tell Crunz-ui the exact location where Crunz is installed. To do this, edit the .env file inside the main folder of Crunz-ui by un-commenting the entry CRUNZ_BASE_DIR and indicating into that the value of the absolute path of Crunz installation. In order to be able to insert, modify and delete tasks, the Apache user must have access and write permissions to the tasks folder.

Then copy crunz-ui.sh file and TasksTreeReader.php into the Crunz base folder:

cp /[BASE_CRUNZUI_PATH]/crunz-ui.sh /[BASE_CRUNZ_PATH]
cp /[BASE_CRUNZUI_PATH]/TasksTreeReader.php /[BASE_CRUNZ_PATH]

By default crunz.ui.sh batch will search for standard log folder ./var/logs inside main Crunz folder. Therefore, if you want to use standard configuration, you need to create default folder for logs. The folder must be accessible and writeable by the Apache user:

cd /[BASE_CRUNZ_PATH]
mkdir ./var ./var/logs

Modify the Crunz process, configured in Crontab during the Crunz installation, replacing it with the Crunz-ui process:

* * * * * cd /[BASE_CRUNZ_PATH] && ./crunz-ui.sh

Configure, if needed, Crunz-ui .env file with a custom path of the log folder. In this case too it is important that the folder is accessible and writeable by the Apache user. If you have configured a custom log folder, the crontab configuration must be changed as follows:

* * * * * cd /[BASE_CRUNZ_PATH] && ./crunz-ui.sh -l [LOGS_PATH]

Custom log directory configuration

By default, the configured log folder is ./var/logs inside Crunz / Crunz-ui folder. The folder must be accessible and writeable by the Apache user.

To configure custom folder set the .env file with the path of new log folder.

If you have configured a custom log folder, the crontab configuration must be changed as follows:

* * * * * cd /[BASE_CRUNZ_PATH / BASE_CRUNZUI_PATH] && ./crunz-ui.sh -l [LOGS_PATH]

Accounts configuration

All users enabled to access the application are configured in the configuration file /config/accounts.json.

The accounts.json configuration file has the following format:

[
    {
        "username":"admin",
        "name":"Admin User",
        "userType":"admin",
        "email":"admin@nomail.com",
        "password":"password",
        "active":"Y",
        "expireDate":"2020-10-10",
        "customSessionDuration":""
    },
    {
        "username":"j.doe",
        "name":"Jhon Doe",
        "userType":"user",
        "email":"j.doe@nomail.com",
        "password":"password",
        "active":"Y",
        "expireDate":"2020-10-10",
        "customSessionDuration":""
    },
    ...
]

Among the various information listed, the type of user is also induced, information that is then used to filter the menu items enabled for the user. For simplicity's choice the access configurations have been inserted in a file. However, nothing prevents the implementation of user management based on database reading.

First login

The application is preconfigured with a single access user to verify the login procedure and access the dashboard and the main menu.

To test access use the login admin and password password

Contributing

This project is maintained by a group of awesome contributors. Contributions are extremely welcome ❤️. Please see Contributing informations for details.

Roadmap

Please see Roadmap for details.

FAQ and Troubleshooting

For help, FAQ or troubleshooting please refer to FAQ and Troubleshooting.

Credits

License

Crunz-ui is licensed under the MIT license. See License File for more information.

lucatacconi / crunz-ui

Maintainers

Details