Difference between revisions of "Basic Installation"

From ARK
Jump to: navigation, search
(→‎How To's)
Line 1: Line 1:
 
Pre-configured ARK setups are available from the ARK team. If you are unfamiliar with the setup and administration of webservers along with the security risks to your system and data this entails, please consider contacting us to acquire a fully running ARK. For those of you who have already got a server and want to go though the installation procedure, we have provided the following notes:
 
Pre-configured ARK setups are available from the ARK team. If you are unfamiliar with the setup and administration of webservers along with the security risks to your system and data this entails, please consider contacting us to acquire a fully running ARK. For those of you who have already got a server and want to go though the installation procedure, we have provided the following notes:
  
−
===How To's===
+
==Installing ARK==
  
−
Detailed How-To documents have been written to take the new administrator through the installation and setup of MS4W, Mapserver, and ARK. They can be downloaded [http://ark.lparchaeology.com/download/windows-installation-walkthroughs-now-available].
+
Ark is installed by unpacking the source code into the document root of the webserver where you intend to host it. This process requires two steps, the [Initial Setup] and the [Configuration].
 +
 
 +
===Download source===
 +
 
 +
Download the latest source code from http://sourceforge.net/projects/arkdb/ sourceforge.
  
 
===Dependencies===
 
===Dependencies===
Line 9: Line 13:
 
ARK requires the following open source software packages to be installed on your server:
 
ARK requires the following open source software packages to be installed on your server:
  
−
#Apache 2
+
#Apache
−
#PHP 5
+
#PHP 5.4
−
#MySQL 5
+
#MySQL
−
#PEAR Liveuser
+
 
 +
ARK is able to connect to any WMC/WFS compliant server of geographic information. Mapserver is no longer bundled with ARK so that users can connect to a geographic database of their choice, to suit their needs. Details on [http://mapserver.org/ Mapserver] setup can be found on their website.
 +
 
 +
====Mapscript====
 +
 
 +
In order to benefit fully from the spatial integration offered by ARK, you will also need PHP Mapscript
 +
 
 +
Mapscript runs on all three major operating systems. The installation instructions vary depending on many factors. Detailed installation instructions are available on the [http://mapserver.org/mapscript/ Mapscript] website.
 +
 
 +
 
 +
==Initial Setup==
 +
 
 +
====LINUX====
  
−
In order to benefit from the spatial integration offered by ARK, you will also need the following packages:
+
=====Apache=====
  
−
#PHP Mapscript
+
Most Linux distros include a web service (like Apache) consult the documentation on your installation for instructions on how to configure your server. If your service path is configured, the service can be started with <code> sudo service httpd start </code>.
  
−
====Apache PHP MySQL====
+
If you need to install Apache, instructions can be found on their [http://httpd.apache.org/docs/current/install.html website].
  
−
On most Linux distributions these packages will be installed by default. ARK is not particularly fussy about the version numbers of these packages and should run ok on PHP4 and MySQL4, although this may require some minor modifications. It is important to ensure that you have the gd and dbase php extensions enabled.
+
On most Linux distributions these packages will be installed by default.
  
−
You will need to make sure that you set the short_open_tag option to On in your [http://uk2.php.net/ini.core php.ini].
+
Unpack the ARK source code into your server doc root. Consult the documentation of your distribution if you are unsure. It is likely to be either <code>/var/www/</code> or <code>/srv/www/</code>.
  
−
For Mac OSX and Windows, these packages are available as binary distributions. ARK is known to run on [http://www.mamp.info/en/index.php MAMP], the binary distribution for Mac and [http://www.wampserver.com/en/ WAMP] or [http://www.maptools.org/ms4w/index.phtml MS4W], the binary distributions for Windows.
+
=====PHP=====
  
−
The MS4W distribution also contains Mapserver and if this is installed only MySQL needs to be added.
+
ARK 1.1 requires PHP 5.4. PHP 5.5+ will not run ARK as some functions have been deprecated. This will be updated in future releases of ARK. It is important to ensure that you have the gd and dbase php extensions enabled.
  
−
ARK runs on top of these packages and does not provide any set up of them or additional security to them. If you are using your server exposed to the internet, it is essential that you follow good standard security practice for the configuration of your packages. This setup is outside of the scope of this documentation and you are advised to undertake your research carefully.
+
=====MySQL=====
  
−
====PEAR LiveUser====
+
MySQL is included in many Linux distros, but if you do not have it you may need to install mysql-server and mysql (we use yum) you will need to run the secure installation, <code>sudo /usr/bin/mysql_secure_installation</code>.
  
−
The PEAR Liveuser is used to ensure effective security for the ARK system. ARK makes use of PEAR LiveUser, LiveUser_Admin, MDB2, and MDB2_driver_mysql, DB, and Event_Dispatcher. All of these packages will need to be installed in order for ARK user authentication to function.
+
We use MySQL from the command line to add the 'arkuser' user to the MySQL installation for instance:
 +
  <code>CREATE USER arkuser'@'%' IDENTIFIED BY 'XXXXXX';
 +
  GRANT ALL PRIVILEGES ON *.* TO 'arkuser'@'%' WITH GRANT OPTION;</code>
  
−
'''PLEASE NOTE that ALL the PEAR SQL tables are already included with the basic ARK database, and do not need to be added to the database during PEAR setup. ALSO the required PEAR depencies are included with the v1.0 directory structure and in the environment settings, so no further installation or set-up of PEAR should be needed.'''
+
The values in this must be changed in order to secure your database. See the [http://dev.mysql.com/doc/ mysql manual] for more information.    
 +
ARK only requires one user on the database, individual users on the website are managed by PEAR, which is bundled in the ARK package.
  
−
====MS4W====
+
You will also need to create a database for your ARK to connect to.  
−
MS4W [http://www.maptools.org/ms4w/] is a no fuss installer for setting up MapServer on Microsoft Windows platforms. It includes a Apache HTTP version, PHP, Mapserver and loads of nice tools.
+
<code>CREATE DATABASE arkv1_1</code>
  
−
MS4W is super simple to install on a server. Either download [http://www.maptools.org/ms4w/index.phtml?page=downloads.html] the base package which consists of a folder which unpacks to the C-drive of the server or try out the new installer.  
+
You are encouraged to change these default names see the [http://dev.mysql.com/doc/ mysql manual] for more information.
  
−
If you are using the base package you need to start the Apache server by running C:\ms4w\apache-install.bat. If the installation is succesful you should get the main page by pointing you browser to http://localhost/ or http://127.0.0.1/.
+
The ARK database is included in the ARK package as an SQL file. You can load this into your database by using the <code>Source</code> command on the mysql terminal specifying the location of the arkv1_1.sql file.
  
−
If this does not work it is very likely that your port 80 is already in use. Go to C:\ms4w\Apache\conf\httpd.conf and on line 120 change LISTEN 80 to LISTEN 8080 or another port which is not in use.
+
====MAC OR WINDOWS====
  
−
====Mapscript====
+
For Mac OSX or Windows, the required packages are available as a bundle known as [http://www.mamp.info/en/index.php MAMP] for Mac or [http://www.wampserver.com/en/ WAMP] Windows. Their websites detail the installation procedures for these service.
  
−
Mapscript runs on all three major operating systems. The installation instructions vary depending on many factors. Detailed installation instructions are available on the [http://mapserver.gis.umn.edu/ Mapserver] website.
+
ARK runs on top of these packages and does not provide any set up of them or additional security to them. If you are using your server exposed to the internet, it is essential that you follow good standard security practice for the configuration of your packages. This setup is outside of the scope of this documentation and you are advised to undertake your research carefully.
  
−
===Installing ARK===
+
Once you have your server running you should be able to navigate to phpmyadmin, which is a very useful tool for administrating a database. You can access it at [localhost:8888/phpMyAdmin] by default.
  
−
Ark is installed by unpacking the source code into the document root of the webserver where you intend to host it. The second phase of installation is then the initial setup and creation of the empty database.
+
You can use this to create a database, an configure a user. ARK only requires one user on the database, individual users on the website are managed by PEAR, which is bundled in the ARK package. Import the arkv1_1.sql file from the ARK source code into your database using phpmyadmin.
  
−
====Download source====
+
More information on how to use phpmyadmin can be found on their [http://docs.phpmyadmin.net/en/latest/user.html website].
  
−
Download the latest source code from http://ark.lparchaeology.com/downloads and unpack it into the document root of your server. If you are unsure of the correct location of the document root, you could try reading the manual of your apache distribution.
+
==Configuration==
  
−
====Install a database====
+
===Config===
  
−
In order for ark to work, you need to install an ARK database on your MySQL server. Preconfigured sample databases are available for download from the download area of the ARK site. At present you must install the sql dump on the server manually using your tool of choice. We think that [http://www.phpmyadmin.net/home_page/index.php phpMyAdmin] is a good way to do this.
+
You will need to update the values in the config/ folder of your ARK installation to match the environment that you are working in.
  
−
#Download your chosen database dump file
+
====settings====
−
#Point your browser at the phpMyAdmin installation on your web-server
+
In <code>settings.php</code> you can update the name of your ARK, this value will be used for the presentation of your website. You will also need to create a markup nickname (nname) for your ARK. This will let you store and access a human readable name for your ARK on the database.
−
#Make an empty database, by going to the Databases screen and filling in the Create new database box. Make the Collation utf8_unicode_ci and that should deal with most character sets.
+
You should also set your default site code here, but you will need to add it to the ARK database once you are connected.  
−
#Once the database is created, switch to it and choose Import
 
−
#Using the Browse button, point it at the file that you have downloaded (it should be a tar.gz) - make the character set utf8
 
−
#Click Go and wait a little while, and the database structure should be loaded up fine.
 
−
#You will need to set up a user and give it at least SELECT, INSERT, UPDATE and DELETE privileges to the new db.
 
  
−
===Update the DB Settings===
+
====environment settings====
 +
In <code>env_settings.php</code> change the $server flag on line 52 to match your server type, either mac, windows or linux.
  
−
You will now need to update the server-specific DB settings in [[env_settings.php]] and [[settings.php]].  '''THE DATABASE WILL NOT WORK UNTIL THESE SETTINGS HAVE BEEN UPDATED'''.
+
Then in the correct code block, alter the paths to match the locations of the relevant directories in your ARK environment. Both local and remote paths for OpenLayers are offered, use // to comment out the line that you are not using.
  
−
===Setup Windows server for ARK===
+
Alter the database settings at the end of the file to match the database that you created in the setup stages.
  
−
This will take you through setting up a windows server from scratch to work for ARK.
+
<b>You are now ready to connect to your ARK!</b>
  
−
====Download and install====
+
===Preflight Checks===
−
*MS4W, newest release: http://www.maptools.org/ms4w/
 
−
** Download with installer
 
−
** Install without ad-on packages
 
−
** Install in C:\
 
−
** Install in port 80 unless it is already in use then use port 8080
 
−
** Go to http://127.0.0.1 or http://localhost to check that it is running.
 
−
** You can also go to Control Panel > Administrative Tools > Services and check that the Apache MS4W Web Server is started.
 
  
−
* MySQL
+
Point your browser to the preflight checks file included in ARK to test that you have configured ARK correctly. It should be available at localhost:8888/'your ark directory'/config/preflight_checks.php.
−
** Download MySQL community server: http://dev.mysql.com/downloads/
 
−
** Install a typical installation
 
−
** Configuration:
 
−
*** Server Machine
 
−
*** Transactional Database Only
 
−
*** Installation path C:
 
−
*** Online Transaction Processing
 
−
*** Enable TCP?IP Networking on port nr. 3306
 
−
*** Enable Strict Mode
 
−
*** Best Support for Multilingualism
 
−
*** Install as Windows Service
 
−
*** Include Bin Directory in Windows PATH
 
−
*** Set root password
 
−
** You can also go to Control Panel > Administrative Tools > Services and check that the MySQL is started.
 
  
−
* PEAR
+
This tool will list set up options with either PASS or FAIL. If your config FAILs please follow the instructions on the preflight checks page, or refer to other pages on the wiki for more details.
−
** Firstly make sure that there is a path to the folder containing php.exe in the environmental variables: Control Panel > System > Advanced > Environmental Variables > System Variables: Click Edit for the 'path' variable and add ; and the full path to the folder after the last path (in this case C:\ms4w\Apache\cgi-bin
 
−
** Restart the server after this.
 
−
** Now go to the command line and find the folder containing go-pear.bat (should be C:\ms4w\Apache\php) and type in go-pear.bat
 
−
** This will run the pear installation and if you can get this to work then congratulations. I give up here and move the old pear files over from another project.
 
  
 
===Browse to ARK directory===
 
===Browse to ARK directory===
  
−
After browsing to the ARK directory you should now be able to see the login pages for the database.  The tutorial database is created with the following admin user account:
+
After browsing to the ARK directory you should now be able to see the login pages for the database.  The default database is created with the following admin user account:
  
 
<pre>
 
<pre>
Line 117: Line 108:
  
 
</pre>
 
</pre>
 +
 +
You will now need to [http://ark.lparchaeology.com/wiki/index.php/User_Administration create a new user] for yourself, [http://ark.lparchaeology.com/wiki/index.php/Markup_Administration add your ARK name markup] and [http://ark.lparchaeology.com/wiki/index.php/site_code_administration add your default site code].
  
 
If there are any problems, please check your [[settings.php]] and [[env_settings.php]] files to ensure you are using the correct settings.
 
If there are any problems, please check your [[settings.php]] and [[env_settings.php]] files to ensure you are using the correct settings.
  
 
[[category:Administrator]]
 
[[category:Administrator]]

Revision as of 17:17, 26 February 2014

Pre-configured ARK setups are available from the ARK team. If you are unfamiliar with the setup and administration of webservers along with the security risks to your system and data this entails, please consider contacting us to acquire a fully running ARK. For those of you who have already got a server and want to go though the installation procedure, we have provided the following notes:

Installing ARK

Ark is installed by unpacking the source code into the document root of the webserver where you intend to host it. This process requires two steps, the [Initial Setup] and the [Configuration].

Download source

Download the latest source code from http://sourceforge.net/projects/arkdb/ sourceforge.

Dependencies

ARK requires the following open source software packages to be installed on your server:

  1. Apache
  2. PHP 5.4
  3. MySQL

ARK is able to connect to any WMC/WFS compliant server of geographic information. Mapserver is no longer bundled with ARK so that users can connect to a geographic database of their choice, to suit their needs. Details on Mapserver setup can be found on their website.

Mapscript

In order to benefit fully from the spatial integration offered by ARK, you will also need PHP Mapscript

Mapscript runs on all three major operating systems. The installation instructions vary depending on many factors. Detailed installation instructions are available on the Mapscript website.


Initial Setup

LINUX

Apache

Most Linux distros include a web service (like Apache) consult the documentation on your installation for instructions on how to configure your server. If your service path is configured, the service can be started with sudo service httpd start .

If you need to install Apache, instructions can be found on their website.

On most Linux distributions these packages will be installed by default.

Unpack the ARK source code into your server doc root. Consult the documentation of your distribution if you are unsure. It is likely to be either /var/www/ or /srv/www/.

PHP

ARK 1.1 requires PHP 5.4. PHP 5.5+ will not run ARK as some functions have been deprecated. This will be updated in future releases of ARK. It is important to ensure that you have the gd and dbase php extensions enabled.

MySQL

MySQL is included in many Linux distros, but if you do not have it you may need to install mysql-server and mysql (we use yum) you will need to run the secure installation, sudo /usr/bin/mysql_secure_installation.

We use MySQL from the command line to add the 'arkuser' user to the MySQL installation for instance: 

CREATE USER arkuser'@'%' IDENTIFIED BY 'XXXXXX';
GRANT ALL PRIVILEGES ON *.* TO 'arkuser'@'%' WITH GRANT OPTION;

The values in this must be changed in order to secure your database. See the mysql manual for more information. ARK only requires one user on the database, individual users on the website are managed by PEAR, which is bundled in the ARK package.

You will also need to create a database for your ARK to connect to. 

CREATE DATABASE arkv1_1

You are encouraged to change these default names see the mysql manual for more information.

The ARK database is included in the ARK package as an SQL file. You can load this into your database by using the Source command on the mysql terminal specifying the location of the arkv1_1.sql file.

MAC OR WINDOWS

For Mac OSX or Windows, the required packages are available as a bundle known as MAMP for Mac or WAMP Windows. Their websites detail the installation procedures for these service.

ARK runs on top of these packages and does not provide any set up of them or additional security to them. If you are using your server exposed to the internet, it is essential that you follow good standard security practice for the configuration of your packages. This setup is outside of the scope of this documentation and you are advised to undertake your research carefully.

Once you have your server running you should be able to navigate to phpmyadmin, which is a very useful tool for administrating a database. You can access it at [localhost:8888/phpMyAdmin] by default.

You can use this to create a database, an configure a user. ARK only requires one user on the database, individual users on the website are managed by PEAR, which is bundled in the ARK package. Import the arkv1_1.sql file from the ARK source code into your database using phpmyadmin.

More information on how to use phpmyadmin can be found on their website.

Configuration

Config

You will need to update the values in the config/ folder of your ARK installation to match the environment that you are working in.

settings

In settings.php you can update the name of your ARK, this value will be used for the presentation of your website. You will also need to create a markup nickname (nname) for your ARK. This will let you store and access a human readable name for your ARK on the database. You should also set your default site code here, but you will need to add it to the ARK database once you are connected.

environment settings

In env_settings.php change the $server flag on line 52 to match your server type, either mac, windows or linux.

Then in the correct code block, alter the paths to match the locations of the relevant directories in your ARK environment. Both local and remote paths for OpenLayers are offered, use // to comment out the line that you are not using.

Alter the database settings at the end of the file to match the database that you created in the setup stages.

You are now ready to connect to your ARK!

Preflight Checks

Point your browser to the preflight checks file included in ARK to test that you have configured ARK correctly. It should be available at localhost:8888/'your ark directory'/config/preflight_checks.php.

This tool will list set up options with either PASS or FAIL. If your config FAILs please follow the instructions on the preflight checks page, or refer to other pages on the wiki for more details.

Browse to ARK directory

After browsing to the ARK directory you should now be able to see the login pages for the database. The default database is created with the following admin user account: 

username: doe_jd
password: janedoe

You will now need to create a new user for yourself, add your ARK name markup and add your default site code.

If there are any problems, please check your settings.php and env_settings.php files to ensure you are using the correct settings.

Retrieved from "https://ark.lparchaeology.com/wiki/index.php?title=Basic_Installation&oldid=3197"