Difference between revisions of "Basic Installation"

Revision as of 19:49, 26 February 2014

If you are comfortable setting up an Apache web server 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.

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

Install Dependencies

LINUX

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

Apache

Most Linux distros include an Apache web server. 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

ARK 1.1 requires PHP 5.4. PHP 5.5+ may not run ARK or may produce "deprecated" errors as some functions have been deprecated. 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.

MySQL

MySQL is included in many Linux distros, 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.

MAC OR WINDOWS

There are several ways to install 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.

If you would prefer a simple installer, please consider using either WAMP or MAMP to install a complete stack on your system.

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

Unpack ARK

Unpack the ARK source code into the desired location in your 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 should then rename the ark package's folder to your desired name. Make a note of the folder name because you will need to update the environment 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

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. ARK only requires one user on the database, individual users on the website are managed by ARK.

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.

Using phpMyAdmin

Once you have your server Apache and MySQL servers running, phpMyAdmin is a very convenient tool for administering databases. If you install this tool then you can use it to set up your ARK database.

Use the phpMyAdmin interface to create a new database on your server. 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. ARK only requires one user on the database, this is the user that the php code will use to access the MySQL database. Individual (human) users on the website are managed by the ARK system.

Import the arkv1_1.sql file from the ARK source code into your database using the import tab on phpmyadmin.

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

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 can update the name of your ARK, this value will be used as 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

Next edit your env_settings.php file.

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.

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 ARK directory

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

You will now need to create a new user for yourself, add markup for your ARK name 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.

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.

Remove the Jane Doe default user. This is to prevent unauthorised access to your ARK via this account

If you plan on using your ARK on an unsecured network (such as the Internet) you should consider how you intend to encrypt traffic between the users and the server. You should consider how you will be securing passwords and login credentials against various kind of attacks. Such security measures are important but are outside the scope of this install document.