Business logic core of the application and a REST API that provides access to other modules.
You need a web server with PHP (8.1+) and MySQL or MariaDB database.
We recommend installing PHP from remi repository:
# dnf install dnf-utils http://rpms.remirepo.net/enterprise/remi-release-8.rpm
You may list the PHP modules thusly:
# dnf module list php
...and select the right module:
# dnf module enable php:remi-8.1
If you install core-api as a package, the PHP will be installed as dependencies. Otherwise, you may install it manually:
# dnf -y install php php-json php-mysqlnd php-ldap php-pecl-yaml php-pecl-zip php-pecl-zmq php-xml php-intl php-mbstring php-pecl-inotify
It is also recommended that you create a separate database (e.g., recodex)
and a separate DB user who is granted all rights for this database (and only
this database).
You can do this by running mysql -uroot -p and then executing these SQLs:
CREATE DATABASE `recodex`;
CREATE USER 'recodex'@'localhost' IDENTIFIED BY 'someSecretPasswordYouNeedToSetYourself';
GRANT ALL PRIVILEGES ON `recodex`.* TO 'recodex'@'localhost';
This is recommended way for CentOS/RHEL and Fedora systems.
# dnf copr enable semai/ReCodEx
# dnf install recodex-core
The module will be installed in /opt/recodex-core. After installation, you need to
edit /etc/recodex/core-api/config.neon. Proceed from step 3. of manual
installation to the end.
The web API requires a PHP runtime version at least 8.1. Which one depends on actual configuration, there is a choice between mod_php inside Apache, php-fpm with Apache or Nginx proxy or running it as standalone uWSGI script. Also see the required PHP modules in the prerequisites section.
The API depends on some other projects and libraries which are managed by
Composer. It can be installed from system
repositories or downloaded from the website, where detailed instructions are as
well. Composer reads composer.json file in the project root and installs
dependencies to the vendor/ subdirectory.
- Clone the git repository
- Run
composer install - Create a database and fill in the access information in
app/config/config.local.neon(for an example, seeapp/config/config.local.neon.example) do not forget to set the database configuration, especially the credentials. - Setup the database schema by running
bin/console migrations:migrate
You may optionally fill the database with initial values by running
bin/console db:fill init, after this database will contain:
- Instance with administrator registered as local account with credentials username:
admin@admin.com, password:admin - Runtime environments which ReCodEx can handle
- Default single hardware group which might be used for workers
- Pipelines for runtime environments which can be used when building exercises
Creating these data manually may be somewhat difficult and tedious, so it might be a good idea to proceed with this step and perhaps prune the data later (remove runtimes and pipelines you will not use).
Finally, you need to configure the web server, so that
- Directory
/opt/recodex-core/wwwis accessible and PHP scripts here are interpreted. - Proper alias is set for
/opt/recodex-core/wwwthat matches API path set in other modules, especially the web frontend (e.g.,/apiif the recodex runs on a root of a domain). - It might necessary to set up CORS headers (similar thing goes for the web app) as follows:
Header always set Access-Control-Allow-Origin "*"
Header always set Access-Control-Allow-Headers "headers, Authorization, Accept-Language, X-ReCodEx-lang"
Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS"
The API can be configured in config.neon and config.local.neon files in
app/config directory of the API project source tree. The first file is
predefined by authors and should not be modified. The second one is not present
and could be created by copying config.local.neon.example template in the
config directory. Local configuration have higher precedence, so it will
override default values from config.neon.
Descriptions of particular config items are managed in static global config file in form of comments. Global config.neon should never be changed, local changes should be made to config.local.neon.
The simplest way to get started is to start the built-in PHP server in the root directory of your project:
php -S localhost:4000 -t www
Then visit http://localhost:4000 in your browser to see the welcome page.
For Apache or Nginx, setup a virtual host to point to the www/ directory of the project and you should be ready to go.
It is critical that whole app/, log/ and temp/ directories are not accessible directly via a web browser. See security warning. Also it is highly recommended to set up a HTTPS certificate for public access to the
API.
In case of any issues first remove the Nette cache directory temp/cache/ and
try again. This solves most of the errors. If it does not help, examine API logs
from log/ directory of the API source or logs of your webserver.
The tests require sqlite3 to be installed and accessible through $PATH.
Run them with the following command (feel free to adjust the path to php.ini):
php vendor/bin/tester -c /etc/php/php.ini tests
Core API offers several command line commands for cleanup, maintenance, and email notifications. It is recommended you set up some periodical execution of these commands -- e.g., by crontab. The actual frequency depends on utilization of your system, but here are some recommendations:
Daily:
notifications:assignment-deadlineswill send emails to students (who actually allowed this in their configurations) about approaching deadlines. This is the most important command as it is directly related to ReCodEx operations. It is recommended to run this command every night.fs:cleanup:workerwill remove old files that are exchanged between core api and worker backenddb:cleanup:uploadswill remove old uploaded files
Weekly:
notifications:general-statswill send an email to all administrators with brief statistics about ReCodEx usage. It is recommended to run this command once a week (e.g., during the night between Saturday and Monday).
Monthly:
db:cleanup:localized-textswill remove old texts of groups and exercisesdb:cleanup:exercise-configswill remove old exercise configsdb:cleanup:exercise-fileswill remove unused files (attachments and test files) of deleted exercises/assignments and pipelinesdb:cleanup:pipeline-configswill remove old pipeline configs
Annually:
users:remove-inactivewill soft-delete and anonymize users who are deemed inactive (i.e., they have not verified their credentials for a period of time that is set in core module config)
Some details of these periodic commands (e.g., a threshold period of relevant assignment deadlines) can be configured in the neon config file.
Adminer is full-featured database management tool written in PHP and it is part of this Sandbox.
To use it, browse to the subdirectory /adminer in your project root (i.e. http://localhost:4000/adminer).
Feel free to read the documentation on our wiki.
- ReCodEx REST API: MIT License
- Nette: New BSD License or GPL 2.0 or 3.0
- Adminer: Apache License 2.0 or GPL 2