Difference between revisions of "Basic Installation"

From ARK
Jump to: navigation, search
(→‎For windows - ms4w)
 
(112 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
Preconfigured ARK setups are available from the ARK team. If you are unfamiliar with the setup and adminisration of webservers along with the security risks to your system and data this entails, please consider contacting us to aquire a fully running ARK. For those of you who have already got a server and want to go though the installation proceedure, we have provided the following notes:
+
If you are comfortable setting up an Apache webserver and a MySQL database, then setting up ARK is very easy. Follow the guide below to get your ARK instance installed and set up.
  
−
==Dependencies==
+
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 the ARK team to acquire a fully running ARK.
 +
 
 +
There are some further resources for learning about ARK and how to install it and some of the required dependencies [http://ark.lparchaeology.com/resources/ on the ARK website].
 +
 
 +
===Download source===
 +
 
 +
Download the latest source code from http://sourceforge.net/projects/arkdb/ sourceforge.
 +
 
 +
===Check and Install Dependencies===
 +
 
 +
====Dependencies====
  
 
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 and < 7.0
−
#MySQL 5
+
#MySQL
  
−
In order to benefit from the spatial integration offered by ARK, you will also need the following packages:
+
ARK is able to connect to any WMC/WFS compliant server of geographic information. Mapserver is no longer an ARK dependency. This means that that administrators 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.
  
−
#PHP Mapscript
+
ARK 1.1 requires PHP 5.4 or later. PHP 5.5 will run ARK but will produce "deprecated" errors as some functions used in ARK have been deprecated as of 5.5. If you are using PHP 5.5 and see deprecated messages, these can be hidden by following the relevant PHP documentation. These functions will be updated in a future release of ARK. ARK 1.X will not run on PHP 7.0 or later. ARK 2 is currently in development, which will run on PHP versions greater than 7.0.
  
−
===Apache PHP MySQL===
+
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.
  
−
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.
+
In addition the following packages are useful:
  
−
For Mac OSX and Windows, these packages are available as binary distributions. ARK is known to run on MAMP, the binary distribution for Mac and WAMP or MS4W, the binary distributions for Windows.
+
#phpMyAdmin
  
−
ARK runs on top of these packages and does not provide any set up of them or additional securuty 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 Apache and MySQL running, phpMyAdmin is a very convenient tool for administering databases. More information on how to use phpMyadmin can be found on their [http://docs.phpmyadmin.net/en/latest/user.html website].
  
−
===Mapscript===
+
====on LINUX====
  
−
Mapscript runs on all three major operating systems. The installation instructions vary depending on many factors. Detailed installation instructions are available on the Mapserver website.
+
On most Linux distributions these packages will be installed by default.
  
 +
=====Apache=====
  
 +
Most Linux distributions include an Apache webserver. 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:
  
−
==Installing ARK==
+
<code> sudo service httpd start </code>
  
−
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.
+
If you need to install Apache, instructions can be found on their [http://httpd.apache.org/docs/current/install.html website].
  
−
===Download source===
+
=====PHP=====
 +
 
 +
Most Linux distributions include PHP. Make sure that the version number of PHP installed on your system matches the requirements of ARK.
 +
 
 +
If you need to install PHP, instructions can be found on their [http://www.php.net/manual/en/install.php website].
 +
 
 +
=====MySQL=====
 +
 
 +
MySQL is included in many Linux distributions, but if you do not have it you may need to install <code>mysql-server</code> and <code>mysql</code>, instructions are available on the [http://dev.mysql.com/doc/refman/5.1/en/binary-installation.html MySQL website].
 +
 
 +
You will need to secure the installation, <code>sudo /usr/bin/mysql_secure_installation</code>.
 +
 
 +
====on OSX or WINDOWS====
 +
 
 +
There are several ways to manually install each of the required packages on OSX or Windows. These methods will work perfectly well with ARK and if you are comfortable installing and configuring the required packages, please go ahead and do so. For OSX the instructions will be similar to the Linux instructions.
 +
 
 +
If you would prefer a simple package-based installer, please consider using either WAMP/MAMP or if you are using Windows, MS4W also provides a good way to install a complete WAMP stack along with a Mapserver instance.
 +
 
 +
=====MAMP/WAMP=====
 +
 
 +
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 services.
 +
 
 +
=====MS4W=====
 +
 
 +
This package provides a standalone WAMP stack with a Mapserver instance. We have provided some walk through guidance [http://ark.lparchaeology.com/installing-mapserver-and-ms4w/ on the ARK website] for installing this package.
 +
 
 +
==Unpack ARK==
 +
 
 +
The ARK download consists of a folder of containing php code and several 'config' folders - the config folders contain the SQL code for that configuration. The first step is to copy the arkv1_1 folder into the desired location in your web server directory. Consult the documentation of your distribution if you are unsure where this is. It is likely to be something like <code>/var/www/</code> or <code>/srv/www/</code>. You will then need to either select one of the preconfigured configs and rename it to 'config' or create your own.
 +
 
 +
You can now rename the ARK package's folder to your desired name. If you do so, make a note of the folder name because you will need to update the settings to match it. This folder name will be used to navigate your ARK using your browser (in the URL), so call it something short, easy to remember and unique to your installation.
 +
 
 +
==Create Database and User==
 +
 
 +
You now need to create a new database, import the SQL into it and create a new user on your MySQL server.
 +
 
 +
The basic ARK database is included in the ARK package as an SQL file.
 +
 
 +
ARK only requires one user on the database, this is the user that the php code will use to access the MySQL database. Actual end users of your ARK will be created later using the tools provided by ARK.
 +
 
 +
The easiest way to accomplish these steps is to use phpMyAdmin, but you can also accomplish it using the command line mysql tools:
 +
 
 +
===Using phpMyAdmin===
 +
 
 +
Use the phpMyAdmin interface to create the new database. This is the database that will contain your ARK data, so make a note of the name so that you can update the settings files to match.
 +
 
 +
Now create a new user and grant them privileges on the new database.
 +
 
 +
Import the arkv1_1.sql file from the ARK source code into your database. Select the newly created database and then go to the Import tab and Browse to the .zip file that contains the SQL statement. This will copy all of the relevant tables to the database.
 +
 
 +
===Using the Command Line===
 +
 
 +
You can 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>
 +
 
 +
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.   
 +
 
 +
You will also need to create a database for your ARK to connect to.
 +
<code>CREATE DATABASE arkv1_1</code>
 +
 
 +
You are encouraged to change these default names see the [http://dev.mysql.com/doc/ mysql manual] for more information.
 +
 
 +
You should now load the ARK SQL into your database by using the <code>Source</code> command on the mysql terminal specifying the location of the arkv1_1.sql file.
 +
 
 +
===Use install_ark===
 +
With ARK1.2 there is a bash script which will follow the steps above. This is the quickest way to set up an ARK, but you may wish to change the username or password from the suggested defaults this script will use.
 +
 
 +
==Initial Setup==
 +
 
 +
===Config===
 +
 
 +
You will need to edit some of the configuration directives in the settings files located inside the <code>config</code> folder of your ARK installation.
 +
 
 +
====settings====
 +
 
 +
Start with the general <code>settings.php</code> file.
 +
 
 +
You must enter the path of the ark relative to the root of the server. You can also update the name of your ARK, and the markup nickname (nname) for a piece of markup containing the human readable name of your ARK. This allows you to customise the name of your ARK as it appears in page headers and titles. You will now need to add the markup to the ARK database.
 +
 
 +
You should also set your default site code in this file. Make a note of your site code(s) and be sure to add them to the ARK database using the form provided in the data entry page as soon as you log in. You will now need to add the site code to the ARK database.
 +
 
 +
====environment settings====
 +
 
 +
IIf you ahve created a database yourself, rather than using the install_ark script you will need to edit your <code>env_settings.php</code> file. This file should be self-explanatory, however there is an explanation of the relevant settings [http://ark.lparchaeology.com/wiki/index.php/Env_settings.php on this wiki page].
 +
 
 +
Change the <code>$server</code> directive on line 52 to match your server type, either mac, windows or linux.
 +
 
 +
Then in the correct code block of your server type, alter the paths to match the locations of the relevant directories in your ARK environment.
 +
 
 +
Make sure that the various path directives are correct. Be aware that you should update these to match your new ark folder name as set up earlier. For example:
 +
 
 +
<pre>
 +
// The folder name of THIS instance of ARK (relative to the domain)
 +
$ark_dir
 +
// The server path to the ark directory
 +
$ark_server_path
 +
// The path to the PEAR installation
 +
$pear_path
 +
</pre>
 +
 
 +
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 and user that you created earlier.
 +
 
 +
<b>You are now ready to connect to your ARK!</b>
 +
 
 +
===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 on your server at www.example.com/'your ark directory'/config/preflight_checks.php. Depending on your setup you may be able to access it at localhost. Check your server documentation for details.
 +
 
 +
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.
 +
 
 +
====File Uploads and phMagick====
 +
 
 +
It is highly likely that a standard ARK install will fail on some or all of the tests in this section of the pre-flight tests.
 +
 
 +
If you intend to upload files such as PDFs or images to your ARK and would like them to have thumbnails, then you will need to pass all of these tests. If not, then ignore this section of the tests.
 +
 
 +
For further information on how to install the required PHP extensions, imageMagick and phMagick, please consult the relevant online documentation.
 +
 
 +
===Browse to your ARK===
 +
 
 +
Point your browser to the newly created ARK directory, typically this would be <code>www.example.com/ark_dir/</code> or <code>localhost/ark_dir/</code> although the exact URL will vary according to both your hostname and your ARK directory settings.
 +
 
 +
After browsing to the ARK directory you should see the login pages for the new ARK system. The default ARK is created with the following admin user account:
 +
 
 +
<pre>
 +
username: doe_jd
 +
password: janedoe
 +
</pre>
 +
 
 +
Log in using these details and then finalise your configuration.
 +
 
 +
===Final Configuration===
 +
 
 +
If you successfully logged in as Jane Doe, pat yourself on the back and now mask sure you finish the last few steps:
 +
 
 +
You now need to [http://ark.lparchaeology.com/wiki/index.php/User_Administration create a new user] for yourself on ARK and make yourself and administrator. Once you have created this new administrator, you should logout and log back in again using you new username.
 +
 
 +
You <b>should</b> now remove the default doe_jd user to prevent unauthorised access to your system.
 +
 
 +
Now [http://ark.lparchaeology.com/wiki/index.php/Markup_Administration add markup] for the ARK name you specified in the settings file.
 +
 
 +
Now [http://ark.lparchaeology.com/wiki/index.php/site_code_administration add your default site code] as specified in the settings file.
 +
 
 +
==Debug==
  
−
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.
+
If you experience problems after following the steps above, there are a range of possible reasons that your local setup may not be correct. In order to display debug messages, go to your settings file and turn on debug by adjusting the settings from:
  
−
===Install a database===
+
<pre>
 +
error_reporting(0); // Turn off all error reporting - USE THIS FOR PRODUCTION SITES
 +
//error_reporting(E_ALL); // Report all PHP errors (see changelog) - USE THIS FOR SETUP AND TESTING
 +
</pre>
  
−
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 phpMyAdmin is a good way to do this.
+
to
  
−
#Download your chosen database dump file
+
<pre>
−
#Point your browser at the phpMyAdmin installation on your web-server
+
//error_reporting(0); // Turn off all error reporting - USE THIS FOR PRODUCTION SITES
−
#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.
+
error_reporting(E_ALL); // Report all PHP errors (see changelog) - USE THIS FOR SETUP AND TESTING
−
#Once the database is created, switch to it and choose Import
+
</pre>
−
#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 andDELETE privileges to the new db.
 
  
−
If you wish to use the slippy map functionality - you will need to undertake the same steps but this time downloading a copy of the 'clarent' db_schema.
+
==Cleanup==
  
 +
Once you have passed the pre-flight checks you should remove (delete or make inaccessible) this file so that it cannot be seen by unwanted users.
  
 
[[category:Administrator]]
 
[[category:Administrator]]

Latest revision as of 14:09, 19 March 2018

If you are comfortable setting up an Apache webserver and a MySQL database, then setting up ARK is very easy. Follow the guide below to get your ARK instance installed and set up.

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 the ARK team to acquire a fully running ARK.

There are some further resources for learning about ARK and how to install it and some of the required dependencies on the ARK website.

Download source

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

Check and Install Dependencies

Dependencies

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

  1. Apache
  2. PHP > 5.4 and < 7.0
  3. MySQL

ARK is able to connect to any WMC/WFS compliant server of geographic information. Mapserver is no longer an ARK dependency. This means that that administrators can connect to a geographic database of their choice, to suit their needs. Details on Mapserver setup can be found on their website.

ARK 1.1 requires PHP 5.4 or later. PHP 5.5 will run ARK but will produce "deprecated" errors as some functions used in ARK have been deprecated as of 5.5. If you are using PHP 5.5 and see deprecated messages, these can be hidden by following the relevant PHP documentation. These functions will be updated in a future release of ARK. ARK 1.X will not run on PHP 7.0 or later. ARK 2 is currently in development, which will run on PHP versions greater than 7.0.

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.

In addition the following packages are useful:

  1. phpMyAdmin

Once you have Apache and MySQL running, phpMyAdmin is a very convenient tool for administering databases. More information on how to use phpMyadmin can be found on their website.

on LINUX

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

Apache

Most Linux distributions include an Apache webserver. 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.

PHP

Most Linux distributions include PHP. Make sure that the version number of PHP installed on your system matches the requirements of ARK.

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

MySQL

MySQL is included in many Linux distributions, but if you do not have it you may need to install mysql-server and mysql, instructions are available on the MySQL website.

You will need to secure the installation, sudo /usr/bin/mysql_secure_installation.

on OSX or WINDOWS

There are several ways to manually install each of the required packages on OSX or Windows. These methods will work perfectly well with ARK and if you are comfortable installing and configuring the required packages, please go ahead and do so. For OSX the instructions will be similar to the Linux instructions.

If you would prefer a simple package-based installer, please consider using either WAMP/MAMP or if you are using Windows, MS4W also provides a good way to install a complete WAMP stack along with a Mapserver instance.

MAMP/WAMP

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 services.

MS4W

This package provides a standalone WAMP stack with a Mapserver instance. We have provided some walk through guidance on the ARK website for installing this package.

Unpack ARK

The ARK download consists of a folder of containing php code and several 'config' folders - the config folders contain the SQL code for that configuration. The first step is to copy the arkv1_1 folder into the desired location in your web server directory. Consult the documentation of your distribution if you are unsure where this is. It is likely to be something like /var/www/ or /srv/www/. You will then need to either select one of the preconfigured configs and rename it to 'config' or create your own.

You can now rename the ARK package's folder to your desired name. If you do so, make a note of the folder name because you will need to update the settings to match it. This folder name will be used to navigate your ARK using your browser (in the URL), so call it something short, easy to remember and unique to your installation.

Create Database and User

You now need to create a new database, import the SQL into it and create a new user on your MySQL server.

The basic ARK database is included in the ARK package as an SQL file.

ARK only requires one user on the database, this is the user that the php code will use to access the MySQL database. Actual end users of your ARK will be created later using the tools provided by ARK.

The easiest way to accomplish these steps is to use phpMyAdmin, but you can also accomplish it using the command line mysql tools:

Using phpMyAdmin

Use the phpMyAdmin interface to create the new database. This is the database that will contain your ARK data, so make a note of the name so that you can update the settings files to match.

Now create a new user and grant them privileges on the new database.

Import the arkv1_1.sql file from the ARK source code into your database. Select the newly created database and then go to the Import tab and Browse to the .zip file that contains the SQL statement. This will copy all of the relevant tables to the database.

Using the Command Line

You can 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.

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.

You should now load the ARK SQL into your database by using the Source command on the mysql terminal specifying the location of the arkv1_1.sql file.

Use install_ark

With ARK1.2 there is a bash script which will follow the steps above. This is the quickest way to set up an ARK, but you may wish to change the username or password from the suggested defaults this script will use.

Initial Setup

Config

You will need to edit some of the configuration directives in the settings files located inside the config folder of your ARK installation.

settings

Start with the general settings.php file.

You must enter the path of the ark relative to the root of the server. You can also update the name of your ARK, and the markup nickname (nname) for a piece of markup containing the human readable name of your ARK. This allows you to customise the name of your ARK as it appears in page headers and titles. You will now need to add the markup to the ARK database.

You should also set your default site code in this file. Make a note of your site code(s) and be sure to add them to the ARK database using the form provided in the data entry page as soon as you log in. You will now need to add the site code to the ARK database.

environment settings

IIf you ahve created a database yourself, rather than using the install_ark script you will need to edit your env_settings.php file. This file should be self-explanatory, however there is an explanation of the relevant settings on this wiki page.

Change the $server directive on line 52 to match your server type, either mac, windows or linux.

Then in the correct code block of your server type, alter the paths to match the locations of the relevant directories in your ARK environment.

Make sure that the various path directives are correct. Be aware that you should update these to match your new ark folder name as set up earlier. For example: 

// The folder name of THIS instance of ARK (relative to the domain)
$ark_dir
// The server path to the ark directory
$ark_server_path
// The path to the PEAR installation
$pear_path

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 and user that you created earlier.

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 on your server at www.example.com/'your ark directory'/config/preflight_checks.php. Depending on your setup you may be able to access it at localhost. Check your server documentation for details.

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.

File Uploads and phMagick

It is highly likely that a standard ARK install will fail on some or all of the tests in this section of the pre-flight tests.

If you intend to upload files such as PDFs or images to your ARK and would like them to have thumbnails, then you will need to pass all of these tests. If not, then ignore this section of the tests.

For further information on how to install the required PHP extensions, imageMagick and phMagick, please consult the relevant online documentation.

Browse to your ARK

Point your browser to the newly created ARK directory, typically this would be www.example.com/ark_dir/ or localhost/ark_dir/ although the exact URL will vary according to both your hostname and your ARK directory settings.

After browsing to the ARK directory you should see the login pages for the new ARK system. The default ARK is created with the following admin user account: 

username: doe_jd
password: janedoe

Log in using these details and then finalise your configuration.

Final Configuration

If you successfully logged in as Jane Doe, pat yourself on the back and now mask sure you finish the last few steps:

You now need to create a new user for yourself on ARK and make yourself and administrator. Once you have created this new administrator, you should logout and log back in again using you new username.

You should now remove the default doe_jd user to prevent unauthorised access to your system.

Now add markup for the ARK name you specified in the settings file.

Now add your default site code as specified in the settings file.

Debug

If you experience problems after following the steps above, there are a range of possible reasons that your local setup may not be correct. In order to display debug messages, go to your settings file and turn on debug by adjusting the settings from: 

error_reporting(0); // Turn off all error reporting - USE THIS FOR PRODUCTION SITES
//error_reporting(E_ALL); // Report all PHP errors (see changelog) - USE THIS FOR SETUP AND TESTING

to 

//error_reporting(0); // Turn off all error reporting - USE THIS FOR PRODUCTION SITES
error_reporting(E_ALL); // Report all PHP errors (see changelog) - USE THIS FOR SETUP AND TESTING

Cleanup

Once you have passed the pre-flight checks you should remove (delete or make inaccessible) this file so that it cannot be seen by unwanted users.

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