Installation Rough Guide

From CollectiveAccess Documentation
Jump to: navigation, search

This is a rough guide to installing Providence & Pawtucket on the same server based on OpenSuse 11.1 OS. This step by step guide is intended to be a learning tool not to be used for a production installation because of several shortcuts which leave obvious security holes such as disabling the firewall.

These instructions are intended to setup a system in an easy fashion so it may be assessed and tested as a platform. A secure setup guide may follow in the future.

The hardware used in my testing is an HP d530 workstation, and also an HP dc5100 workstation. In both cases the drivers necessary for the server to function were automatically installed during OS installation. Some drivers, for example the sound driver, did not load but were not needed. Any PC workstation with a P4 CPU and more than 512Mb would probably be suitable to build this system on, but may not be fit for use in production as a live server depending on the traffic load.

Initially OpenSuse 11.4 was used, but there were issues with screen flicker on both the local display and the remote desktop display. So, to avoid these issues, OpenSuse 11.1 was used and it worked without flickering.

The installation of Webmin was done to make administration of the MySQL system easier as well as to simplify other system tasks and to allow remote access by web browser. VNC remote desktop is included in the OpenSuse 11.1 allowing more complete remote access along with SSH terminal access. Once configured these tools allow the server to be managed remotely and so no local display, keyboard and mouse are neccessary (except during the initial stages of setup).

The skill level needed to complete this installation requires some basic knowledge such as how to burn an ISO file to DVD, using command line interfaces and moving files.

July 2011

Initial Downloads

From any PC with a DVD burner and internet: Download OpenSuse 11.1 installation DVD [ISO http://download.opensuse.org/distribution/11.1/iso/openSUSE-11.1-DVD-i586.iso] which is about 4Gb and may take several hours depending on your internet connection. Burn to DVD using a program like MagicISO.

Also, to erase and prepare the hard drive, you may wish to download HirenBoot 10.2 CD [ISO http://www.hirensbootcd.org/hbcd-v102/] or use your own partitioning software such as Acronis or Partition Magic.

Once the OpenSuse 11.1 DVD and Hiren Boot CD are created we are ready to clear the partitions on the hard drive and install OpenSuse 11.1

Prepare Hard Drive

Boot your target PC using Hiren Boot CD or other partition manager CD.

  • Warning: All data will be lost on the hard drive, so be sure to backup any existing files before clearing the partitions.

Use a program such as Acronis Disk Manager to clear all partitions on the Hard Drive.

Install OpenSuse 11.1

Boot your PC to the OpenSuse 11.1 DVD created in previous step.

Choose new installation.

Select language & keyboard preferences, click Next

Select New Install, click Next

Select Region and Time Zone, click Next

Select Gnome desktop (KDE is fine but Gnome will be supported in this guide), click Next

Select the default partitioning (Partition based), click Next

Enter a user name/password, un-check autologin, check use same password for admin, click Next

Software selections: Keep all defaults, also check Web & LAMP server, click Next

The install process now begins, it may take 15-30 minutes depending on your PC.

The install process should reboot when complete.

OpenSuse settings

Congratulations! you have installed the OS!

Once install is finished and rebooted, a login screen should be presented to you.

Choose 'other' and login as root using the password you entered in step 3.

Click 'Computer' in bottom left of the desktop

Run Yast [1] (found under System to the right)

In Yast find System Services(Runlevel) and click to start it.

Change to Expert Mode (radio button)

Highlight SuSEfirewall2_init (top of list), click on Set/Reset button and pick Disable.

This should cause SuSEfirewall2_setup to also become disabled (verify)

Highlight Apache2 service in list, click Set/Reset button and pick Enable the Service.

Highlight MySQL service, click Set/Reset button and pick Enable the Service.

Check that sshd service is Enabled, it allows remote terminal like PuTTy to work.

Click OK, to apply changes.

If any of these are missing in the list it may be becasue they were not chosen during installation.

Reboot the system (click Computer in bottom left desktop, shutdown, restart)

Remote Access settings

From the login screen, choose 'other' and login as root.

Click 'Computer' in bottom left of the desktop

Run Yast (found under System to the right)

In Yast under Network Services, find Remote Administration(VNC) and click to start it.

Choose 'Start service' and click OK.

Click 'Computer' in bottom left of the desktop

Drag Firefox icon to desktop if you wish, and run Firefox.

In the top address bar type: localhost and hit enter

You should see 'It Works!' which indicates Apache webservice is running.

Now, try to go to http://localhost:5801/ which should open a remote desktop.

You may have to click yes/ok to a cache setup message.

A remote desktop login should appear. If it stays on the grey snow, you may need to update [Java http://java.com/en/download/installed.jsp?jre_version=1.6.0_0&vendor=Sun+Microsystems+Inc.&os=Linux&os_version=2.6.27.7-9-pae]

Save to desktop then open with 'Execute jar' to install new java.


  • Note, if this remote desktop is not working, try rebooting. Otherwise it is not critical to this installation, but is convenient to have running.

Next, install Webmin (web based remote admin tool). Download it here [2]

When prompted, Open with Install Software (default). This will install and enable Webmin, check if it works [3]

  • Note, most software can be installed using the RPM version from the download site.

Terminal Access

GNOME Terminal is a command line interface to your server, find it by opening 'computer' at bottom left of desktop.

Then click More Applications, scroll down to System section and drag the GNOME Terminal icon to the desktop. This will make it easier to access in the future.

Start GNOME Terminal and type the command 'ifconfig'

Under Eth0, inet addr: you will find the IP address of your server (assigned by DHCP).

On a typical home LAN this will be in the form of 192.168.x.x, make a note of it.

Now, from any other PC on your LAN try to ping that address. If it responds to a ping then you will be able to view the web pages and use the web based Webmin & remote desktop tools as well as command line access using PuTTY.

(in Windows open a Dos window and type PING 192.168.x.x where x.x matches the inet addr found from your GNOME terminal comand earlier in this step.

Download PuTTy [4] to your Windows PC or any other SSH terminal. You should be able to login to the Collective Access server PC using the inet addr above.

Also, from any other PC on your LAN you can open a web page for webadmin at http://192.168.x.x:10000 (as above but replace localhost with <IP address>.

http://192.168.x.x:5801 will open remote desktop.

These tools are very useful in managing your CA server PC from any other PC on your LAN.

In a later step the network settings of the CA server PC will be set to a static IP address on your LAN, but for now the DHCP assigned address is fine.

Download Providence & Pawtucket

Download both Providence and Pawtucket from [collectiveaccess.org http://collectiveaccess.org/download] to the desktop of the CA server PC.

When download is complete, right click each one (.zip format) and choose expand here. This creates a new folder for each on the desktop.

Using the file browser (called roots - Home) to browse to File System, srv, www, htdocs and leave this window open to receive the files by dragging and dropping from the collectiveaccess-providence-1.0 folder on the desktop.

Click the desktop folder called collectiveaccess-providence-1.0 to open it. Select all the folders and files and drag and drop them into /srv/www/htdocs/ folder. Delete index.html (default apache page) so the new file index.php will become active.

Now that you have placed the Providence files into the webserver folder, the Pawtucket files are next.

First, create a new folder in /srv/www/htdocs/ called pawtucket, and using the file browser open that folder and leave this window open to receive files.

Now, on the desktop click into the folder collectiveaccess-pawtucket-1.0.1 and select all the files & folders and move them into the /srv/www/htdocs/pawtucket folder.

So we have placed the Providence files into the webserver folder /srv/www/htdocs The Pawtucket files have been put in a subfolder /srv/www/htdocs/pawtucket

Configuring MySQL

We will use Webmin to setup a database and change the MySQL root password (this is another root account within MySQL, not the same as the system root account).

Open a Webmin session, this can be done locally on the CA server PC by putting the following web address into [Firefox http://localhost:10000] or from any PC on your LAN from a browser using the IP address of the CA server PC such as [webmin http://192.168.1.101:10000]

Login using system root account.

In the right hand column of the Webmin page, click Servers, then MySQL Database Server.If MySQL is running (we enanbled the service earlier) you should see a section called MySQL Databases and another section below called Global Options.

In the top section, MySQL Databases, click on Create a new database.

Fill in the name of the new database (I suggest calling it cabase) and leave all other options as default then click Create.

Next, in Global Options section click on Change Administration Password and enter a password for MySQL root account. Make a note of this password, you need to enter it into the setup.php file for Providence in the next step. It is referenced as put-your-password-here.

Configure Providence setup.php

In the folder /srv/www/htdocs you should be able to see a file called setup.php-dist.

Open this with gedit (default text editor) and make the following changes:

At about 20 lines into the file you will find

define("__CA_BASE_DIR__", "/PATH/TO/COLLECTIVEACCESS");

Change that to: define("__CA_BASE_DIR__", "/srv/www/htdocs");


Next, scroll down to the line:

define("__CA_DB_USER__", 'my_database_user');

Change that to: define("__CA_DB_USER__", 'root');


Next, scroll down to the line:

define("__CA_DB_PASSWORD__", 'my_database_password');

Change that to: define("__CA_DB_PASSWORD__", 'put-your-password-here');

Where put-your-password-here is the MySQL admin password you noted earlier.


Next, scroll down to the line:

define("__CA_DB_DATABASE__", 'name_of_my_database');

Change that to: define("__CA_DB_DATABASE__", 'cabase');

Where cabase is the new database we created in the MySQL configuration.


Finally, save this file with a new name of setup.php into the /srv/www/htdocs folder.

Open a web browser on the CA server PC and go to http://localhost/

You may need to click on the refresh button (CTRL-R) if all is well you will see a Collective

Access box telling you an error has been detected.

If not, you may see a message telling you there is an error in setup.php, usually it indicates the line and describes the fault. Check for any mis-typed info in the setup.php file.

If you see the It Works! message, then delete index.html from the /srv/www/htdocs folder.


Otherwise, to continue the installation, click install to run the installer.

You will see 5 error messages, we will fix each one at a time.

ERROR: PHP mbstring module is required for CollectiveAccess to run. Please install it.
ERROR: PHP zlib module is required for CollectiveAccess to run. Please install it.
ERROR: The CollectiveAccess app/tmp directory is NOT writeable by the installer. This may result in installation errors. It is recommended that you change permissions on this directory (/srv/www/htdocs/app/tmp) to allow write access prior to installation. You can reload the installer to verify that the changed permissions are correct.
ERROR: The CollectiveAccess media directory is NOT writeable by the installer. This will prevent proper creation of the media directory structure and result in installation errors. It is recommended that you change permissions on this directory (/srv/www/htdocs) to allow write access prior to installation. You can reload the installer to verify that the changed permissions are correct.
ERROR: It looks like the directory for temporary files is not writable by the webserver. Please change the permissions of /srv/www/htdocs/app/tmp and enable the user which runs the webserver to write this directory. 

These last three errors are just file permissions which can be fixed with a chmod command in a terminal session. So open GNOME Terminal by clicking the Computer icon in the bottom left of the desktop and clicking more applications and finding GNOME Terminal in the list.

Once the terminal session is open type the following commands:

cd /srv/www

chmod 777 htdocs

cd htdocs

chmod 777 app

cd app

chmod 777 tmp


This will clear the errors, except for the module errors.

Go to the browser and open http://localhost/ and check there are only the 2 module errors remaining.

To fix these missing module (mbstring & zlib) errors click Computer icon in the bottom left of the desktop and in the right column under System click Add Software.

This opens the Yast Software Manager.

Either scroll down to php5-zlib in the list or type zlib in the search box, then highlight the module and click Install (lower right corner).

Click Apply, and Agree to the licenses (more than one appear due to dependant mudules being installed along with zlib).


Again, the same thing for mbstring module...

Click Computer icon in the bottom left of the desktop and in the right column under System click Add Software.

This opens the Yast Software Manager.

Either scroll down to php5-mbstring in the list or type mbstring in the search box, then highlight the module and click Install (lower right corner).

Click Apply, and Agree to the licenses (more than one appear due to dependant mudules being installed along with mbstring).

This will clear the module errors, after a reboot of the system.

So, restart the CA server PC, and then go to the browser and open http://localhost/ and this time the errors should be gone

If not, try a browser refresh (CTRL-R)

You should now see the Collective Access Version 1 Installer

Enter an email address.

Leave the DEFAULT collectinon type or selct another.

Click on the Begin Installation button.

Installation will take a few minutes while it builds the database tables etc.

Once it is finished you will be informed of your administration login password, write it down so you do not lose it.

Click login, User Name is Administrator, password is as you noted in previous step.


Congratulations - you have completed the installation of the Providence back end!

Configure Pawtucket setup.php

There is another setup.php-dist file needed in the /pawtucket folder of /srv/www/htdocs.

In the folder /srv/www/htdocs/pawtucket you should be able to see a file called setup.php-dist.

Open this with gedit (default text editor) and make the following changes:

At about 15 lines into the file you will find

define("__CA_BASE_DIR__", "/PATH/TO/WEBSERVER/ROOT");

Change that to: define("__CA_BASE_DIR__", "/srv/www/htdocs/pawtucket");


Next, scroll down to the line:

define("__CA_URL_ROOT__", "");

Change that to: define("__CA_URL_ROOT__", "/pawtucket");


Next, scroll down to the line:

define("__CA_DB_USER__", 'my_database_user');

Change that to: define("__CA_DB_USER__", 'root');


Next, scroll down to the line:

define("__CA_DB_PASSWORD__", 'my_database_password');

Change that to: define("__CA_DB_PASSWORD__", 'put-your-password-here');

Where put-your-password-here is the MySQL admin password you noted earlier.


Next, scroll down to the line:

define("__CA_DB_DATABASE__", 'name_of_my_database');

Change that to: define("__CA_DB_DATABASE__", 'cabase');

Where cabase is the new database we created in the MySQL configuration.


Now, save this file as setup.php into the /srv/www/htdocs/pawtucket folder.

If we open the pawtucket web [page http://localhost/pawtucket] we should see three errors, relating to file permissions.

ERROR: Could not write to /srv/www/htdocs/pawtucket. Check permissions.
ERROR: Could not write to /srv/www/htdocs/pawtucket/media. Check permissions.
ERROR: Could not write to /srv/www/htdocs/pawtucket/media/my_first_collectiveaccess_system. Check permissions.

These last three errors can be fixed with a chmod command in a terminal session. So open GNOME Terminal by clicking the Computer icon in the bottom left of the desktop and clicking more applications and finding GNOME Terminal in the list.

Once the terminal session is open type the following commands:

cd /srv/www/htdocs/pawtucket

chmod 777 app

cd app

chmod 777 tmp

cd /srv/www/htdocs/pawtucket

mkdir media

chmod 777 media

cd media

mkdir my_first_collectiveaccess_system

chmod 777 my_first_collectiveaccess_system


At last! We are ready to see the pawtucket front end page at: http://localhost/pawtucket

This should display the public web page which (Browse, Gallery, About)

Final Installation Notes

The back end server (Providence) is at http://localhost

The front end server (Pawtucket) is at http://localhost/pawtucket

If an new object is entered in Providence, it should display in Pawtucket.

Pictures and video require some additional configuration (loading Imagick, etc) which I hope to cover soon.

This installation is quick and dirty, but it should give a good idea of what is involved and a chance to test the look and feel of Collective Access. Some obvious security issues arise from using the root account to access MySQL and from chmod 777 to make permisssions (too open) so be aware this installation would probably be easy to hack if it was put into production as a live server.

If run from the CA server PC use http://localhost to access the web pages. From any other PC on your LAN you can also access the pages by substituting localhost with the IP address of the CA server PC. In a production server the IP address would be set to a static IP instead of a dynamic IP assigned by DHCP.

The remote admin tools can also be accessed from any PC on your LAN. If your CA server PC had a dynamic DHCP assigned address of 192.168.1.101 then:

Webmin is at http://192.168.1.101:10000

Remote Desktop is at http://192.168.1.101:5801

Terminal Session by PuTTY to the IP address of the server.

sphinx

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools