Crowdsourcing Platform
Update to google analytics 4, fix paging issues
This is a Laravel Web Application for Crowdsourcing Projects and Questionnaires.
.env file.env settingsOffering the code under open source licenses includes many benefits. Of those, the ones related to our project, are:
ECAS official installation
SciFY official installation
The setup instructions have been divided into two sections for clarity:
Regardless of the installation method, you will need to run the following commands to set up the application.
These commands should be run outside any Docker container:
sudo chown -R `whoami`:www-data storage
chmod 775 storage
cd storage/
find . -type f -exec chmod 664 {} ;
find . -type d -exec chmod 775 {} ;Depending on the installation method, you should run the rest of the steps either in the Docker container or on your local machine.
Note: If you are using Docker Compose, you will first need first to enter the PHP container:
docker exec -it crowdsourcing_platform_server bashand then run the rest of the commands.
If you are running the commands on your local machine, you can run the following commands directly.
If you have started Ddev, you should run all the commands prefixed with ddev exec.
.env fileAfter cloning the project, create an .env file (should be a copy of .env.example):
cp .env.example .envIn case of a non-Docker installation, you will need to create a Database for the application.
In case of a Docker environment, enter the crowdsourcing_platform_db container, and create a Database
named crowdsourcing_db_docker:
docker exec -it crowdsourcing_platform_db bashEnter the MySQL shell:
mysql -u root -pThen, run the following MySQL command:
CREATE DATABASE IF NOT EXISTS crowdsourcing_db_docker;First you will need to enter the DB container:
docker exec -it crowdsourcing_platform_db bashIf you have an existing MySQL dump file, make sure that is in the current directory, and import it into the database:
mysql -u root -p crowdsourcing_db_docker < dump.sqlThen, add the following to the .env file:
DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=crowdsourcing_db_docker
DB_USERNAME=root
DB_PASSWORD=rootNote: If you are using Docker Compose, you will need first to enter the server container:
docker exec -it crowdsourcing_platform_server bashphp artisan migratephp artisan db:seedEnter the PHP container (if using Docker Compose):
docker exec -it crowdsourcing_platform_server bashThen, run the following commands:
composer install
composer dump-autoloadphp artisan key:generatenpm install
npm run dev # (if in development mode, use for live changes)
npm run build # (if in development mode)
npm run prod # (if in production mode)By default, images are stored at app/storage/public. Run
php artisan storage:link.env settingsAnd then persist the .env settings to Laravel Cache:
php artisan config:cachein order to link this folder with the public directory
This app uses Socialite Laravel Plugin to handle social login.
In order to get it working in your development environment, you need to make sure that you have API keys and secrets for Facebook and Twitter (guides here and here), and that you can access https://dev.crowdsourcing/ (notice the https) on your machine.
A guide for enabling https on your local machine can be found here.
Basically, you need to run
openssl req -new -sha256 -newkey rsa:2048 -nodes
-keyout dev.crowdsourcing.key -x509 -days 365
-out dev.crowdsourcing.crtReference the 2 generated files in the Nginx configuration file of the application. Make sure you change the port to 443 as shown below:
server {
listen 443 ssl;
server_name dev.crowdsourcing;
ssl_certificate /path/to/dev.crowdsourcing.crt;
ssl_certificate_key /path/to/dev.crowdsourcing.key;
root /var/www/crowdsourcing/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-XSS-Protection "1; mode=block";
add_header X-Content-Type-Options "nosniff";
index index.php index.html index.htm index.nginx-debian.html;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
error_page 404 /index.php;
location ~ .php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
}
location ~ /.ht {
deny all;
}
}Also, make sure to restart Nginx, by running
sudo systemctl restart nginxThis application uses Spatie - Laravel Sitemap plugin, in order to create
the public/sitemap.xml file (which is excluded from git), that will be crawled by the search engines.
In order to run the generator for the current application installation, run the embedded Laravel command:
php artisan sitemap:generateThis application uses Laravel Pint in order to perform code-style.
In order to run the styler, run :
./vendor/bin/pint --test -v # the --test will not do any changes, it will just output the changes needed
./vendor/bin/pint -v # this command will actually perform the code style changes This application uses ESLint and Prettier in order to perform code-style.
In order to run the styler & formatter, run :
npm run lint # this command will check the code style
npm run format # this command will format the code styleThis project uses the free AdminLTE template.
It also makes use of Bootstrap 4
The application can be tweaked and personalized for each installation.
In the .env file you can set the INSTALLATION_RESOURCES_DIR variable accordingly. This variable must take a value
that represents a directory name in the resourcess/views/home/partials directory. For example, see
the resourcess/views/home/partials/together directory. This directory must contain the partial blade files for the
installation.
This part of the documentation describes the directory structure of the Laravel application.
It is mostly scoped to the custom directories and files that are used in the application. For the general Laravel directory structure, please refer to the official documentation.
├── app # Laravel application directory
│ ├── BusinessLogicLayer # Business Logic Layer classes (services that contain the business logic and delegate from Controllers towards the Data Access Layer)
│ ├── Http/Controllers # Controllers directory (classes that handle the HTTP requests, perform the necessary validations/operations and return the responses)
│ ├── Http/Middleware # Middleware directory (classes that handle the HTTP requests before they reach the Controllers)
│ ├── Models # Models directory (ORM classes that represent the database tables and contain the relationships between them)
│ ├── Notifications # Notifications directory (classes that handle the notifications, like emails)
│ ├── ViewModels # View Models directory (classes that contain the data that will be passed to the views)
│ ├── Repository # Repository directory (classes that handle the database operations and contain the DB/ORM queries)
│ resources # Resources directory (contains the views, assets, front-end files, and other resources)
│ ├── views # Views directory (contains the blade files that are used to render the HTML)
│ ├── assets # Assets directory (contains the front-end assets like CSS, JS, images, etc.)
│ ├── js # JavaScript files (contains the Vue.js components and other JS files)
│ ├── sass # SASS files (contains the SASS files that are compiled to CSS)
│ ├── lang # Language files (contains the language files for the translations)
The application uses the Repository Pattern to separate the business logic from the data access logic.
All the database operations are handled by the Repository classes, which contain the DB/ORM queries.
These classes are located in the app/Repository directory, and they all extend the app/Repository/Repository class.
Each child class represents a database table/entity and contains the queries for that table. This entity is defined in
the app/Models directory, and is referenced by the child Repository class, in the getModelClassName method.
So, we can use the base methods that are defined in the Repository class, like getAll, getById, create,
update, without having to write the same queries in each child class. We can also define custom queries in the child
classes, or override the base methods if needed.
The Repository classes are used by the Business Logic Layer classes, which contain the business logic and delegate from the Controllers towards the Data Access Layer.
More information about the Repository Pattern can be found here.
Make sure that you have cleared any cache and config files:
php artisan cache:clear
php artisan config:clearCreate the test database file:
touch storage/database_testing.sqliteGive the necessary permissions to the test database file:
chmod 777 storage/database_testing.sqliteThen, make sure that you have set up the test database:
Run the migrations & seeders for the test database:
php artisan migrate:fresh --seed --env=testing --database=sqlite_testingphp artisan test commandYou can run the tests using the php artisan test command, which is a built-in Laravel command.
And finally, run the tests:
# Note that you filter the tests by using the --filter flag (without the = sign)
php artisan test --env=testing --filter {METHOD OR CLASS NAME} --coveragerun-tests.sh scriptYou can also run the tests using the run-tests.sh script, which is a wrapper around the PHPUnit command.
chmod +x run-tests.sh
./run-tests.shThis can also take any arguments (like the --filter or --coverage flag) that you would pass to the PHPUnit command.
./run-tests.sh --filter {METHOD OR CLASS NAME}or
./run-tests.sh --coverageBy using Docker Compose, you can debug the application by following these steps:
docker compose up to start the containers..vscode/launch.json file with the following contents:{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www": "${workspaceFolder}"
},
"log": true
}
]
}Now you can start debugging your application.
For debugging the tests:
docker exec -it crowdsourcing_platform_server bash to enter the PHP container.php artisan app:test --filter {METHOD OR CLASS NAME}. For example
php artisan app:test --filter authenticatedNonAdminUserCannotAccessCreatePage.If you encounter any issues, refer to the following steps:
docker compose logssystemctl status nginx and systemctl status php-fpmstorage/logs/laravel.log.env file has the correct database credentialssystemctl status mysqlnginx -tTo contribute to the application, follow these steps:
git checkout -b <branch_name>.git commit -m '<commit_message>'git push origin <project_name>/<location>This project is open-sourced software licensed under the Apache License, Version 2.0.
This project is developed by SciFY and ECAS and is based on the Laravel framework. The project is maintained by SciFY.
Some of the images used in the application are from Freepik.
Feel free to contact the project maintainers:
