Ushahidi Installation Instructions
(→Add a Twitter Feed) |
|||
| Line 9: | Line 9: | ||
We are running it with Virtual Box. | We are running it with Virtual Box. | ||
| − | # Download [ | + | # 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 | + | # 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 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. | # 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 | ||
| Line 27: | 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 62: | Line 62: | ||
===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 | ||
| Line 75: | Line 75: | ||
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 a Database in MySQL=== | ===Create a Database in MySQL=== | ||
| Line 96: | Line 96: | ||
===Download, Install, and Configure Ushahidi=== | ===Download, Install, and Configure Ushahidi=== | ||
| − | In the guest machine (that is the virtual machine), download the Ushahidi code from [http://www.ushahidi.com/products/ushahidi-platform the Ushahidi | + | 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). |
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.) | 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.) | ||
| Line 138: | Line 138: | ||
* And you don't need a prefix | * 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 | + | 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). | 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). | ||
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.
- Download VirtualBox. You'll need to choose the version appropriate for your machine.
- Download Version 3 of the Harvard CS50 Appliance
- 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
- 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).
- You may have to configure the network. There are troubleshooting instructions on the reference page for the CS50 Appliance under VirtualBox.
- Start the machine.
- 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.
