This is a Laravel 9 Web Application for Crowdsourcing Projects and Questionnaires.
- Introduction
- Features
- Organizations using the Crowdsourcing platform
- Installation Instructions
- Run the Laravel Application commands
- Step 1: Create the
.env
file - Step 2: Generate the application key
- Step 3: Install Laravel (back-end) dependencies
- Step 4: Install and compile the front-end dependencies:
- Step 5: Set up the Database **(only if in new installation) **
- Step 6: Create symbolic link for uploaded files
- Step 7: Fix permissions for storage directory
- Step 1: Create the
- Social Login - Sign Up with Socialite
- SEO - Generate Sitemap
- Related HTML Template
- PHP code style - Laravel Pint
- Installation-specific resources
- Run Tests
- How to debug
- Troubleshooting
- Contributing
- License
- Credits
- Contact
- Administration panel to set up questionnaires & projects
- Questionnaires with and without login: Questionnaires can be responded anonymously or eponymoysly
- The questionnaires can be automatically translated via google translations (to facilitate the manual translations)
- The citizen responses are automatically translated via google translations (and at the results you can see both the original and the translated)
- Setting targets for goals (number of responses needed for the questionnaire) to be reached
- Gamification elements: The platform motivates users to respond to questionnaires or invite others to respond
- Mailchimp integration: All the emails of registered users are collected to a mailchimp list
- Google Analytics integration (with anonymized settings turned on) with custom events: We track anonymously people who do actions in the website
- Voting mechanism for provided answers: Users can vote the best answers, Platform moderators can highlight the most interesting answers and reject/demote the not interesting ones
- Extract the results: You can download the answers to excel
- View statistics
- Login function with Facebook, Google, LinkedIn, Twitter, Microsoft
- The platform is available in many languages (and new translations can be added with relative low cost)
- GDPR compliant
Offering the code under open source licenses includes many benefits. Of those, the ones related to our project, are:
- There is no dependency on the developer of the solution (SciFY), but other collaborators can be used after the end of the project. The code remains always freely available.
- Stakeholders can add features, change it, improve it, adjust to their needs.
- New contributions are added to the existing solution so that everyone benefit
- Docker: Follow the installation guide for your operating system on the Docker website.
- Docker Compose: Docker Compose is included with Docker Desktop for Windows and Mac. For Linux, follow the instructions here.
Run the following command to build and start the containers:
docker-compose up --build
The application will be available at http://localhost:8080. To access PHPMyAdmin, visit http://localhost:8081.
- PHP: Install PHP 8.0 or newer. You can follow the installation guide for your operating system on the PHP website.
sudo apt update
sudo apt install php php-cli php-fpm php-mysql php-xml php-mbstring php-curl php-gd php-zip php-bcmath
- Composer: Install Composer by following the instructions on the Composer website.
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer
- Node.js: Install Node.js and npm by following the instructions on the Node.js website.
sudo apt install nodejs npm
Or, if using nnm, run the following command:
nvm use
- Nginx: Install Nginx by following the instructions on the Nginx website.
sudo apt install nginx
Create an Nginx configuration file for your Laravel project:
sudo nano /etc/nginx/sites-available/crowdsourcing
Add the necessary configuration to the file. Refer to the Nginx documentation for detailed configuration.
Example configuration:
server {
listen 80;
server_name crowdsourcing.local;
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;
}
}
Enable the configuration:
sudo ln -s /etc/nginx/sites-available/crowdsourcing /etc/nginx/sites-enabled/
sudo systemctl restart nginx
- MySQL: Install MySQL by following the instructions on the MySQL website.
sudo apt install mysql-server
If you are running MySQL version 8.0 and above, there is a certain bug regarding memory overflow when trying to sort results in tables that have columns of JSON data type.
A workaround to fix this is to tweak the memory buffer size for sorting. In order to do so, please follow:
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
And append the following options:
[mysqld]
sort_buffer_size = 10485760
innodb_sort_buffer_size = 10485760
After you save the file, restart the MySQL service:
sudo service mysql restart
- Ddev: Install Ddev by following the instructions on the Ddev website.
Run the following command to start Ddev:
ddev start
Depending on the installation method, you should run the following commands either in the Docker container or on your local machine.
For example, if you have already started the Docker containers, you can run the following command to access the PHP container:
docker exec -it crowdsourcing-php bash
and then run the following 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
.
After cloning the project, create an .env file (should be a copy of .env.example):
cp .env.example .env
php artisan key:generate
composer install
composer dump-autoload
npm install
npm run dev # (if in development mode)
npm run build # (if in production mode)
npm run dev # (if in development mode and you want to have live changes)
Run the Laravel migrations:
php artisan migrate
Run the Database seeder:
php artisan db:seed
By default, images are stored at app/storage/public. Run
php artisan storage:link
in order to link this folder with the public directory
sudo chown -R user:www-data storage
chmod 775 storage
cd storage/
find . -type f -exec chmod 664 {} \;
find . -type d -exec chmod 775 {} \;
The above steps can also be done in a better way, by using the companion script:
chmod +x set-file-permissions.sh
sudo ./set-file-permissions.sh www-data USER .
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.crt
And then reference 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 nginx
This 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:generate
This project uses the free AdminLTE template.
It also makes use of Bootstrap 4
This 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
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.
You may use a separate MySQL database, for testing purposes.
Generally, the fields for testing should be defined in a .env.testing
file, which should start as a copy of
the .env.testing.example
file.
Then, run the migrate
and seed
commands for the testing Database:
cp .env.testing.example .env.testing
php artisan migrate --env=testing
php artisan db:seed --env=testing --class=DatabaseSeeder
- Install and configure Xdebug on your machine
- At Chrome install Xdebug helper
- At PhpStorm/IntelliJ click the "Start listening for PHP debug connections"
If you encounter any issues, refer to the following steps:
- Check container logs if using Docker Compose:
docker-compose logs
- Verify Nginx and PHP-FPM status:
systemctl status nginx
andsystemctl status php-fpm
- Review Laravel logs located in
storage/logs/laravel.log
- Ensure your
.env
file has the correct database credentials - Verify the MySQL service is running:
systemctl status mysql
- Check the Nginx configuration:
nginx -t
To contribute to the application, follow these steps:
- Fork this repository.
- Read the CONTRIBUTING file.
- Create a branch:
git checkout -b <branch_name>
. - Make your changes and commit them:
git commit -m '<commit_message>'
- Push to the original branch:
git push origin <project_name>/<location>
- Create the pull request.
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.
Feel free to contact the project maintainers: