Ushahidi Installation Instructions

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
(Stole text from the main Ushahidi page.)
 
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
''This page is under development.  It is an attempt to record the strategy we used in the POSSE2013 workshop.''
 +
 
===Set up a Virtual Machine===
 
===Set up a Virtual Machine===
  
Line 7: Line 9:
 
We are running it with Virtual Box.   
 
We are running it with Virtual Box.   
  
−
# Download [ttps://www.virtualbox.org/ VirtualBox].  You'll need to choose the version appropriate for your machine.   
+
# Download [https://www.virtualbox.org/ VirtualBox].  You'll need to choose the version appropriate for your machine.   
−
# Download [http://mirror.cs50.net/appliance/3/cs50-appliance-3-15-ovf.zip Version 3 of the Harvard CS50 Applicance]
+
# Download [http://mirror.cs50.net/appliance/3/cs50-appliance-3-15-ovf.zip Version 3 of the Harvard CS50 Appliance]
−
# Unzip the CS50 Appliance file.  You should see ...
+
# Unzip the CS50 Appliance file.  You should see a folder with two files: One is cs50-appliance-3-disk1.vmdk, the other is cs0-appliance-3.ovf.  The first is a the disk.  The second has the machine settings.
 
# Install Virtual Box
 
# Install Virtual Box
 
# Import the appliance into VirtualBox.  If you need help, refer to [https://manual.cs50.net/CS50_Appliance_3/VirtualBox the reference page for the CS50 Appliance under VirtualBox].  It will probably take about fifteen minutes (at least it did for some of us).
 
# Import the appliance into VirtualBox.  If you need help, refer to [https://manual.cs50.net/CS50_Appliance_3/VirtualBox the reference page for the CS50 Appliance under VirtualBox].  It will probably take about fifteen minutes (at least it did for some of us).
Line 18: Line 20:
 
''Congratulations!  You have a virtual machine in which to play.''
 
''Congratulations!  You have a virtual machine in which to play.''
  
−
===Set Up Web Server===
+
===Set Up the Web Server===
  
 
Before we go about installing Ushahidi, we want to make sure that the Web server, PHP, and MySQL work correctly.  If you're not familiar with Apache, it tends to look for a user's Web materials in the <code>public_html</code> directory.  So you need to make that directory.
 
Before we go about installing Ushahidi, we want to make sure that the Web server, PHP, and MySQL work correctly.  If you're not familiar with Apache, it tends to look for a user's Web materials in the <code>public_html</code> directory.  So you need to make that directory.
Line 25: Line 27:
 
   $ mkdir public_html
 
   $ mkdir public_html
  
−
However, by default, Linux keeps things private.  And private means that no one, not even the Web server, can access them.  So you need to make things public.  Ideally, the home directory should not be readable.  But it needs to grant access to the public_html subdirectory.  In Linux terms, it needs to be "world executable".  The public_html directory needs to be both readable and executable (that is, people need to be able to see what files are there and to read those files).
+
However, by default, Linux keeps things private.  And private means that no one, not even the Web server, can access them.  So you need to make things public.  Ideally, the home directory should not be readable.  But it needs to grant access to the <code>public_html</code> subdirectory.  In Linux terms, it needs to be "world executable".  The <code>public_html</code> directory needs to be both readable and executable (that is, people need to be able to see what files are there and to read those files).
  
 
   $ cd /home/jharvard
 
   $ cd /home/jharvard
Line 49: Line 51:
 
Again, this file is private by default, so we need to make it public.
 
Again, this file is private by default, so we need to make it public.
  
−
   # chmod a+r index.html
+
   $ chmod a+r index.html
  
 
We're now ready to test whether the Web server is running.  Believe it or not, but you can test this on your ''host'' machine (that is, your real computer, not the virtual one).  Start by finding the IP address of your virtual machine.  It should be in the lower-right-hand corner of the screen.  It's probably something like 192.168.56.101.   
 
We're now ready to test whether the Web server is running.  Believe it or not, but you can test this on your ''host'' machine (that is, your real computer, not the virtual one).  Start by finding the IP address of your virtual machine.  It should be in the lower-right-hand corner of the screen.  It's probably something like 192.168.56.101.   
Line 56: Line 58:
  
 
If you Web server doesn't run, type
 
If you Web server doesn't run, type
−
   sudo service httpd start
+
   $ sudo service httpd start
−
 
+
  
 
===Check the PHP Installation===
 
===Check the PHP Installation===
  
−
We're getting there.  Now, we need to create a file that shows what php
+
We're getting there.  Now, we need to create a file that shows what php packages have been installed.
−
   # cd /home/jharvard/public_html
+
   $ cd /home/jharvard/public_html
−
   # cat > info.php
+
   $ cat > info.php
 
   <?php
 
   <?php
 
   phpinfo()
 
   phpinfo()
 
   ?>
 
   ?>
 
   ^D
 
   ^D
−
   # chmod a+r info.php
+
   $ chmod a+r info.php
 +
 
 +
''Once again, the ^D means Control-D.''
  
 
Visit the page in your browser at http://192.168.56.101/~jharvard/info.php.  You should see a list of PHP packages that have been installed.
 
Visit the page in your browser at http://192.168.56.101/~jharvard/info.php.  You should see a list of PHP packages that have been installed.
  
−
Once you've tested this, you should get rid of the info.php file because it tells hackers a lot about your system.  (It doesn't matter for our private virtual install, but it's still a good habit to get into removing such files.)
+
Once you've tested this, you should get rid of the <code>info.php</code> file because it tells hackers a lot about your system.  (It doesn't matter for our private virtual install, but it's still a good habit to get into removing such files.)
  
−
===Create Database in MySQL===
+
===Create a Database in MySQL===
−
We're going to create the database using the Web admin interface.  This is a good way to create a database quickly without getting into nitty-gritty details, SQL etc.
+
 
 +
Ushahidi stores all of its information in a MySQL database.  It's possible to set up that database from the command line.  However, we're going to create the database using the Web admin interface.  This is a good way to create a database quickly without getting into nitty-gritty details and worrying about SQL.
 +
 
 +
On your host machine, navigate to http://192.168.56.101/phpMyAdmin/ (updating the IP address as appropriate)
  
 
Open up your Web browser in the host machine.
 
Open up your Web browser in the host machine.
−
Go to http://192.168.56.102/phpMyAdmin/ (you may have a slightly different IP address).
+
Go to http://192.168.56.101/phpMyAdmin/ (updating the IP address as appropriate).  You will be prompted to log in.  Remember that the account is '''jharvard''' and the password is '''crimson'''..
 +
 
 +
Click on the '''Databases''' tab. 
 +
 
 +
Enter the name of the database to create (see next paragraph), leave the type as "Collation" and click '''Create'''.
  
 
For some reason, life is complicated if you don't prefix the name of the database with the name of the user.  So create a database with name beginning with ''jharvard_''  You might want to use "jharvard_ushahidi".
 
For some reason, life is complicated if you don't prefix the name of the database with the name of the user.  So create a database with name beginning with ''jharvard_''  You might want to use "jharvard_ushahidi".
  
−
===Download and Install Ushahidi===
+
That's it.  You're done setting up the database.
  
−
Get Ushahidi code from website ([http://www.ushahidi.com/products/ushahidi-platform]) or github ([https://github.com/ushahidi/Ushahidi_Web]).
+
===Download, Install, and Configure Ushahidi===
  
−
Extract zip file within VM otherwise you’ll need to sftp the files.
+
In the guest machine (that is the virtual machine), download the  Ushahidi code from [http://www.ushahidi.com/products/ushahidi-platform the Ushahidi website] or from [https://github.com/ushahidi/Ushahidi_Web github].  Please download on the guest machine (the Harvard appliance).  If you download on your host machine, you'll need to transfer the files to the guest machine (perhaps using sftp).
  
−
You can find detailed installation instructions through a Google Search. However, some Ushahidi installation guides have too much information. Possible assignment for students can be to create a new guide.
+
Detour: Exploring the wonder of open-source instructions (a possible assignment).  You might think that you can find detailed installation instructions through a Google Search. However, some Ushahidi installation guides have too much information, or worse yet, outdated information. Possible assignment for students can be to create a new guide. (We hope that guide that you are reading will suffice.)
  
−
Copy the ushahidi directory to 'public_html' directory.
+
Copy the ushahidi directory to your <code>public_html</code> directory.  The resulting data should be in <code>/home/jharvard/public_html/ushahidi</code>.
  
−
In browser (outside virtual machine) navigate to http://192.168.56.101/~jharvard/ushahidi to test if this worked.
+
In a browser on the host machine, navigate to http://192.168.56.101/~jharvard/ushahidi to test if this worked.  You should end up on an installation page.  We recommend that you start with a basic installation, so click on '''Proceed with Basic'''.
  
−
Ensure that files in the Ushahidi 'media' directory have read and execute permissions for 'other' users.
+
You should see a warning that looks something like the following about needing files to be writable.
−
chmod –R go+w media
+
−
- changes recursively inside directory
+
  
−
Click on 'Get Started'
+
<blockquote>
 +
Before you get started, you will need to make sure the following files and folders are writable by your webserver. This involves changing file permissions.
  
−
Be sure to use an easy to find database name.
+
* application/config
−
Also use an easy to find site name – preferably related to project, city, etc.
+
* application/cache
 +
* application/logs
 +
* media/uploads
 +
* .htaccess
 +
</blockquote>
  
−
Admin user name can be anything but must look like a valid email address (e.g. jharvard@example.edu)
+
Okay, now we're in dangerous territory. Ideally, we would set up a group that includes jharvard and the Web server and give group write permission to those areas.  But we're lazy, so we'll give it to everyone.
  
−
===Configure Ushahidi===
+
  $ cd /home/jharvard/ushahidi
 +
  $ chmod -R a+w application/config
 +
  $ chmod -R a+w application/cache
 +
  $ chmod -R a+w application/logs
 +
  $ chmod -R a+w media/uploads
 +
  $ chmod -R a+w .htaccess
 +
 
 +
In addition, certain files need to be readable.  (It's not clear why they're not readable by default.)  Try the following command to ensure that the Web browser can read and access the files.
 +
 
 +
  $ chmod –R go+rX /home/jharvard/ushahidi/media
 +
 
 +
Note that the -R recursively changes any files and folders within the directory.
 +
 
 +
Okay, we're ready to move forward.  Click on '''Let's Get Started'''.  First, you'll set up a database.
 +
 
 +
* You'll reuse the database name from above (e.g., jharvard_uhshaidi)
 +
* You should use your jharvard account and password
 +
* Your database host is localhost
 +
* And you don't need a prefix
 +
 
 +
Next, you'll need to provide general information about the site (name, tagline).  You may want to use your email address as the contact (or not; use anything you like).
 +
 
 +
Next, you'll set up your administrator account.  The admin user name can be anything the looks like like a valid email address (e.g. jharvard@example.edu).
 +
 
 +
Finally, you should be prompted to go to your newly-created site, http://192.168.56.101/~jharvard/ushahidi/index.php/login.
 +
 
 +
Log in.  If things worked fine, you'll see a reasonably well formatted administrative page.  If things worked badly, it will not look good.  Try make media readable again (see above).  If you can't log in at all, something has gone very wrong.  We have no advice, other than to try again.
  
 
===Add a Twitter Feed===
 
===Add a Twitter Feed===
 +
 +
[[Category:Ushahidi]]

Latest revision as of 00:29, 8 January 2019

This page is under development. It is an attempt to record the strategy we used in the POSSE2013 workshop.

Contents

Set up a Virtual Machine

We use the Harvard CS50 appliance. It's a nice, relatively complete, small Red Hat virtual machine. In addition to the full LAMP (Linux, Apache, MySQL, PHP) stack, it includes many of the things you would want for your students as they develop Web stuff. The Harvard CS50 site also has some nice basic Linux administration exercises.

The primary account is jharvard and the password is crimson.

We are running it with Virtual Box.

  1. Download VirtualBox. You'll need to choose the version appropriate for your machine.
  2. Download Version 3 of the Harvard CS50 Appliance
  3. Unzip the CS50 Appliance file. You should see a folder with two files: One is cs50-appliance-3-disk1.vmdk, the other is cs0-appliance-3.ovf. The first is a the disk. The second has the machine settings.
  4. Install Virtual Box
  5. Import the appliance into VirtualBox. If you need help, refer to the reference page for the CS50 Appliance under VirtualBox. It will probably take about fifteen minutes (at least it did for some of us).
  6. You may have to configure the network. There are troubleshooting instructions on the reference page for the CS50 Appliance under VirtualBox.
  7. Start the machine.
  8. Once the machine has started, you can install Guest Additions under Virtual Box. Ideally, that will let you copy files between OS's and let the resolution of the guest machine match the size of the window you give it. (Unfortunately, those of us working on Macs could not get the guest additions to work reliably.)

Congratulations! You have a virtual machine in which to play.

Set Up the Web Server

Before we go about installing Ushahidi, we want to make sure that the Web server, PHP, and MySQL work correctly. If you're not familiar with Apache, it tends to look for a user's Web materials in the public_html directory. So you need to make that directory. 

 $ cd /home/jharvard
 $ mkdir public_html

However, by default, Linux keeps things private. And private means that no one, not even the Web server, can access them. So you need to make things public. Ideally, the home directory should not be readable. But it needs to grant access to the public_html subdirectory. In Linux terms, it needs to be "world executable". The public_html directory needs to be both readable and executable (that is, people need to be able to see what files are there and to read those files). 

 $ cd /home/jharvard
 $ chmod go+x .
 $ chmod go+rX public_html

We need a sample file. So let's create a very simple index.html. (Please don't be offended at the inadequate HTML. This example is intended to be a quick and dirty hack. 

 $ cd /home/jharvard/public_html
 $ cat > index.html
 <html>
 <head>
 <title>Welcome to the example</title>
 </head>
 <body>
 Welcome to the machine.
 </body>
 </html>
 ^D

In case you didn't know, ^D represents hitting the Control key and the D key simultaneously.

Again, this file is private by default, so we need to make it public. 

 $ chmod a+r index.html

We're now ready to test whether the Web server is running. Believe it or not, but you can test this on your host machine (that is, your real computer, not the virtual one). Start by finding the IP address of your virtual machine. It should be in the lower-right-hand corner of the screen. It's probably something like 192.168.56.101.

In the Web browser on your host machine, go to http://192.168.56.101/~jharvard (change the IP address to the address that shows up in your host machine). You should see a Web page.

If you Web server doesn't run, type 

 $ sudo service httpd start

Check the PHP Installation

We're getting there. Now, we need to create a file that shows what php packages have been installed. 

 $ cd /home/jharvard/public_html
 $ cat > info.php
 <?php
 phpinfo()
 ?>
 ^D
 $ chmod a+r info.php

Once again, the ^D means Control-D.

Visit the page in your browser at http://192.168.56.101/~jharvard/info.php. You should see a list of PHP packages that have been installed.

Once you've tested this, you should get rid of the info.php file because it tells hackers a lot about your system. (It doesn't matter for our private virtual install, but it's still a good habit to get into removing such files.)

Create a Database in MySQL

Ushahidi stores all of its information in a MySQL database. It's possible to set up that database from the command line. However, we're going to create the database using the Web admin interface. This is a good way to create a database quickly without getting into nitty-gritty details and worrying about SQL.

On your host machine, navigate to http://192.168.56.101/phpMyAdmin/ (updating the IP address as appropriate)

Open up your Web browser in the host machine. Go to http://192.168.56.101/phpMyAdmin/ (updating the IP address as appropriate). You will be prompted to log in. Remember that the account is jharvard and the password is crimson..

Click on the Databases tab.

Enter the name of the database to create (see next paragraph), leave the type as "Collation" and click Create.

For some reason, life is complicated if you don't prefix the name of the database with the name of the user. So create a database with name beginning with jharvard_ You might want to use "jharvard_ushahidi".

That's it. You're done setting up the database.

Download, Install, and Configure Ushahidi

In the guest machine (that is the virtual machine), download the Ushahidi code from the Ushahidi website or from github. Please download on the guest machine (the Harvard appliance). If you download on your host machine, you'll need to transfer the files to the guest machine (perhaps using sftp).

Detour: Exploring the wonder of open-source instructions (a possible assignment). You might think that you can find detailed installation instructions through a Google Search. However, some Ushahidi installation guides have too much information, or worse yet, outdated information. Possible assignment for students can be to create a new guide. (We hope that guide that you are reading will suffice.)

Copy the ushahidi directory to your public_html directory. The resulting data should be in /home/jharvard/public_html/ushahidi.

In a browser on the host machine, navigate to http://192.168.56.101/~jharvard/ushahidi to test if this worked. You should end up on an installation page. We recommend that you start with a basic installation, so click on Proceed with Basic.

You should see a warning that looks something like the following about needing files to be writable.

Before you get started, you will need to make sure the following files and folders are writable by your webserver. This involves changing file permissions.
  • application/config
  • application/cache
  • application/logs
  • media/uploads
  • .htaccess

Okay, now we're in dangerous territory. Ideally, we would set up a group that includes jharvard and the Web server and give group write permission to those areas. But we're lazy, so we'll give it to everyone. 

 $ cd /home/jharvard/ushahidi
 $ chmod -R a+w application/config
 $ chmod -R a+w application/cache
 $ chmod -R a+w application/logs
 $ chmod -R a+w media/uploads
 $ chmod -R a+w .htaccess

In addition, certain files need to be readable. (It's not clear why they're not readable by default.) Try the following command to ensure that the Web browser can read and access the files. 

 $ chmod –R go+rX /home/jharvard/ushahidi/media

Note that the -R recursively changes any files and folders within the directory.

Okay, we're ready to move forward. Click on Let's Get Started. First, you'll set up a database.

  • You'll reuse the database name from above (e.g., jharvard_uhshaidi)
  • You should use your jharvard account and password
  • Your database host is localhost
  • And you don't need a prefix

Next, you'll need to provide general information about the site (name, tagline). You may want to use your email address as the contact (or not; use anything you like).

Next, you'll set up your administrator account. The admin user name can be anything the looks like like a valid email address (e.g. jharvard@example.edu).

Finally, you should be prompted to go to your newly-created site, http://192.168.56.101/~jharvard/ushahidi/index.php/login.

Log in. If things worked fine, you'll see a reasonably well formatted administrative page. If things worked badly, it will not look good. Try make media readable again (see above). If you can't log in at all, something has gone very wrong. We have no advice, other than to try again.

Add a Twitter Feed

Retrieved from "http://foss2serve.org/index.php?title=Ushahidi_Installation_Instructions&oldid=13054"
Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox