#AlertME is built using Laravel, the PHP framework for web artisans. For more information on getting started with Laravel, check out there extensive documentation here.
- PHP v5.4.7+
- Git
- Composer
- Beanstalkd
- MySQL
- Mcrypt PHP Extension
- OpenSSL PHP Extension
- Mbstring PHP Extension
- Tokenizer PHP Extension
- 256MB RAM
As of PHP 5.5, some OS distributions may require you to manually install the PHP JSON extension. When using Ubuntu or Debian, this can be done via sudo apt-get install php5-json.
We recommend setting up with Debian Wheezy. #AlertME will though be able to run on any system setup that meets the requirements.
After spinning up your instance, you should install Linux, Nginx, MySQL, PHP (LEMP). Here is a great step by step guide for Debian 7.
sudo apt-get install php5-cliGit is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
- On Debian you can install it by running
sudo apt-get install git. - For other systems, you can find installation instructions here.
Composer is the dependency manager for PHP.
- Install on *nix - https://getcomposer.org/doc/00-intro.md#installation-nix
Recommended: Install composer globally.
Currently, Debian Wheezy ships with PHP v5.4.39-0+deb7u2. To install PHP v5.5, add the following lines to /etc/apt/sources.list:
deb http://packages.dotdeb.org wheezy all
deb-src http://packages.dotdeb.org wheezy all
deb http://packages.dotdeb.org wheezy-php55 all
deb-src http://packages.dotdeb.org wheezy-php55 all
Fetch and install the GnuPG key
wget http://www.dotdeb.org/dotdeb.gpg
sudo apt-key add dotdeb.gpgTo read more on the above, check out http://www.dotdeb.org/instructions/.
Update and upgrade PHP by running the following commands:
sudo apt-get update
sudo apt-get dist-upgrade php*The Laravel Framework requires MCrypt PHP extension. To install it on debian, run the following command:
sudo apt-get install php5-mcryptFor queue services, #AlertME uses Beanstalkd. This allows us to defer the processing of a time consuming task, such as sending an e-mail, until a later time, thus drastically speeding up the web requests to the application.
On Debian, this can be installed by running the following command:
sudo apt-get install beanstalkdTo keep background tasks running e.g listening for queues to process jobs, we will need supervisor. Installation on Debian would be by running the following command:
sudo apt-get install supervisorYou can learn more about installing and managing supervisor here.
sudo apt-get install ruby-dev
# Uninstall
sudo apt-get purge libruby1.9.1 ruby-dev ruby1.9.1 ruby1.9.1-devInstall gems
sudo gem install premailer getopt nokogirisudo apt-get install mysql-server-5.6curl -sL https://deb.nodesource.com/setup | sudo bash -
sudo apt-get install -y nodejsOptional: if you run node and npm in shell and they don't work, you can fix them as such:
sudo ln -s /usr/bin/nodejs /usr/bin/node
curl -L https://npmjs.org/install.sh | sudo shNow let's install grunt-cli and bower as such:
sudo npm install -g grunt-cli
sudo npm install -g bowerNow that we have our server set up, we can set up the application. Here, we clone the main repository and install the needed packages. At the end, we should be able to see a welcome page displayed on the browser.
Cloning from github is as simple as running the following command:
git clone https://github.com/CodeForAfrica/AlertME.git(Optional) You can checkout the branch (recommended: master (default), develop) you want by running the following commands:
cd AlertME
git checkout [<branch>]Run the composer install command in the root of the cloned project's directory. This command will download and install the dependencies.
In this step, we'll use the simple MySQL but feel free to explore with any other Database you like. Currently Laravel supports four database systems: MySQL, Postgres, SQLite, and SQL Server; out of the box.
First, we create the alertme user and alertme database. Connect to the server as MySQL root user using the command mysql -u root -p and then run the following:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'alertme'@'localhost'
-> IDENTIFIED BY 'YOUR_DB_PASSWORD' WITH GRANT OPTION;
mysql> SHOW GRANTS FOR 'alertme' @ 'localhost';
mysql> CREATE DATABASE alertme;
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
-> ON alertme.*
-> TO 'alertme'@'localhost';Duplicate .env.examlple file and name the duplicate to .env.
cd ~/AlertME
cp .env.example .envGenerate YOUR_SECRET_KEY by running php artisan key:generate and copying the resulting key into .env.
In the .env file make sure to edit the following:
...
DB_HOST=localhost
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret
...Read more on configuration here.
With the database set up, we can do the database migration. To do this, run the php artisan migrate command in the root of the cloned project's directory.
Optional: You can define the environment by adding --env=[<environment>] argument. For example php artisan migrate --env=local.
Queue configuration to run tasks in the background requires mainly configuration of supervisor to initiate the listener. Create and edit the /etc/supervisor/conf.d/alertme.conf file. In the file, add the following:
[program:beanstalkd]
command=beanstalkd
[program:alertme_queue_worker]
command=php artisan queue:listen --timeout=0 --memory=256 --tries=5 --queue=alertme,default
directory=/path/to/AlertME
stdout_logfile=/path/to/AlertME/storage/logs/supervisor_queue.log
To create multiple workers, duplicate the following section in the supervisor configuration:
[program:alertme_queue_worker_1]
command=php artisan queue:listen --timeout=0 --memory=256 --tries=5 --queue=alertme,default
directory=/path/to/AlertME
stdout_logfile=/path/to/AlertME/storage/logs/supervisor_queue.log
Once saved, reload supervisor as such:
sudo supervisorctl
supervisor> reload
supervisor> exitRunning sudo supervisorctl again, should show you the programs running.
If you get the following error unix:///tmp/supervisor.sock no such file, you need to start supervisor as such:
sudo supervisord -c /etc/supervisor/supervisor.confFirst create ssl keys:
sudo mkdir /etc/nginx/ssl
cd /etc/nginx/ssl
sudo openssl genrsa -des3 -out server.key 2048
sudo openssl req -new -key server.key -out server.csr
# Remove passphrase ?
sudo cp server.key server.key.org
sudo openssl rsa -in server.key.org -out server.key
# Sign SSL Certificate
sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
# Confirm Certificate
sudo cp /etc/nginx/ssl/* /usr/local/share/ca-certificates/
sudo update-ca-certificates -fYou can read more on SSL with nginx here.
Finally, to see the page on example.com you would need to add the file /etc/nginx/sites-available/alertme with the following:
server {
listen 443;
root /path/to/AlertME/public;
index index.php index.html index.htm;
server_name example.com alertme;
ssl on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
server {
listen 80;
server_name example.com alertme;
return 301 https://$server_name$request_uri;
}Enable the site by creating a symlink:
sudo ln -s /etc/nginx/sites-available/alertme /etc/nginx/sites-enabled/alertme
sudo service nginx restartNow if you visit example.com, you will be able to see the basic #AlertME website loaded.
We've created a simple command to upgrade the platform from the git branch you are on.
In the root folder, simply run:
php artisan pahali:upgradeSometimes the command has also been updated so try to run it twice if things don't look right.
Note: This command does a hard reset for git so please make sure to check the status of all tracked files.
Hint: It's all about the Dashboard.
We care about sharing improvements.
The GPL (V2 or V3) is a copyleft license that requires anyone who distributes your code or a derivative work to make the source available under the same terms. V3 is similar to V2, but further restricts use in hardware that forbids software alterations.
Linux, Git, and WordPress use the GPL.
Find out more by checking out the LICENSE file here.
Have any questions? Feel free to reach us at kazini@codeforafrica.org.
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable, creative experience to be truly fulfilling. Laravel attempts to take the pain out of development by easing common tasks used in the majority of web projects, such as authentication, routing, sessions, queueing, and caching.
Laravel is accessible, yet powerful, providing powerful tools needed for large, robust applications. A superb inversion of control container, expressive migration system, and tightly integrated unit testing support give you the tools you need to build any application with which you are tasked.
Documentation for the framework can be found on the Laravel website.
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the Laravel documentation.
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell at taylor@laravel.com. All security vulnerabilities will be promptly addressed.
The Laravel framework is open-sourced software licensed under the MIT license