Webfaction: Installing and Working with Ushahidi

Ushahidi is a free and open source web mapping platform that is designed to be used to collect data. One of its primary draws is its capability to collect data and utilize mobile devices. Ushahidi is built and maintained by a non-profit company of the same name. Ushahidi, as a company, develops and produces a suite of software, such as Crowdmap, CrisisNET, and SMSsync. To read more on the company and their products, check out the Ushahidi website.

One way to think of Ushahidi is as a 'WordPress for Maps'. You install an instance of the software on your server, that you can fully administer and customize.

To get an idea for the types of maps that are being created with Ushahidi and view some examples of work that has been done, check out the Ushahidi Types of Maps wiki page.

Installing Ushahidi and WebFaction

This tutorial will utilize the current release, Ushahidi Version 2.7.4. Ushahidi 3.0 is in development, and appears as if it will be released soon. Installing Ushahidi is straightforward, but there are a handful of steps. There are many resources for installing Ushahidi on a variety of different servers and operating systems. You can work with Ushahidi locally, or place it on your server for a live, web-facing map. Some of the resources are found on the Ushahidi Installation Guide webpage.

Installation instructions from the Ushahidi Wiki

This tutorial will go over the process of installing Ushahidi on WebFaction, a hosting site designed specifically for developing and constructing new applications and webpages. As mentioned above, the process for installing Ushahidi is straightforward, yet contains some nuances. At the end of this tutorial, you will have a live working Ushahidi installation, and be shown how to start customizing your installation. Let's get going!



1. Getting Started

The general workflow for installing Ushahidi on our WebFaction account goes like the following. We will break down each step to explain further what is going on.

  1. Create a new website for your Ushahidi map and page.
  2. Create an app for that website that allows it to use PHP.
  3. Create a mySQL database that your Ushahidi install can use.
  4. Download the Ushahidi files to your computer, unzip, and place them on your server.
  5. Set server settings to make sure you can write to specific files
  6. Navigate to your Ushahidi site using a web browser.
  7. Follow the step-by-step instructions given by the Installation Wizard.

Login to WebFaction and Navigate to your Control Panel

To start, login to your WebFaction account and go to your control panel. Here we will create our website and the mySQL database, then we will download files from Ushahidi, unzip and place them on our server using FTP, and then navigate to our website and run the online Ushahidi installer wizard.

a. Create a New Website

In the Control Panel, navigate to Domains/Websites -> Websites. Here click Add new website. In the new website window, enter the following.

  • Name: ushahidi
  • Status: Enabled
  • IP Address: (leave default)
  • Security: Encripted website (https)
  • Domains: Set this to be ushahidi.(your username).webfactional.com
  • Contents: Add an Application -> Create a new application. We want a Give it the following properties.
    • Name: ushahidi
    • App category: Static
    • App type: Static/CGI/PHP-5.4
    • URL: Leave default, should be the same as your set above.

The dialog will show the following. When satisfactory, click Save to create your new website. Make sure your new website is HTTPS! If not, we will see errors.


New application.

New website.

New website.

b. Create a new mySQL database

Ushahidi uses mySQL, an open-source relational database. To install Ushahidi, we need to tell it to use a specific mySQL database, it unfortunately does not automate this process. Therefore, on WebFaction, we need to create one for it to use.

In the Control Panel, navigate to Databases -> Databases. Here click Add new database. In the new website window, enter the following.

  • Name: ushahididb
  • Database type: MySQL
  • Encoding: (leave default)
  • Database owner: Create a new mysql user (https)
    • Set a username and password for your new user. Write this down! You will need it for the install.

Click Save. We now have a website, application, and database we can use to install Ushahidi on.

c. Download the Ushahidi files to your computer and put on your server.

Next we have to download the installation files. If you have worked with Drupal or Wordpress, it is quite similar in practice. Download the files, unzip them, you will see a full structure of folders and files that drive Ushahidi, and upload ALL of the files to your server folder.

Download the Ushahidi Files

The Ushahidi download can be found on here:

Ushahidi homepage

Scan down the page and locate Get the Ushahidi Platform and the Download link. Click the link. A zip file will begin to download to your machine. Save this in a place you can work with it, it contains all of the files we need to install Ushahidi.

Unzip the downloaded file and connect to FTP

Unzip your downloaded Ushahidi folder. It will be called Ushahidi_Web-2.7.4. This means we have version 2.7.4. Unzip the files. This unzipped folder contains all the materials and files Ushahidi needs to run. We will upload ALL OF THE CONTENTS to our server folder.

Connect to your WebFaction hosting folder via your FTP client. For instructions on how to complete this, visit the link below. The MIT recommended and cron supported client for both Mac and Windows is Cyberduck. Other options are SecureFX (for Windows), FileZilla (cross-platform), and FireFTP (a Firefox extension).

A short tutorial on WebFaction FTP access can be found here: DUSPVIZ FTP Access Tutorial

Use the FTP to upload the unzipped Ushahidi files to WebFaction

Once logged into your website via your FTP client, navigate to webapps -> ushahidi on your server. This is the ushahidi application we created in the previous steps, and this is the location we want to upload all of our files. Upload the downloaded and unzipped contents of the Ushahidi folder to this location.

Put all of your unzipped files into the ushahidi folder you created.


Copy and Paste the Following Files

It is important to get every folder and file that is included in the downloaded materials in your installation. When you copy and paste, make sure you get ALL of the files. The directory of files you upload to your server should look like the following.

When transferring, if asked by your FTP client, make sure you transfer all files as ASCII file types, not Binary.


There are a large number of files, almost 6,000. This may take a while.

d. After upload, check server settings to make sure you can write to specific files.

When the files are done uploading, double check on the write privileges of five files. The installer needs access to a few specific files in order to complete the install. In your FTP client, once the files are uploaded, check the properties for each of the following folders and files to make sure that they are writable. This is usually found by right clicking and navigating to Properties, then allowing all users to be able to Read, Write, and Execute specific folders and files.

  • application/logs
  • application/cache
  • application/config
  • media/uploads
  • .htaccess

Change all of these to be writable in the properties of each folder.

If there is an index.html in addition to an index.php file in your Ushahidi folder after upload, you can delete the index.html. If it has both, it will not load.

Once these files are set to be writable, we are done uploading items to the server and can navigate to our Ushahidi website! Once on the website, we will finish our installation using the Ushahidi wizard.

e. Navigate to your Ushahidi website using a web browser.

We are now ready to install Ushahidi. Navigate to your website at:

https://ushahidi.(your url).webfactional.com/installer/

Note: It is important to include the https://. and it may take a minute or two for WebFaction servers to propagate. You will likely have to type the whole address, including the https:// the final forward slash. The page that loads is the Ushahidi installer wizard. You will see a simple webpage that offers two options for installing Ushahidi on your site. If you see this page, your steps to this point have worked and we can continue!


Note: If you have waited a while and still do not see anything, try loading the site on a different computer or clear the DNS cache on your machine. To clear the DNS cache, follow the instructions to Flush the DNS cache on your machine at the bottom of the WebFaction Domains Help page.

This installation process does a couple of things, it runs the scripts to complete the install, sets up the link to our mySQL database, and creates an account we can use to log in to our Ushahidi instance. We can use the basic installation for now, and set other settings later. Click on Basic Installation, and you'll see the following screen. We have done these steps, and are ready to proceed.


Click Lets get started! to move on.

Tell Ushahidi to use your new MySQL database: Enter database credentials

Enter your database credentials for your mySQL database. This is what you created earlier in the exercise. Your database name will be the name you decided (ushahididb), and the host will be your WebFaction server (webXXX.webfaction.com). Leave the last field blank and continue.


Click continue, if your database credentials are all correct and Ushahidi can connect, it will move on to the next screen. If not, it will notify you of errors.

Name your site and email

Give your site a name, tagline, and an email. Use your email so you can make you receive correspondence.


Click continue.

Input your desired Email (username) and Password

Input the credentials you want for the site. Write this down, you will need these to log in to your Ushahidi instance once we are completed with installation. Again, think of Ushahidi as a WordPress for Maps. We will log into our interface with these credentials, but we can administer the back end by accessing our server.

You can use the same email as before, and remember to write down your password!


Click continue. This will complete our installation, and we can proceed to our map and begin working with various components.


Lets visit our site. It might take a few minutes for the servers to propagate!

2. Visit our Ushahidi site and log in

After waiting a few minutes for the servers to catch up, navigate to your Ushahidi page. It will be at:

https://ushahidi.(your url).webfactional.com/

Here you will see your basic default Ushahidi page. If you don't see your page, make sure you are going to https:// and that you have the last slash in your URL. If you are still having trouble, try typing in /index.php at the end of the URL. It is a bit finicky.


Log in to your page by clicking on Login in the upper right corner. Use the credentials you gave yourself. You will see a dashboard. Here you can administer, customize, and monitor your map.

Note: Your browser might tell you that security certificates for webfaction.com and webfactional.com do not match. You can proceed anyway. The connection is still encrypted, don't worry.

3. Secure our Installation

With Ushahidi installed, there are some steps you need to take to secure your installation to help ensure that your web map and web site will not be hacked. Follow the instructions at the following link, going step-by-step. Change files or delete them using your FTP client.

1. Set your site URL in the config.php file.

Set your cookie domain. This will prevent cookies from other websites from being used on your page. Cookies are small pieces of data that are stored in a browser that track you, often for the purpose of targeted advertising. Disable these from anything other than your site. Navigate to application/config/cookie.php on your server using your FTP client and change the following line to your domain name.

$config['domain'] = '';
$config['domain'] = 'ushahidi.(username).webfactional.com';

2. Use Secure HTTP (HTTPS)

We have done this by using HTTPS to create our site! However, you still get a browser error because of the WebFaction certificates. The best way around this is to get a custom domain (you could purchase this, whatever you want) and then get a certificate. This is beyond the scope for now, but if you want to do this, please contact Mike.

3. Delete your installer folder

A major step you can take in protecting your site is to delete the installer folder. The installer folder contains the installation wizard we used to run through the previous steps. It sits on your server and can be accessed by anyone if it is there, so theoretically they could go in and overwrite or damage our site. We have to delete this folder so that no one else goes to the installer on our site and overwrites or messes up our files.

a. In your FTP client, navigate to the location of your files. webapps -> ushahidi

b. Locate installer. Right click and delete this folder.

Further reading on Securing your site

This should be fine for now when it comes to securing our site, but if you want to read more, check out the Ushahidi wiki. This details the items we just discussed, along with a couple other steps you could take to secure Ushahidi.


4. Explore Ushahidi and Customize

The Ushahidi framework has many different ways to customize and implement your mapping application. Some of these include data input from Twitter (based on a hashtag) and setting up FrontlineSMS to allow for data submission via SMS messaging. A fantastic tutorial was made for the Crowd Sourced City class a couple years ago by DUSP PHD Cressica Brazier. Check it out here:


You can also search through the Ushahidi Types of Maps gallery to see functionality.

Good luck, and happy mapping!

Go Back to DUSPviz Tutorials Page