The information in this wiki hasn't been maintained for a good while. Some of the projects described have since been deprecated.

In particular, the "Ushahidi Platform v3.x" section contains information that is often misleading. Many details about this version of Platform have changed since.

This website is an extraction of the original Ushahidi wiki into a static form. Because of that, functions like logging in, commenting or searching will not work.

For more documentation, please refer to

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Installing the API


First, you will need a copy of the source code, which lives in our Github repository:

% git clone

Once you have the code, the next step is to prepare a web server.


By default, there are two options for running the Ushahidi platform locally. You can either run the Vagrant virtual machine, or you can run it locally.

Using the Vagrant virtual machine

To run the virtual machine, install Vagrant following the instructions on their website. You'll need ruby installed too.
Check the settings in the Vagrantfile then start the VM from your console:

% gem install puppet librarian-puppet

% librarian-puppet install

% vagrant up && vagrant provision

This should set up a server, and install all the dependencies too.


The vagrant set up uses a 64 bit VM so you may need to enable 64 bit virtualization on your host machine.


Using a local server

System Requirements

To install the platform on your computer/server, the target system must meet the following requirements:

  • PHP version 5.4.0 or greater
  • MySQL database version 5.5 or greater (PostgreSQL support planned)
  • An HTTP server, we develop Ushahidi using Apache 2.2+ and nginx
  • Unicode support in the operating system (UTF-8 charset, PCRE, iconv extension, etc)

To create a database, first login to MySQL as root. 

% mysql -u root -p


Using the -p is only required when your MySQL configuration requires it. You may need to use the -h option to specify localhost or if you are unable to connect.

Next, create a new user and database for Ushahidi. The username and database can be anything; we will use ushahidi for both in this example:

GRANT ALL ON ushahidi.* to ushahidi@localhost IDENTIFIED BY 'set-a-custom-password-here';

Now copy the database.php config file into environments/development/ and edit it. Make sure that the database, username, and password match the database you just created.

% cp application/config/database.php application/config/environments/development/database.php
% $EDITOR application/config/environments/development/database.php 

You should also rename template.htaccess in httpdocs to .htaccess (for Apache) to enable rewriting of all non-existent files to index.php. If you do not want to, or are unable to, enable rewriting, then customize the initialization settings by also copying the init.php config file into environments/development/ and editing it, setting index_file to "index.php"


A note on urls, docroots and base_url

Typically, Ushahidi is run under a separate virtual host / domain name. Be sure to make platform/httpdocs/ the DocumentRoot (for Apache) or root (for nginx) setting in your virtual host.

If you are running Ushahidi via http://localhost/ then the base_url will be http://localhost/platform/httpdocs/

Enable writing to the logs, cache, and upload directories:

% chmod 0777 application/logs application/cache application/media/uploads

If you are running in shared or production environment, it is better to use chown to set the owner of the directories to the user that runs the web server runs as, rather than making them globally writable.

Installing dependencies

We use Composer to manage server side dependencies. Once you have installed composer, you can run the update script with:

% bin/update

Whenever the repository is updated using git pull, run the update script to ensure that your installation stays updated!

If you are updating a production deployment, you will want to avoid installing developer dependencies (testing tools, etc) by using the "deploy" option:

% bin/update --production

Logging in the first time

The default install creates a user admin with password admin. Once logged in this user can create further user accounts or give others admin permissions too.


Base config files are in application/config/.

You can add per-environment config overrides in application/config/environments/. The environment is switched based on the KOHANA_ENV environment variable.

Routes are configured in application/routes/default.php. Additional routes can be added in per-environment routing files ie. application/routes/development.php

Installing the client

Getting the code

First, you will need a copy of the source code, which lives in our Github repository:

% git clone

Once you have the code, open up the readme: and follow the instructions there.

Please check for current install docs