About the Codebase

The OpenPolice.org codebase is mostly PHP and extends SurvLoop, which was built for it. The OpenPolice package powers OpenPolice.org to collect and share data, and manage site content.

SurvLoop is an open data engine mostly written PHP, with a fair amount of JavaScript/jQuery for the front-end. Please share any problems you see that could be barriers to entry for other developers. These include issues with code, development processes, community standards, etc. Thank you!


1. Install Homestead

Locally On A Mac

Replace all references to "openpolice" with a short name for your own project.
  1. Install XCode from the App Store. Open it, and accept the user agreement.
  2. Install VirtualBox: https://www.virtualbox.org/wiki/Downloads
  3. Install Vagrant: https://www.vagrantup.com/downloads.html
  4. To the command line (Mac OS Terminal, or iTerm)! Create local ssh key, if you haven't on this computer before:
    $ ssh-keygen -t rsa -C "your@emailaddress.com"
  5. Install Composer, Homestead, and initialize. For this example, the work area's directory is "~/web", but you can adjust it as needed:
    $ vagrant box add laravel/homestead
    $ curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer $ cd ~/ $ git clone https://github.com/laravel/homestead.git homestead $ cd homestead
    $ git checkout release $ bash init.sh

     

  6. Edit paths in Homestead.yaml:
    $ nano Homestead.yaml
    Change the folders and sites to:
    folders: 
        - map: ~/homestead/code
          to: /home/vagrant/code
    
    sites:
        - map: openpolice.local
          to: /home/vagrant/code/openpolice/public

     

  7. Auto-add project(s) to the the /etc/hosts file:
    $ vagrant plugin install vagrant-hostsupdater



2. Install Laravel

$ cd ~/homestead
$ mkdir code
$ cd code
$ composer create-project laravel/laravel openpolice "5.8.*"
$ cd openpolice

Edit the environment file to connect the default MYSQL database:

$ nano .env
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

You could do things like install Laravel's out-of-the-box user authentication tools, and push the vendor file copies where they need to be:

$ php artisan make:auth
$ echo "0" | php artisan vendor:publish --tag=laravel-notifications

3. Install FlexYourRights/OpenPolice

From your Laravel installation's root directory, update `composer.json` to require and easily reference OpenPolice:

$ nano composer.json
...
"require": {
 ...
    "wikiworldorder/survloop": "^0.2.10",
    "flexyourrights/openpolice": "^0.2.10",
 ...
},
...
"autoload": {
 ...
 "psr-4": {
    ...
   "SurvLoop\": "vendor/wikiworldorder/survloop/src/",
    "OpenPolice\": "vendor/flexyourrights/openpolice/src/",
  }
 ...
}, ...

After saving the file, run the update to download OpenPolice, and any missing dependencies.

$ composer update

Laravel Config

Add the package to your application service providers in `config/app.php`.

$ nano config/app.php
...
'providers' => [
  ...
 SurvLoopSurvLoopServiceProvider::class,
 OpenPoliceOpenPoliceServiceProvider::class,
 ...
],
...
'aliases' => [
 ...
 'SurvLoop' => 'WikiWorldOrderSurvLoopSurvLoopFacade',
  'OpenPolice' => 'FlexYourRightsOpenPoliceOpenPoliceFacade',
  ...
], ...

Swap out the OpenPolice user model in `config/auth.php`.

$ nano config/auth.php
...
'model' => AppModelsUser::class,
...

Migrate, Publish, and Clean Up

Update composer, publish the package migrations, etc...

$ echo "0" | php artisan vendor:publish --force
$ cd ~/homestead
$ vagrant up
$ vagrant ssh
$ cd code/openpolice
$ php artisan migrate
$ composer dump-autoload
$ php artisan db:seed --class=OpenPoliceSeeder
$ php artisan db:seed --class=OpenPoliceSLSeeder
$ php artisan db:seed --class=OpenPoliceDeptSeeder
$ php artisan db:seed --class=ZipCodeSeeder $ php artisan optimize:clear

For now, to apply database design changes to the same installation you are working in, depending on your server, you might also need something like this...

$ chown -R www-data:33 app/Models
$ chown -R www-data:33 database

You might need to re-run some things outside the virtual box too, e.g.

$ exit
$ cd ~/homestead/code/openpolice
$ php artisan optimize:clear
$ composer dump-autoload

Initialize OpenPolice Installation

Then browsing to the home page should prompt you to create the first admin user account:

https://openpolice.org

If everything looks janky, then manually load the style sheets, etc:

https://openpolice.org/css-reload

After logging in as an admin, this link rebuilds many supporting files:

https://openpolice.org/dashboard/settings?refresh=2

You can also connect to the database with apps like Sequel Pro, and default login info.... Host: 127.0.0.1 , Username: homestead , Password: secret , Port: 33060 , Database: homestead .


New To Laravel?

Here are some of the basic lessons I've learned in my first three years...

Clearing Caches

You've made changes, but they aren't taking root. You might be able to turn that off and on again with one the common cache clears. These can be run from your Laravel installation's root:

$ php artisan vendor:publish --force
$ php artisan cache:clear
$ php artisan route:cache
$ php artisan view:clear
$ php artisan config:cache
$ php artisan optimize

New To Composer?

Here are some of the basic lessons I've learned in newb land...

$ composer dump-autoload

Thank You!

After following those instructions, hopefully you should have a functioning installation to start tinkering with. Please contact us if you hit any big errors or have corrections or improvements to this install process. We hope you'll help make it harder, better, faster, and stronger for complainants, police oversight investigators, and the whole community!


Updated: November 3, 2019