Installation Overview

EgoWeb has been optimized for running on a web server and providing access to authoring and administering social network data collection interviews over the web, but it can also be installed on stand alone machines and run locally through web browsers without use of the internet. Below are instructions for the various types of installations.

NOTE: The Linux instructions below assume a web server and the Windows and Mac instructions assume local installation, but the Linux instructions apply to a local installation and EgoWeb can also be run on a Windows or Mac based web server.

Desktop and Laptop installs


Although EgoWeb was designed to be installed and run on a webserver broadcasting over the internet, it can also be installed onto a single machine and run as a local server only. Stand alone Linux machines can run the instructions above. Windows and Mac machine installation instructions are below. This installation will not allow use of some of the features that require the internet, such as sending links to respondents to fill out EgoWeb surveys or for using EgoWeb mobile.
==

==

Windows machine


Step 1) Download EgoWeb Files.

The first step for running EgoWeb on a laptop or desktop computer (for use without an active connection to the internet) is to download all of the program files onto the machine you are using. Download the latest zip file from https://github.com/qualintitative/egoweb and extract its contents onto the Desktop. There is a "Master" branch as well as a "dev" branch. Dev has more updated code by testing is in progress.

download from git.png
Downloading zip file of EgoWeb from www.github.com/qualintitative/egoweb.

Step 2) Download and Install Supporting Programs: Visual Basic Windows Update.

Because Windows cannot execute PHP scripts, additional software is necessary to run EgoWeb on a desktop or laptop running Windows OS. To run EgoWeb locally, you will need to install the software "WAMP Server". This will allow a Windows machine to mimic the functions of a webserver without broadcasting over the internet. Below are the steps for Installing WAMP Server.

NOTE: Some older versions of Windows require installation of a Windows update program called "Visual C++ Redistributable for Visual Studio 2012 Update 4" before moving onto the WAMP server software installation procedures described below. If you know that you have this update, you can skip to Step 3. However, it is probably a good idea to install and run the update just to be save. In some previous atttempts to install EgoWeb without first installing the update file above, WAMP crashed after install because of a missing *.dll file that caused the wampserver install to break. This required uninstalling wampserver, deleting the remaining wamp folder and then starting the reinstallation process again after installing the Visual C++ file. Therefore, we recommend installing this first before trying to install wampserver to be sure this does not need to happen.

The file was available for downloading at the link below when these instructions were written (but it's possible the link could change or be moved in the future):

https://www.microsoft.com/en-us/download/details.aspx?id=30679

Download and run the file from the link above and follow the default installation steps. If the link above does not work because it has been changed, a current link can be found through an internet search for “Visual C++ Redistributable for Visual Studio 2012 Update 4".

The download page looks like this:
visual c++ update 4.png
Update file to download and run before installing WAMP Server
Step 3) Download and Install Supporting Programs: WAMP Server (version 2.5)

Install WAMP Server by going to the following link and downloading the appropriate version (32 or 64 bit)

WAMPSERVER 2.5.

WAMP 2.5 screen.jpg

NOTE: We have examples of users who had installation problems with WAMP 3.0+ and the problem was fixed by using 2.5. Therefore we recommend 2.5! The main wampserver page with current versions of WAMP is at http://www.wampserver.com/en/ but this will take you to newer versions of WAMP server that cause problems. All of the installation instructions are based on WAMP version 2.5, 64-bit, so to avoid problems use this version.

Select default options for the install. Other versions may require slight variations. Therefore we recommend the 64 bit version if possible.

Step 4) Start WAMP Server and services

If it's not already running after installation, start wampserver from the windows start menu.

Start menu wampserver.jpg
Initiating Wampserver from the Start menu

NOTE: this required an admin login to run after initial set up.

Locate the WAMP menu in system tray (lower right hand side of Windows desktop screen). If the icon is not green, you may need to manually install a component. For instance, I had to manually install Apache by going to Apache -> Service -> Install Service, then start it by going to Apache -> Service -> Start Service.


start wampserver.png
WAMP Server running


Step 3) Edit httpd.conf

From the WAMP Menu, go to Apache -> httpd.conf. In Notepad, search for the phrase "AllowOverride all" and remove the hash tag character (“#”) immediately preceding it. Save the file.

apache http config.png
Locating the file httpd.conf to edit through Apache in WAMP Server



allowoverride.png
Editing httpd.conf to enable "AllowOverride all"



Step 4) Enable the rewrite module

From the WAMP menu, make sure Apache -> Apache Modules -> rewrite_module is checked. Clicking on an unchecked module will enable it.


apache modules.png




rewrite_module.png


After clicking on rewrite_module, WAMP will reboot. Follow the same steps as above to confirm that the rewrite_module has been checked.

Step 5) Launch PHPMyAdmin

Click on the WAMP menu in the system tray, and visit PHPMyAdmin, a PHP Application that allows you to manage the MySQL server in WAMP. A browser should open with PHPMyAdmin loaded. If you are prompted for a password, leave it blank and log in.
Step 6) Create default egoweb database.

In the PHPMyAdmin browser window, click on "databases." Under "Create database", put in "egoweb" for the database name (all lowercase) and select "utf8_general_ci" for the collation (recommended for fast performance). Click create. A new database named "egoweb" should appear in the left sidebar.

Step 7) Import database structure from SQL file

In the PHPMyAdmin browser window, click on "egoweb", then select "Import" from the top navigation bar. Click on the file input under "File to import". Find "egoweb_db.sql" in the “sql” folder among the extracted files on the desktop. After the file is selected, click on "Go" at the bottom of the page. The Egoweb database should now be populated with tables.

Step 8) Add user privileges to egoweb database

In the PHPMyAdmin browser window, click on "privileges" in the navigation menu, then click on the "Add User" link. The default username is "egowebuser" and the default password is "egowebpass." For production servers, please replace egowebpass with a password of your choice. if you change this value you will need to change the corresponding value in the "main.php" config file. Select "Local" for the host field. Click on "Go" at the bottom of the page.

Step 9) Install the Egoweb PHP files into the WAMP www directory.

  • Open the folder "C:\wamp\www" and delete all of the existing files inside the folder.
    • You can either directly open it up using Windows Explorer by pointing it to "C:\wamp\www" or you can open this window using WAMP menu by selecting "www directory".
  • After deleting these files, locate the the egoweb files that you extracted from the github .zip file you downloaded.
  • Locate the folder "app" among the extracted files on the desktop and copy its contents into "C:\wamp\www". Do not copy the folder itself, copy the files within the folder.
  • There should now be a new "index.php" file in the folder "C:\wamp\www".

Step 10) Configure egoweb

  • In the folder "C\wamp\www", create a new folder called "assets".
  • In the folder “C:\wamp\www\protected", create a new folder named "runtime".
  • In the folder “C:\wamp\www\protected\config", rename the file "main.php.example" to "main.php".
  • If you changed the default database password in step 8, you will need to edit this file and change the corresponding values under the "db" section.

Step 11) Start Egoweb

Open a browser and go to "http://localhost" to start using Egoweb. You will be prompted to create an admin user. After creating the user, you can log in to Egoweb with the user’s email and password. Enjoy!

NOTE: The initial installation was conducted with an administrator account. A non-admin account could not run wampserver. We attempted to set up wampserver to automatically load at startup without administrative rights but have not figured that out yet. We will update the documentation when we identify reliable procedures.


Updating Windows machines


1. Repeat steps from the main installation instructions starting with 9 (copy files from the .zip file webapp folder into the www folder).

2. Type the following into a browser address and hit enter:

localhost/admin/migrate

If there are data base changes, these will be migrated into the existing data base and EgoWeb will be fully updated. If there are no changes that need to be migrated, running this will confirm that your system is up to date.



Mac OS machine

Mac OS

Download the latest zip file from this repo and extract its contents onto the Desktop. There is a "Master" branch as well as a "dev" branch. Dev has more updated code but testing is in progress.

Step 1) Install MAMP

  • Go to http://www.mamp.info/en/ and download the appropriate version.
  • For this example, I installed version 3.1. We can't guarantee that there won't be problems with later versions, so it is a good idea to use this version.
  • For this set up, I use the default root password for MySQL "root"

Step 2) Configure MAMP

  • Start MAMP app from Applications. At the top menu click on "MAMP" then "Preferences" and then click the "Ports" tab.
  • Select "Set Web & MySQL Ports to 80 and 3306". Click "OK" to save.
  • Click on the icon above "Start Servers". The icon will turn "green" and the text will change to "Stop Servers", meaning that WAMP is running. (This is basically your on/off button for WAMP.)
  • You should be taken to the MAMP WebStart page. You may be asked to provide your admin password depending on your settings. If the WAMP WebStart page does not open automatically in a web browser, you can open it manually by clicking on the "Open WebStart page" icon in the middle of the MAMP application.

Step 3) Create default egoweb database.

  • On the MAMP Webstart page, at the top menu, click "Tools" and then "phpMyAdmin".
  • In the PHPMyAdmin browser window, click on "Databases". Under "Create database", put in "egoweb" for the database name (all lowercase) and select "utf8_general_ci" for the collation (recommended for fast performance).
  • Click create. A new database named "egoweb" should appear in the left sidebar.

Step 4) Import database structure from SQL file

  • In the phpMyAdmin browser window, click on the new database "egoweb" that you just created on the left hand side of the page. When the egoweb database structure appears in the middle of the page, select "Import" from the top navigation bar.
  • Under "File to Import:" you will browse your computer to find a file to import. Click on the "Choose File" button in the section under "File to import". Navigate to the egoweb folder you extracted from the .zip file downloaded from github. Find the "sql" folder, open it, you will see "egoweb_db.sql". Select this file and click OK.
  • After the file is selected (you will see "egoweb_db.sql" next to the "Choose File" button), click on "Go" at the bottom of the page. The EgoWeb database will now be populated with all of the tables needed to run EgoWeb on your Mac.

Step 5) Add user privileges to egoweb database

  • At the top menu of the phpMyAdmin page, click on the "Privileges" menu option. Click on the "Add User" link. The default username is "egowebuser" and the default password is "egowebpass."
  • NOTE: If setting up a production server that is not broadcasting / facing externally (if you are not just using your Mac to run EgoWeb -- e.g. if you are running it over a network and others will have access to the installation on a server) please replace egowebpass with a password of your choice. If you change this value you will need to change the corresponding value in the "main.php" config file.
  • Select "Local" for the host field.
  • Click on "Go" at the bottom of the page.

Step 6) Turn on Show Hidden Files for Finder

This step is necessary to copy the hidden file .htaccess, which is necessary for Apache to set the configurations for EgoWeb.

  • Open up a terminal by going into the the Application Launcher and typing in "Terminal". If you're running OS X Mavericks or Yosemite run the following command (you can copy and paste the text into a terminal session and hit "enter":


defaults write com.apple.finder AppleShowAllFiles -boolean true ; killall Finder


  • If you're running OS X 10.8 or below, run the following command instead:


defaults write com.apple.finder AppleShowAllFiles TRUE ; killall Finder


7) Install the Egoweb PHP files into the MAMP htdocs directory.

Go to the folder "/Applications/MAMP/htdocs". It is located in the same folder where your MAMP.app file is located.

Screenshot 2017-01-15 13.26.19.png
This is the MAMP folder with the "htdocs" folder and the MAMP.app application file.


  • You can also open it from the WAMP program menu by clicking on "Preferences" , then clicking on the "Web Server" tab.
    • You will see the path to your "htdocs" folder in the middle of the page.
    • Click the arrow next to the folder icon next to "Document Root:". This will open the "htdocs" folder.

  • Open the folder created when you extracted the egoweb .zip file from github in another Finder Window. Open the folder "app" within that folder.
  • Copy all of the contents of the "app" folder (not the folder itself) into the "htdocs" folder.
  • There should now be a file named "index.php" in the folder "/Applications/MAMP/htdocs".

8) Configure egoweb
  • In the folder htdocs ("/Applications/MAMP/htdocs/"), create a new folder called "assets".
  • Open the folder "protected" within "htdocs" (“/Applications/MAMP/htdocs/protected/"). Create a new folder named "runtime".
  • In the folder "config" within the "protected" folder (“/Applications/MAMP/htdocs/protected/config/"), rename the file "main.php.example" to "main.php". You will be asked if you really want to change the extension in a dialog box. Confirm that you do want to change from .example to .php.
  • NOTE:If you changed the default database password (in step 5 above), you will need to edit "main.php" and change the corresponding values under the "db" section.

9) Start Egoweb

Open a browser and go to "http://localhost" to start using Egoweb. You will be prompted to create an admin user. After creating the user, you can log in to Egoweb with the user’s email and password.

Updating Mac OS Machines

1. Repeat steps from the main installation instructions starting with 7 (copy files from the .zip file app folder into the htdocs folder).

2. Type the following into a browser address and hit enter:

localhost/admin/migrate

If there are data base changes, these will be migrated into the existing data base and EgoWeb will be fully updated. If there are no changes that need to be migrated, running this will confirm that your system is up to date.

Installing Linux

On an Existing Linux Server


These are instructions for a machine running Ubuntu 14.10 with the latest Ubuntu / Debian repositories. Open up a terminal on your server and execute the commands listed below.
Step 1) Install LAMP Server
  • sudo apt-get update

  • sudo apt-get install lamp-server^ git

When prompted whether or not to install, hit 'y' and press enter. Remember the root password you enter when installing the mysql server. You will need this password later.

Step 2) Configure Apache
  • sudo nano /etc/apache2/apache2.conf

Under <Directory /var/www/>, change AllowOverride None to AllowOverride All Ctrl + X and type Y to save.

Step 3) Enable the Apache rewrite and PHP Mcrypt modules
  • a2enmod rewrite

  • php5enmod mcrypt

  • service apache2 restart

Step 4) Install the Egoweb PHP files into the Apache www directory.
Step 5) Configure MySQL Database
  • mysql -p

  • CREATE DATABASE egoweb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;

  • USE egoweb

  • SOURCE ~/egoweb/sql/egoweb_db.sql

For production servers, please replace egowebpass in the command below with a password of your choice. If Egoweb is the only database you're setting up in MySQL, you may re-use the root password from Step 1. Otherwise, please use a different password.
  • CREATE USER 'egowebuser'@'localhost' IDENTIFIED BY 'egowebpass';

  • GRANT ALL PRIVILEGES ON egoweb.* TO 'egowebuser'@'localhost';

  • quit

Step 6) Configure Yii by running initialize.sh
  • cd /var/www/html

  • ./initialize.sh

For production servers, you will need to edit /var/www/html/protected/config/main.php. Replace egowebpass in the database connection string with the password you used in Step 4. For additional security, you may change the encryption key near the bottom of the configuration file.

Step 7) Start Egoweb

Open a browser and go to "http://localhost" (Or replace localhost with your IP) to start using Egoweb. You will be prompted to create an admin user with a name, email (which will be used as a username for logging in), and password. Please note that this is different from the database username and password which allows Egoweb to connect to the MySQL database. You may want to use a different password than the one used in Step 4. After creating the user, you can log in to Egoweb with the user’s email and password.

Updating a Linux Server


This set of instructions assumes you followed the Linux setup instructions on this wiki to install Egoweb initially, and that there is a copy of egoweb in the ~/ folder.

After logging in, type these following commands:

cd egoweb
git pull
cd ..
rm -rf /var/www/*
cp -r egoweb/app/. /var/www/html/
cd /var/www/html
./initialize.sh

After these commands are successfully run, open a browser and log in to the version of EgoWeb just updated. Go to the following url extension of the egoweb url that is being updated:

~/admin/migrate

If there are data base changes, these will be migrated into the existing data base and EgoWeb will be fully updated.

Updating a Linux Server to Another EgoWeb branch


Run this set of commands if you want to switch your webpage to a different egoweb branch. The the final 5 lines are the same as the final 5 lines above.

cd -
cd egoweb
git checkout {branch name}
git pull
cd ..
rm -rf /var/www/*
cp -r egoweb/app/. /var/www/html/
cd /var/www/html
./initialize.sh

And then run the same migrate command to update the data base if necessary:

~/admin/migrate


Creating a new Linux server with www.linode.com


The script below is available in the www.linode.com stack script library. This StackScript installs EgoWeb and all software required to run EgoWeb on linode. Most of the code should work on other systems. The Current Distribution is set to Ubuntu 14.04 LTS.

#!/bin/bash

set -e

# <UDF name="db_password" Label="MySQL root Password" />

DB_NAME="egoweb"

DB_USER="egowebuser"

DB_USER_PASSWORD="egowebpass"

echo "db_name is $DB_NAME"

echo "db_user is $DB_USER"

echo "db_user_password is $DB_USER_PASSWORD"

source <ssinclude StackScriptID="1">

system_update

postfix_install_loopback_only

mysql_install "$DB_PASSWORD" && mysql_tune 40

mysql_create_database "$DB_PASSWORD" "$DB_NAME"

mysql_create_user "$DB_PASSWORD" "$DB_USER" "$DB_USER_PASSWORD"

mysql_grant_user "$DB_PASSWORD" "$DB_USER" "$DB_NAME"

php_install_with_apache && php_tune

apache_install && apache_tune 40

goodstuff

a2enmod rewrite

sudo apt-get install -y php5-mcrypt

sudo php5enmod mcrypt

sudo apt-get install -y git

echo 'CLONING EGOWEB FROM GIT'

git clone https://github.com/qualintitative/egoweb

echo 'REMOVING DEFAULT WEB FILES'

sudo rm -rf /var/www/*

echo 'ADDING EGOWEB FILES TO WEB DIRECTORY'

sudo cp -r egoweb/app/. /var/www/html/

echo 'SETTING UP TABLES IN MYSQL FOR EGOWEB - USE SQL FILE AS SOURCE'

echo "SOURCE /egoweb/sql/egoweb_db.sql" | mysql egoweb -u root -p$DB_PASSWORD

ELINENOF=$(grep -n '/var/www/' /etc/apache2/apache2.conf |cut -f1 -d:)

echo "lineno is $ELINENOF"

ELINENO=$(($ELINENOF + 2))

echo "lineno is $ELINENO"

echo "$ELINENO s/None/All/"

sed -i -e "$ELINENO s/None/All/" /etc/apache2/apache2.conf

restartServices

cd /var/www/html

./initialize.sh



Miscellaneous Information


Reset admin password


If attempts to login with any administrative passwords fail, access can be regained to an EgoWeb installation by deleting all entries in the "user" table. If this table is blank when a user attempts to open an EgoWeb instance, the user is immediately prompted to create an administrative account name and password. Deleting entries in the "user" table can be done using mysql for Linux installations, WAMP for Windows installations, and MAMP for Mac installations.

After re-entry into EgoWeb, any users that were deleted would have to be re-created using the new administrator account.


re-initiate admin 3.png
Launch the WAMP Server application from the Windows tray.


re-initiate admin 4.png
Select the WAMP Amin application.


re-initiate admin 5.png
Within WAMP Admin, select SQL


re-initiate admin 2.png
Select the "user" table from SQL.


re-initiate admin 1.png
Delete all users in "user" table. This triggers the request for a new admin password after launching EgoWeb (launching "localhost" in a browser).

A current link can be found through a search on Visual C++ Redistributable for Visual Studio 2012 Update 4"

Page not loading properly


If EgoWeb code has changed, browsers may still load old versions of pages because they are storing page data in the cache. Somtimes there is a mixture of old and new page code, which can cause the page to appear broken in different ways.

To remedy this problem, do a hard browswer refresh, which clears the browser’s cache for that page and forces the browser to load the current page code. Browsers hang onto old code so that they do not have to load everything each time you visit the same page, but it sometimes hangs onto too much.

Doing a hard refresh depends on the browser and the operating system. For Windows and Chrome, hold down the “ctrl” key and click the browser refresh (or F5) and this should make the menu bar load properly. For Mac, do the same but instead of "ctrl" hold down "shift".

See this page for other options.

Return to the EgoWeb 2.0 Wikispaces Home