Arches: heritage inventory & management system - Installation Guide

Transcription

1

2 Arches: heritage inventory & management system - Installation Guide Installation Guide Arches Project This book is for sale at This version was published on This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. This work is licensed under a Creative Commons Attribution 3.0 Unported License

3 Contents Version i Acknowledgments ii Contributors: ii Cover image ii Cover design ii What is Arches? An overview iii Key features iii Application iii Further information iv Introduction What do I need to know to use this guide? Express Installation Guide Before You Start Option 1: Installing Arches on your own Computer Step 1: Download the Arches VM Step 2: Install VirtualBox Step 3: Import the Arches VM Step 4: Start the Virtual Machine Step 5: Log on to the VM Step 6: Start the Arches Server A note on Ubuntu Option 2: Installing Arches on the Amazon Cloud Step 1: Set up an Amazon Account Step 2: Use the Arches AMI Step 3: Select the Arches Server Size Step 4: Create Key Pair Step 5: Launch the Arches Server Step 6: Configure HTTP Access on your Server Step 7: Log on to Arches Deploying Arches Before you start System Requirements Arches and Cultural Heritage Standards

4 CONTENTS Step 1: Install Core Arches Installation Options Option 1: Install Arches on a Windows Server Step 1: Download Arches Step 2: Install PostgreSQL 9.x, PostGIS 2.x Step 3: Install Python Step 4: Install the latest Java Development Kit (JDK) Step 5: Install Web Framework Step 6: Install Arches Next Steps Option 2: Install Arches on a Linux Server Step 1: Download Arches Step 2: Install PostgreSQL/PostGIS Step 3: Install Web Framework Step 4: Install and Build Arches Next Steps Option 3: Install Arches on a Vagrant Virtual Machine Step 1: Download Arches Step 2: Install Vagrant Step 3: Install VirtualBox Step 4: Download Virtual Machine File Step 5: Build Arches Step 6: Start Arches A Note on Vagrant Step 2: Load Resource Type Definitions What are Resources? Arches Resource Type Categories Heritage Resources: Activities Documents Actors Creating Your Own Resource Types Loading Resources Step 1: Select Resources to Load Step 2: Load Resource Type Definitions Next Steps Step 3: Load Controlled Vocabularies What are Controlled Vocabularies? Thesauri Default Authority Documents Understanding the Structure of an Authority Document Understanding Authority Document Values What Value Types Can I Define? Modifying the Default Authority Files

5 CONTENTS Loading the Controlled Vocabularies Next Steps Step 4 (optional): Load Data into Arches Resources and Their Attributes Creating a Data Load File Adding Multiple Values to an Attribute Attribute Goups Which Attributes can be Grouped? Loading the Data File Next Steps Step 5: Running and Configuring Arches Running Arches Arches Configuration Managing User Accounts Updating the Default Administrator Password Adding a New Editor Account Setting Default Map Settings Managing Basemaps and External GIS Layers Adding a new Basemap/GIS Service to Arches Removing a GIS Map Service from Arches Cosmetic Settings Changing the Image on the Arches Splash Screen Changing the Style of a Resource Layer Using Arches Backup Your Arches Database Performance Tuning User Guide Feedback and Support

6 Version This version is issued to support Version 1.0 of Arches, released in October 2013.

7 Acknowledgments Contributors: Ryan Anderson, Farallon Geographics Yiannis Avramides, World Monuments Fund Kieran Byrne, English Heritage Phil Carlisle, English Heritage Alison Dalgity, Getty Conservation Institute Rob Gaston, Farallon Geographics Edmund Lee, English Heritage Adam Lodge, Farallon Geographics David Myers, Getty Conservation Institute Alexei Peters, Farallon Geographics Koen Van Daele, Flanders Heritage Agency Dennis Wuthrich, Farallon Geographics Cover image Extract from a technical survey of the 18th century arch of the Ironbridge, England, part of the Ironbridge World Heritage Site. Courtesy of Paul Bryan, English Heritage. Cover design Ken Feisel, World Monuments Fund

8 What is Arches? An overview Arches is a new open-source geospatial software system for cultural heritage inventory and management, developed jointly by the Getty Conservation Institute and World Monuments Fund. Arches grew out of the widespread need within the heritage field for the ability to create electronic inventories at low cost that are easy to use and access. Arches combines state-of-theart software development with insights and perspectives of heritage professionals from around the world. The need for functional heritage inventories has grown over the last decades, together with the rise of a global awareness of the importance of heritage management. Nevertheless, inventories remain complicated to establish and maintain, and frequently rely on costly proprietary software that does not always fit the needs of the heritage field. Arches provides a common platform that is easy to use and customize, and yet one that takes advantage of the latest available technology to allow users to create and manage heritage information in all its richness and diversity. Key features Purpose-built. Arches has been purpose-built for the international cultural heritage field, and can be used to inventory and document all types of immovable heritage, including buildings and other structures, cultural landscapes, heritage ensembles or districts, as well as archaeological sites. Open Source. As open source software, Arches is freely available to use and customize, without licensing costs, and it is capable of being configured and extended to meet the needs of particular users. Standards-based. Arches incorporates internationally adopted standards for heritage inventory, semantic modeling, and information technology, leading to better practices in the creation and management of heritage data and facilitating data exchange and longevity in spite of advances in technology. Application Arches has been designed to serve a number of purposes fundamental to the understanding, appreciation, and management of heritage places. These include: identification and inventory research and analysis monitoring and risk mapping determining needs and priorities for investigation, research, conservation and management

9 What is Arches? An overview iv planning for investigation, conservation, and management activities raising awareness and promoting understanding among the public, as well as governmental authorities and decision makers Further information Detailed background to the project, fact sheets, conference presentations, a project blog and active online community are all available at

10 Introduction Welcome to the Arches software installation guide. This document is intended to help you quickly get Arches running on your server. If you can t wait to get started, skip straight to the Deploying Arches chapter. Or, if you d simply like to evaluate Arches using an example dataset, jump straight to the Express Installation chapter. Otherwise, read on to learn more about how Arches manages cultural heritage data. Once you have installed Arches there is a companion book to this one, the Arches User Guide, with more information about how to use the software, and how to join the Arches community, a growing online network of Arches developers and users. What do I need to know to use this guide? Arches is designed to let you manage many types of cultural heritage data. And while we ve tried to make it easy to install Arches, you ll need to make some decisions on how you wish to describe and manage the information that goes into Arches. But don t worry, we ve also included lots of examples and well-thought-out defaults for setting up the software. So, installing Arches means loading software and deciding how you want to describe the cultural heritage information that s important to you. We ve written this guide assuming that you are comfortable working with your computer s command line, and that you can edit text files with ease. That s it! Feel free to tap a colleague on the shoulder if you need a little help along the way, or check out the resources at for more support.

11 Express Installation Guide The Express Installation Guide allows you to quickly install and use Arches with its default settings and an example dataset from northern England, courtesy of English Heritage. If your primary goal is to test Arches to determine whether it might be a good fit for your project or organization, then the Express Installation is for you. Before You Start You ll need to decide where you want to install Arches. You have two options: Local Installation (on a computer that you own), or Cloud Installation on an Amazon server Arches runs best with at least 2GB of RAM (but feel free to give it more!), so check to make sure that your computer has enough memory to support the installation. If you decide to install Arches on your own computer, you ll need to download and install an application to support the express installation. We ve designed the express installation to install Arches on a Virtual Machine (VM). Don t worry too much if you don t know what a VM is; just know that it will streamline the work needed to install Arches. And, as an added bonus, the VM will ensure that Arches can be easily started or deleted from your host computer. OK, let s begin! Option 1: Installing Arches on your own Computer You can install Arches on a laptop, PC, or server. The steps include downloading a Virtual Machine (VM) file (think of this as a complete computer all bundled up in a single file) and the software necessary to run the VM. Step 1: Download the Arches VM Start by downloading the following Arches Virtual Machine file to your computer: It s a pretty large file (about 3 GB), so depending on the speed of your Internet connection, this might take a while.

12 Express Installation Guide 3 Step 2: Install VirtualBox VirtualBox is an open source application that runs Virtual Machines. You will use VirtualBox to import and run the Arches VM that you downloaded in Step 1. Navigate to download and install VirtualBox for your OS. VMWare works too! If you already use VMWare software to run virtual machines you can skip this step and use your current VMWare product to run Arches. Step 3: Import the Arches VM Start VirtualBox, click File and then Import Appliance. Navigate to the folder where you downloaded the Arches VM files and click on ArchesVM.ova. You should see the following screen: Arches Default Screen: Simple Search Click the Continue button. VirtualBox will start the import process; you ll be presented with a summary of the VM:

13 Express Installation Guide 4 Arches Default Screen: Simple Search Press the Import button. VirtualBox will create a new VM. Step 4: Start the Virtual Machine Highlight the newly created Virtual Machine in the VirtualBox Manager, then press Start : Arches Default Screen: Simple Search During the startup process, VirtualBox may alert you with messages about how it has configured the mouse and keyboard. Go ahead and accept each message.

14 5 Express Installation Guide Step 5: Log on to the VM You will see the following log on screen: Arches Default Screen: Simple Search The user account is called Arches admin. The password is arches. Step 6: Start the Arches Server Once you ve logged on to the VM, you ll see 2 shortcuts on the desktop: Step 1: Start Arches Web Server Step 2: Open Arches

15 6 Express Installation Guide Arches Default Screen: Simple Search Double-click Step 1 icon, and then click the Run in Terminal button. Minimize the Terminal Window (Don t close it!), then double click on the Step 2 icon. If everything s gone right, you ll see the Arches welcome screen:

16 7 Express Installation Guide Arches Default Screen: Simple Search If you want to test adding or editing cultural heritage data in Arches, you ll need to sign in. Click Map in the upper right corner of the screen, then click Arches Sign In The Username and Password are both admin (omit the quotes when entering the username and password). For more help in understanding the Arches app, check out the Arches User Guide to learn how to work with Arches. Using the test data-set All test data supplied is for experimentation in Arches only. The records are not certified for accuracy or completeness. A note on Ubuntu The VM you re working with is running Ubuntu One reason we re using Ubunutu is because of its nice user interface. Check out to learn more about Ubuntu and to see a quick tutorial on using the interface.

17 Express Installation Guide 8 Option 2: Installing Arches on the Amazon Cloud You can install Arches on the Amazon cloud. The steps are pretty simple; you just have to start an Amazon server using the Arches amazon machine instance. Don t worry, its pretty easy! Before you start, you may want to familiarize yourself with the Amazon EC2 cloud at You ll find lots of useful information on what the Amazon cloud can do, as well as the costs for using it. Step 1: Set up an Amazon Account Go to and then click Sign Up and follow the on-screen instructions. Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad. Step 2: Use the Arches AMI Click on: to start building an Arches server on the Amazon cloud. Note that you ll be prompted to log in to the Amazon console ( if you haven t done so already. You should see the following screen: Click on the Continue button. Amazon Console

18 Express Installation Guide 9 Step 3: Select the Arches Server Size You ll need to decide what size server you want to run Arches (the Instance Type in Amazon lingo). We recommend either M1 Medium or C1 High CPU Medium. Amazon Console Click on the Continue button. Step 4: Create Key Pair Continue to click on the Continue button until you reach the Create Key Pair page: Amazon Console Enter a name for your key pair, then click the Create and Download your Key Pair. You ll be prompted to select a security group. You can just select the default group. More advanced Amazon users may wish to create a custom group.

19 Express Installation Guide 10 Click on the Continue button. Step 5: Launch the Arches Server Review your selections, and then press the Launch button. This will start up the Arches server. Continue on to the Amazon console: Amazon Console Highlight your Arches instance, and you will see the public URL that you ll use to access Arches. In this example, the URL is The clock has started! As soon as you press Launch, Amazon will start billing your account for your usage of the Arches server that you ve just launched. Remember that you re only charged while your Arches server is running. Using the Amazon console, you can start and stop Arches as often as you wish, thereby minimizing your costs to evaluate Arches. Step 6: Configure HTTP Access on your Server You ll need to tell Amazon to let users access your brand-new Arches server. To do this, you ll need to update your security group. To do this: Highlight your Arches server in the Amazon console, then Click Security Groups on the lower left of the screen. Click the Inbound tab From the Create a new rule dropdown, select HTTP Click Apply Rule Changes

20 Express Installation Guide 11 When you re done, you should see port 80 (HTTP) added to your security settings. Amazon Console Step 7: Log on to Arches You re now ready to log on to Arches. The web address for your instance of Arches has the following form: Amazon URL>/FGI/Arches/# In this example, you would type the following address into your web browser (note: Arches works with Firefox, Chrome, Safari, Opera, and Internet Explorer 10 or higher): If everything s gone right, you should see:

21 12 Express Installation Guide Arches Default Screen: Simple Search If you want to test adding or editing cultural heritage data in Arches, you ll need to sign in. Click Map in the upper right corner of the screen, then click Arches Sign In The Username and Password are both admin (omit the quotes when entering the username and password). For more help in understanding the Arches app, check out the User Guide at User Guide/ to learn how to work with Arches. Using the test data-set All test data supplied is for experimentation in Arches only. The records are not certified for accuracy or completeness.

22 Deploying Arches Installing Arches for production purposes consists of the following steps: Acquiring and installing the Arches software Determining what immovable cultural heritage data you wish to include in your Arches inventory Identifying (or creating) the controlled vocabularies (simple lists or more sophisticated thesauri) that you will use to describe your cultural heritage data (Optionally) Loading any pre-existing cultural heritage data that you may have into Arches Setting some basic configuration options for your Arches user community The following chapters provide step-by-step instructions for completing each of these system deployment steps. Don t worry if you re unsure about how to define cultural heritage resources or thesauri. Arches comes with a set of default cultural heritage resource types and simple thesauri to make it easier for you to adapt Arches for your specific data management needs. Before you start There are a few things to know about Arches before we get started. Arches has the following software dependencies: PostgreSQL relational database (version 9.x) PostGIS (version 2.x) spatial module for PostgreSQL Python (version 2.7) Django (version 1.5) Lucene Search Engine (version 4.4) and ElasticSearch (version 0.90) You ll need to make sure that your server has these applications loaded before Arches will work. Don t worry, these instructions will walk you through the necessary steps! Please note that Arches has been developed for modern browsers. It supports Firefox, Chrome, Safari, Opera, and Internet Explorer 10 or higher. System Requirements Arches runs best with 2GB (or more) of RAM. Diskspace requirements will vary depending on the size of your dataset, but we have found that installing PostgreSQL with default settings should get you up and running without any problems.

23 Deploying Arches 14 Arches and Cultural Heritage Standards Arches can be configured to manage a wide variety of cultural heritage data. And the software has been designed to allow for easy customization and enhancement. But the rich and complex nature of heritage data make building a system like Arches challenging. To ensure that Arches can meet the data management and interoperability needs of the cultural heritage community, Arches has been designed to comply with the following standards: CIDOC Conceptual Reference Model (CRM) ( The CRM provides definitions and a formal structure for describing the implicit and explicit concepts and relationships used in cultural heritage documentation. International Core Data Standard for Archaeological and Architectural Heritage. This is a soon-to-be finalized standard for the inventory of both archaeological and architectural heritage, which is based on the earlier Core Data Index to Historic Buildings and Monuments of the Architectural Heritage (adopted by the Council of Europe in 1992) and the Core Data Standard for Archaeological Sites and Monuments (adopted by CIDOC in 1995). The new standard under preparation (referred to here as the CDS ) was used to identify the data fields of Arches. Organizations that deploy Arches can customize those data fields to meet their specific requirements. You may wish to familiarize yourself with these data standards as part of your Arches installation and deployment effort. If you ever wish to further customize Arches, familiarity with both will help you greatly along the way.

24 Step 1: Install Core Arches This chapter presents the steps necessary to acquire and install the Arches core software on your server. In contrast to the Express Installation of Arches, this chapter summarizes the steps to install Arches in preparation for customization and a production deployment. Installation Options This guide describes the steps to complete a basic installation and configuration of Arches on: Windows Linux Vagrant Virtual Machines (For Developers) Of course, you may use the same instructions to install Arches on both in-house or remote servers. And, while this guide does not cover it, Arches can be installed across multiple machines for deployments that demand high fault tolerance. Option 1: Install Arches on a Windows Server Step 1: Download Arches Start by getting a copy of the Arches code. You can always find the most up-to-date codebase at: Create a folder called Arches on your computer and unzip the archive to this folder. Step 2: Install PostgreSQL 9.x, PostGIS 2.x Download and install the latest version of PostgreSQL for Windows from: Notes: Select all the default options when installing and take special note of the password you supply for the superuser (you ll need this later) At the end of the install leave the checkbox checked to run Stack Builder (which you ll use to install PostGIS) then click the Finish button In the Stack Builder drop-down menu, select the local Postgres database (something like PostgreSQL 9.2 on port 5432) then click Next

25 Step 1: Install Core Arches 16 Expand the Spatial Extensions link and check the box for PostGIS. Click Next Select your download directory and click Next again Click Next to start the installation of PostGIS Select all the defaults until you get to the screen where it asks for your password. Type in the password that you created earlier. Select Yes to register the GDAL_DATA environment variable,unless you have it currently set to something else and you don t want to override it. Click Close and then Finish to complete the setup of Postgres with PostGIS To confirm that you have installed PostgreSQL, open a command window and type: psql. You should be prompted for a password. If so, then PostgreSQL is installed and you may close the command prompt. If you received an error like psql is not recognized as an internal or external command, operable program or batch file then you probably need to add an entry to your path. Assuming that your Postgres installation is in C:\Program Files\PostgreSQL\9.x, add this to your path: C:\Program Files\PostgreSQL\9.x\bin (Note: make sure to replace 9.x with your version of Postgres) PostgreSQL Warnings If you experience errors during the installation, please check that the setting standard_conforming_strings in postgresql.conf is uncommented and set to off. See this question on stackoverflow for more information. Step 3: Install Python 2.7 Download Python at Notes: Download the latest MSI Installer for version 2.7.x (Note: make sure to select the x86 version for 32bit machines, or x86-64 for 64bit machines) Run the installer and select all the default options when prompted. Assuming that your Python installation is in C:\Python27\, add this to your PATH: C:\Python27\;C:\Python27\Scripts If you are unsure how to do this, look here: Python Versions Arches is only compatible with Python 2.7. Python 3.x is right out.

26 Step 1: Install Core Arches 17 Step 4: Install the latest Java Development Kit (JDK) Download and install the JDK from Notes: Select all the default options, except at the very end, uncheck the box that asks to install the Ask.com toolbar. Right-click the My Computer icon on your desktop and select Properties to set the JAVA_HOME environment variable. Click the Advanced tab. Click the Environment Variables button. Under System Variables, click New. Enter the variable name as JAVA_HOME. Enter the variable value as the installation path for the Java Development Kit. (If you used the default path for the Java Development Kit during installation, use C:\Program Files\Java\jdk1.7.0_25. This string should be your variable value.) Click OK. Click Apply Changes. Close any command window which was open before you made these changes, and open a new command window. There is no way to reload environment variables from an active command prompt. If the changes do not take effect even after reopening the command window, restart Windows. Step 5: Install Web Framework Now that you ve installed the database software Arches uses, you re ready to install the Django web framework ( and search engine ( Arches uses. Open a command window and navigate to: arches/install Then run the following script: install.bat Once this script runs you ll need to start the ElasticSearch search engine. Navigate to the root arches folder: cd.. and run this script:

27 Step 1: Install Core Arches 18 runserver.bat Windows may automatically open a command window as part of this step. Step 6: Install Arches Open a new command window, and navigate to: arches/build Run the following script to build Arches: build_core_arches.bat Database Password You may be prompted for a password to the Arches database. The default password is: postgis. You can open Settings.py in the arches root folder to change the default arches password, or to install Arches on to an existing instance of PostgreSQL/PostGIS. Next Steps You ve just completed the steps needed to install the core Arches application on your server. But you re not done yet! You still have the following steps to complete: Define the cultural heritage resources you want Arches to manage (see Step 2: Load Heritage Resource Definitions ) Define the controlled vocabularies that you ll use to describe heritage (see Step 3: Load Controlled Vocabularies ) (Optionally) Import data from a legacy system into Arches (see Step 4: Load Data into Arches ) Configure the default settings for Arches (see Step 5: Configuring Arches ) Option 2: Install Arches on a Linux Server The following instructions were written with Ubuntu LTS in mind. Other versions of Ubuntu or other Linux distributions might have some different steps, but the general outline should be similar. All instructions assume that they are entered through the terminal and that the user has root privileges. Step 1: Download Arches Navigate to the Arches download page at and click on the download link. Create a folder called Arches on your computer and unzip the archive to this folder. Or use the command line:

28 Step 1: Install Core Arches 19 sudo wget sudo tar -xzf default.tar.gz After unzipping, rename Arches archive folder to Arches. Step 2: Install PostgreSQL/PostGIS Install PostgreSQL, PostGIS and the PostgreSQL development library (needed to compile the Python bindings). Start by getting the repositories: sudo apt-get update -y sudo apt-get install -y make python-software-properties sudo add-apt-repository -y ppa:pitti/postgresql sudo add-apt-repository -y ppa:sharpie/for-science sudo add-apt-repository -y ppa:sharpie/postgis-stable sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable sudo apt-get update -y Install the database: sudo apt-get install -y build-essential postgresql-9.2 postgresql-server-dev-9\.2 libxml2- dev libproj-dev libjson0-dev xsltproc docbook-xsl docbook-mathml\ libgdal1-dev postgresql- contrib-9.2 postgresql-server-dev-9.2 libpq-dev sudo -u postgres psql -d postgres -c "ALTER USER postgres with encrypted passw\ ord 'postgis';" sudo echo "*:*:*:postgres:postgis" >> ~/.pgpass sudo chmod 600 ~/.pgpass Configure the connection parameters: cd.. cd.. sudo chmod 666 /etc/postgresql/9.2/main/postgresql.conf sudo echo "standard_conforming_strings = off" >> /etc/postgresql/9.2/main/post\ gresql.conf sudo echo "listen_addresses = '*'" >> /etc/postgresql/9.2/main/postgresql.conf sudo chmod 666 /etc/postgresql/9.2/main/pg_hba.conf sudo echo "#TYPE DATABASE USER CIDR-ADDRESS METHOD" >> /etc/postgresql/9.\ 2/main/pg_hba.conf sudo echo "local all all trust" >> /etc/postgresql/9.2\

29 Step 1: Install Core Arches 20 /main/pg_hba.conf sudo echo "host all all /32 trust" >> /etc/postgresql/9.2\ /main/pg_hba.conf sudo echo "host all all ::1/128 trust" >> /etc/postgresql/9.2\ /main/pg_hba.conf sudo echo "host all all /0 md5" >> /etc/postgresql/9.2/m\ ain/pg_hba.conf sudo service postgresql restart Install the GEOS library: sudo wget sudo tar xvfj geos tar.bz2 cd geos /configure make sudo make install cd.. Get PostGIS: sudo wget sudo tar xfvz postgis tar.gz cd postgis /configure make sudo make install sudo ldconfig sudo make comments-install sudo ln -sf /usr/share/postgresql-common/pg_wrapper /usr/local/bin/shp2pgsql sudo ln -sf /usr/share/postgresql-common/pg_wrapper /usr/local/bin/pgsql2shp sudo ln -sf /usr/share/postgresql-common/pg_wrapper /usr/local/bin/raster2pgsql cd.. sudo -u postgres psql -d postgres -c "CREATE EXTENSION postgis;" sudo -u postgres createdb -E UTF8 -T template0 --locale=en_us.utf8 template_po\ stgis_20 sudo -u postgres createlang -d template_postgis_20 plpgsql sudo -u postgres psql -d postgres -c "UPDATE pg_database SET datistemplate='tr\ ue' WHERE datname='template_postgis_20'"

30 Step 1: Install Core Arches 21 sudo -u postgres psql -d template_postgis_20 -f /usr/share/postgresql/9.2/cont\ rib/postgis-2.0/postgis.sql sudo -u postgres psql -d template_postgis_20 -f /usr/share/postgresql/9.2/cont\ rib/postgis-2.0/spatial_ref_sys.sql sudo -u postgres psql -d template_postgis_20 -f /usr/share/postgresql/9.2/cont\ rib/postgis-2.0/rtpostgis.sql sudo -u postgres psql -d template_postgis_20 -c "GRANT ALL ON geometry_columns\ TO PUBLIC;" sudo -u postgres psql -d template_postgis_20 -c "GRANT ALL ON geography_column\ s TO PUBLIC;" sudo -u postgres psql -d template_postgis_20 -c "GRANT ALL ON spatial_ref_sys \ TO PUBLIC;" sudo -u postgres createdb training -T template_postgis_20 Get the latest JDK: sudo apt-get install -y openjdk-7-jdk python-setuptools python-dev Finally, install the PostGIS template database: sudo -u postgres createdb -E UTF8 -T template_postgis_20 --locale=en_us.utf8 a\ rches PostgreSQL Warnings If you experience errors during the installation, please check that the setting standard_conforming_strings in postgresql.conf is uncommented and set to off. See for more information. Step 3: Install Web Framework Now that you ve installed the database software Arches uses, you re ready to install the Django web framework ( and search engine ( Arches uses. Navigate to:

31 Step 1: Install Core Arches 22 cd./install Then run the following script:./install.sh Once this script runs you ll need to start the ElasticSearch search engine. Navigate to the root folder: cd.. and run this script:./runserver.sh Step 4: Install and Build Arches Open a new terminal window, and navigate to: cd./build Run the following script to build Arches:./build_core_arches.sh Database Password You may be prompted for a password to the Arches database. The default password is: postgis. You can open Settings.py in the arches root folder to change the default arches password, or to install Arches on to an existing instance of PostgreSQL/PostGIS. Next Steps You ve just completed the steps needed to install the core Arches application on your server. But you re not done yet! You still have the following steps to complete: Define the cultural heritage resources you want Arches to manage (see Step 2: Load Heritage Resource Definitions ) Define the controlled vocabularies that you ll use to describe heritage (see Step 3: Load Controlled Vocabularies ) (Optionally) Import data from a legacy system into Arches (see Step 4: Load Data into Arches ) Configure the default settings for Arches (see Step 5: Configuring Arches )

32 Step 1: Install Core Arches 23 Option 3: Install Arches on a Vagrant Virtual Machine Developers may wish to install Arches using Vagrant. Vagrant ensures that all developers can work on the same platform. And if you decide to use a local Mercurial client (like SourceTree), Vagrant will allow you to quickly test your code in a virtual environment. Check out for more information. Step 1: Download Arches Start by getting a copy of the Arches code. You can always find the most up-to-date codebase at: Create a folder called Arches on your computer and unzip the archive to this folder. Or, consider using a local Mercurial client to manage the Arches codebase locally. Step 2: Install Vagrant Navigate to download and install the Vagrant software for your operating system (OS). Step 3: Install VirtualBox VirtualBox is an open source Virtual Machine application. Navigate to download and install VirtualBox for your OS. Step 4: Download Virtual Machine File Open a command prompt and type the following command to download an empty Ubuntu server (version 12.04, 32-bit) VM file vagrant box add precise32 \ You can consult the Vagrant website if you prefer to use an alternate base OS for your Arches VM. Pro Tip: Windows Installation For some versions of Windows you may get an error when running the vagrant box add command. Try running the command again, this time WITHOUT the / after the precise32. Check the latest vagrant documentation for additional troubleshooting help. Step 5: Build Arches Open a command prompt and navigate to the Arches folder:

33 Step 1: Install Core Arches 24 cd arches once you ve navigated to your arches folder, type: vagrant init precise32 then: vagrant up Pro Tip: Making Arches run with less than 2 GB of RAM Before you vagrant up, open this file: arches/vagrantfile with a text editor. Scroll down to vb.customize [ modifyvm, :id, memory, 2048 ]. Replace the 2048 with 1024, and Arches will only request 1GB of RAM. Vagrant will create a Virtual Machine with a complete Arches install, including all required software dependencies, as well as a sample dataset ready for you to test Arches with. How long will it take to build Arches? Depending on your computer, it may take anywhere from 10 minutes to an hour or two to build Arches.You ll know that Arches is ready when the command prompt returns. Step 6: Start Arches At the command prompt type: vagrant ssh This command will log you onto your virtual Linux server. To start Arches, navigate to the Arches folder in your virtual server. Run the Arches build script by typing the following command:./runserver-vagrant.sh Windows Users: Get an ssh client Because Windows doesn t usually come with ssh, you ll need to install a ssh client like PuTTY. See the Vagrant documentation ( for more information.

34 25 Step 1: Install Core Arches Arches will start and be ready for use in just a moment or two. To access Arches, open a browser (note: Arches works with Firefox, Chrome, Safari, Opera, and Internet Explorer 10 or higher), and type: You should see the following screen: Arches Default Screen: Simple Search If you want to test adding or editing cultural heritage data in Arches, you ll need to sign in. Click Map in the upper right corner of the screen, then click Arches Sign In The Username and Password are both admin (omit the quotes when entering the username and password). For more help in understanding the Arches app, check out the Arches User Guide to learn how to work with Arches. Using the test data-set All test data supplied is for experimentation in Arches only. The records are not certified for accuracy or completeness. A Note on Vagrant Vagrant is a handy way to quickly set up a server for software testing.

35 Step 1: Install Core Arches 26 If you review the Vagrant documents, you ll see that you can halt the Arches VM simply by typing: vagrant halt Starting Arches again is a simple vagrant up command. You can completely remove Arches from your computer by typing: vagrant destroy While Vagrant is a great way to evaluate Arches, it s not necessarily the way you d want to deploy Arches for a project. For one thing, we haven t built-in a back-up of the Arches database for vagrant. So if you vagrant destroy your version of Arches, be prepared to lose any data that you may have entered. Don t worry though. You can always type vagrant up and get a pristine version of Arches running again.

36 Step 2: Load Resource Type Definitions In this chapter you ll learn that Arches manages cultural heritage data as resources, and you ll understand how to install the resource files that you want to use to manage your data. What are Resources? Arches is designed to manage cultural heritage data anywhere in the world. Needless to say, that s an ambitious goal. After all, architecture considered culturally significant in San Francisco - a city founded in might not merit much comment in Cairo or London. So, how does Arches resolve this? Arches requires you to define the set of Resource Types that you wish to include in your inventory and the terms that you will use to describe them. What is an Arches Resource Type? In Arches, the term Resource Type refers to a class of cultural heritage records. Things like Architectural Heritage, Investigation Activity, and Person are all examples of Resource Types.Think of Resource Types as the categories of information that Arches will manage. A Resource is simply one instance of a particular Resource Type. Resource Types are described following the CIDOC Conceptual Reference Model (CRM). The CRM is an ontology for cultural heritage information that has been developed by a the International Committee for Documentation (CIDOC) of the International Council of Museums. Arches uses the CRM because it was adopted by the International Organization for Standardization as the standard (ISO 21127:2006) for the interchange of cultural heritage information. Arches Resource Type Categories By default, Arches groups Resource Types into the following categories: Heritage Resources: Heritage Resources are archaeological, built, landscape, or other immovable cultural heritage. In Arches, Heritage Resources include:

37 Step 2: Load Resource Type Definitions 28 Archaeological Heritage (element) a single archaeological entity that could stand alone or be an element of a larger archaeological group (e.g., a bath house within a Roman villa) Archaeological Heritage (site) an area of archaeological potential or an area of known or discovered archaeological elements What s the difference between archaeological elements and sites? While conceptually these categories overlap, Arches differentiates between the two because of the way that they are represented using the CIDOC CRM. Architectural Heritage culturally significant buildings, structures, and groups thereof Landscape Heritage areas of land designed and created intentionally by man, such as garden and parkland landscapes constructed for aesthetic reasons, organically evolved areas of land resulting from an initial social, economic, administrative, and/or religious imperative and that has developed its present form by association with and in response to its natural environment, or areas of land that are culturally significant due to powerful religious, artistic or cultural associations of the natural element rather than material cultural evidence, which may be insignificant or even absent (UNESCO) Maritime Heritage underwater heritage (both under sea and inland), which may include heritage inundated by sea level rise and dam construction, shipwrecks and aircraft, as well as heritage afloat (e.g., ships, sailing vessels) Activities Activities are events or actions that may take place during a given time span and at a location or area. In Arches, Activities include: Investigation Activity an activity undertaken with the explicit intention of gathering information about, and understanding of, a Heritage Resource, and the creation of an information source to record that information and understanding Management Activity an activity undertaken to prevent damage to, promote the survival of, and promote the understanding and appreciation of Heritage Resources.

38 Step 2: Load Resource Type Definitions 29 Designation and Protection Activity an activity which implements or revokes statutory and non-statutory designation and protection regimes which may apply to Heritage Resources Historical Event any activity that took place in the past, including both human and natural events Documents Documents are information carriers such as books, texts, periodicals, inscriptions, audio files, video files, 3-D models, or images. In Arches, Documents include: Document an information carrier, other than an Image, whether physical or digital, eg. books, maps, pdfs, word-processed documents Image an information carrier that represent an external form, whether physical or digital, eg. photographs, slides, drawings, jpegs or tiff files Actors Actors refer to individuals or groups of people. In Arches, Actors include: Person real persons (i.e., who live or are assumed to have lived) Organization A group or legally identifiable body Creating Your Own Resource Types You may decide that Arches does not include a Resource Type that you need. If that s the case, you can create you own Resource Type definitions. Defining an Arches Resource Type requires you to build a graph of entities. You ll need the CIDOC CRM to define the set of entities, their relationships, and any controlled vocabularies necessary to describe your custom Resource Type. Take a look at one of Arches default Resource Type definition files, such as Architectural Heritage, to see what a Resource Type definition looks like. You can find those files at: arches/db/etl/cds Package/Mappings You can view a Resource Type graph using a tool such as Gephi. Or you can just create a file of nodes and a file of edges to define a resource. Creating your own Resource Type definitions requires that you are comfortable with using the CIDOC CRM, and that you have a good working knowledge of how to define thesauri. Consequently, defining your own resource is an advanced topic, and you may wish to check site for additional guidance.

39 Step 2: Load Resource Type Definitions 30 Loading Resources Although Arches provides a suite of Resource Type definitions, you are not required to use them all. Before you can start creating and managing cultural heritage data, you ll need to decide which Resource Types you want to use and then load the corresponding Resource Type definitions into Arches. Step 1: Select Resources to Load Navigate to the arches directory and open: settings.py Scroll down until you find the LIMIT_ENTITIES_TO_LOAD parameter: Settings.py: Simple Search By default, Arches loads all 13 Resource Type definitions (hence the limit to load is None). You can define the specific definitions to load by providing a comma-delimited listing of just the resources you want to manage: LIMIT_ENTITY_TYPES_TO_LOAD = ('ARCHAEOLOGICAL HERITAGE (ARTIFACT).E18', 'LANDS\ CAPE HERITAGE.E27) This would limit Arches to just loading the definitions for the Archaeological Heritage element) and Landscape Heritage types. Tip: Resource Type Names Use the following following formal names to identify the Resource Types you wish to load into Arches:

40 Step 2: Load Resource Type Definitions 31 ARCHAEOLOGICAL HERITAGE (ARTIFACT).E18 ARCHAEOLOGICAL HERITAGE (SITE).E27 ARCHITECTURAL HERITAGE.E18 LANDSCAPE HERITAGE.E27 MARITIME HERITAGE.E18 INVESTIGATION.E7 MANAGEMENT.E7 DESIGNATION AND PROTECTION.E7 HISTORICAL EVENT.E5 DOCUMENT.E31 IMAGE.E38 PERSON.E21 ORGANIZATION.E74 Step 2: Load Resource Type Definitions Open a terminal and navigate to the following folder: db/etl/cds Package and run the following script: install_package.bat (./install_package.sh for Linux) Arches will install the set of Resource Types that you ve defined. Next Steps You ve just completed one of the most important installation steps: deciding which cultural heritage Resource Tsypes you will be managing. The next step in installing Arches is to decide which controlled vocabularies you will use to describe your cultural heritage resources. Turn to Step 3: Load Controlled Vocabularies.

41 Step 3: Load Controlled Vocabularies In this chapter you ll learn how to configure the drop-down lists Arches uses to support consistent and valid cultural heritage data entry. What are Controlled Vocabularies? Like any good data-editing tool, Arches supports consistent and valid data entry. Almost every one is familiar with this concept: it s the ability to select a valid value from a list: Selecting a value from a Controlled Vocabulary Notice that in this Arches data entry form, you re able to select the kind of Archaeological Heritage Element from among the list of approved types or classifications. In Arches, these lists are called controlled vocabularies. But what if you want to use a particular list of period names, instead of the names that come with Arches? Arches allows you to define exactly the set of names you want to use for every resource. Thesauri So, why do we use the term controlled vocabulary if all we re doing is selecting values from a drop-down list? The answer is that Arches treats each drop-down list as if it s a thesaurus.