Install

Install

About this guide

These instructions focus on installing crm on an Ubuntu machine with the Apache webserver. If you are installing on a different OS, you will need to do the equivalent steps for your environment.

You should already have installed all the system requirements.

Downloading

The latest stable release is available at Github.

If you want to live on the bleeding edge, new features and bug fixes take place in the master branch. You can checkout the latest copy of the source code with the command:

git clone https://github.com/City-of-Bloomington/uReport.git

Uncompressing

You can uncompress the tarball with the command (replacing "x.x.x" with your downloaded version number):

tar xzvf ureport-x.x.x.tar.gz

You can then remove the tarball:

rm ureport-x.x.x.tar.gz

Moving into place

You can move the crm directory anywhere accessible by Apache. We'll be editing Apache's configuration to tell it where we've put the application.

Apache will need read permissions for the application and write permissions for the data directory inside the application. The easiest thing to do is just give Apache ownership of the application.

chown -R apache crm

Apache Configuration

We need to tell Apache where the application is and set up the URL to host it. We also need to set up the mod_rewrite rules to route all traffic to index.php.

PHP ini settings

Rather than editing the php.ini file, we include the ini settings in the Apache configuration.

PHP default values for post_max_size and upload_max_filesize are usually very small. Employees and members of the public can upload photos and other files to attach to reports. You should adjust these values for your expected use case.

Example configuration:

RewriteEngine On

Alias /crm/COB "/srv/data/ureport/Themes/COB/public"
<Directory     "/srv/data/ureport/Themes/COB/public">
    Options FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

Alias /crm/media "/srv/data/ureport/media"
<Directory       "/srv/data/ureport/media">
    Options FollowSymLinks
    AllowOverride None
    Require all granted

    RewriteBase /crm
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule .? /crm/index.php [NC,L]
</Directory>

Alias /crm "/srv/sites/ureport/public"
<Directory "/srv/sites/ureport/public">
    Options FollowSymLinks
    AllowOverride None
    Require all granted

    RewriteBase /crm
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule .? /crm/index.php [NC,L]

    php_value post_max_size 10M
    php_value upload_max_filesize 10M
    php_value error_reporting 32767
    php_value log_errors on
    php_value html_errors off
    php_value arg_separator.output ";"
    php_value arg_separator.input  ";&"

    SetEnv SITE_HOME /srv/data/ureport
</Directory>

MySQL setup

You will need to create a database for CRM. It's safest to create a user just for this database. In MySQL, here's how to create a database, called "crm". We can also create a user with a username of "crm" and create a password for that user.

create database crm;
grant all privileges on crm.* to crm@localhost identified by 'somepassword';
flush privileges;

The database is now created, but it is still empty. We need to create all the tables needed inside the database, and load those tables with some initial data. In /scripts is a mysql.sql that will do just that. We can use the mysql command line to load this script.

cd /scripts
mysql -p crm < mysql.sql

CRM configuration

The configuration setup has changed over time. There is still the bootstrap.inc, however all of the stuff you would normally customize has been moved into a seperate site_config.inc. The bootstrap.inc does not need to be edited at all.

This change has come because of the new multi-home installation support. Now, a single uReport installation can host multiple sites, each with it's own database and data directory. The data directory is now referred to as the "SITE_HOME" in bootstrap.inc.

All of the site-specific stuff is stored in this directory. This also includes any and all templating overrides. For more information on site templating, check out [Theming]

Verify installation

At this point, you should have the application installed on the webserver. With the configuration.inc in place, you should be able see the application in your browser. Point your browser to whatever URL you chose in your Apache configuration and make sure the page loads with no errors. Your should see something like this:

Create an Administrator account

At this point the application is completely empty and ready to start using. The rest of the setup will continue in the browser at your new site. However, you need to create the initial user account for you to log in with. This will need to be an Administrator account so it has permission to do all the rest of the setup. More administrators can be created as needed using the web interface.

If you prefer, you can just add a row to the people table in MySQL. Or, you can use a PHP script for this.

In your application install directory is a PHP script that can create user accounts.

include '../bootstrap.inc';

$person = new Person();

// Fill these out as needed
$person->setFirstname('Admin');
$person->setLastname('Person');
$person->setEmail('admin@localhost');
$person->setUsername('administrator');
$person->setAuthenticationMethod('local');
$person->setPassword('');

// No more changes needed
$person->setRole('Administrator');
$person->save();

Once it's been modified, you'll need to run it from the command line.

cd scripts
SITE_HOME=/path/to/data/dir php createAdminUser.php

Once the createAdminUser.php script has been run, you should be able to log into the site using the account information you just created.