Installation

System Requirements

Arches works on Linux, Windows, or macOS, but some of its dependencies may be more difficult to install on certain operating systems. Most enterprise-level installations of Arches have been created on Linux servers.

To begin development or make a test installation of Arches, you will need the following:

  • 2gb disk space
    • 1.5gb for all dependencies and 600mb for Arches.
    • In production, the amount of disk space you need will depend on the number of resources in your database, specifically uploaded images or media files.
  • 4gb memory (RAM)
    • This recommendation is calculated by the fact that ElasticSearch requires 2gb to run, and as per ElasticSearch documentation no more than half of your system’s memory should be dedicated to ElasticSearch.
    • In development, it’s possible to force ElasticSearch to run with only 1gb of memory, as we have noted here.
    • In production, you may want to increase your memory, and allow ElasticSearch to use more than its default.

Please note that Arches 4.0.0 release is only fully supported in Chrome.

Dependencies

These instructions will provide some guidance on installing the required dependencies and getting Arches up and running quickly.

Installing Arches

Once you have all of the dependencies installed, open a command prompt and use the following steps to install the latest stable release of Arches. To install the latest non-stable Arches code (generally only necessary for developers), you can follow these installation steps.

  1. Create and enter a new directory called Projects:

    mkdir Projects && cd Projects
    
  2. Create a virtual environment called ENV:

    virtualenv ENV
    
  3. Activate the new virtual environment

    Linux and macOS:

    source ENV/bin/activate
    

    Windows:

    ENV\Scripts\activate
    

    Note

    At this point (once the virtual environment is activated), Windows users need to manually install Shapely. Follow these instructions.

  4. Install Arches into your virtual environment

    You can install Arches with pip:

    pip install arches --no-binary :all:
    

    Warning

    Running a pip installation without the --no-binary :all: argument will install arches in your virtual environment, but will not install all of the separate python packages that you need. This will cause you to not be able to proceed with the following steps.

  5. Create a new Arches project

    A project is a standalone Arches app that sits outside of your virtual environment and facilitates all of the customizations that you will need to make one installation of Arches different from the next.

    Linux and macOS:

    arches-project create my_project
    

    Windows:

    python C:\Projects\ENV\Scripts\arches-project create my_project
    

    Note

    On Windows, the above command will end in an error on the last step of the command. The workaround for this is to enter my_project\my_project\ (the directory that contains bower.json) and run this command: bower install.

    Warning

    On Windows, you must specify the path to your GDAL library before continuing. Open settings.py in your new project and add this line: GDAL_LIBRARY_PATH = 'C:/OSGeo4W64/bin/gdal201.dll' Be sure to adjust the path as necessary for your installation, and note the forward slashes.

    At this point you should install ElasticSearch (unless you have done so already) before continuing.

  6. Setup your Arches database

    First, make sure ElasticSearch is installed and running

    Then create your Arches database with:

    python manage.py packages -o setup_db
    
  7. Run the development server

    To view Arches, run:

    python manage.py runserver
    

    You can now view Arches by navigating to localhost:8000 in a browser.

More about Arches Projects

Arches Projects facilitate all of the customizations that you will need to make one installation of Arches different from the next. You can update html to modify web page branding, and add functions, datatypes, and widgets to introduce new functionality. A project sits outside of your virtual environment, and can thus be transferred to any other system where Arches is installed.

The general structure of a new Arches project is::

my_project/
└─ manage.py
└─ my_project/
      └─ settings.py
      └─ datatypes/
      └─ functions/
      └─ media/
      └─ templates/
      └─ widgets/

Note that not all files are shown

settings.py

Many project-specific settings are defined here. You will likely want to add a settings_local.py file that can separately store variables that you may want to keep out of the public eye (db passwords, API keys, etc.).

templates

This directory holds HTML templates that you can modify to customize the branding and general appearance of your project.

datatypes, fuctions, and widgets

These directories will store the custom datatypes, functions, and widgets that you can create for the project. Developers interested in pursuing these customizations should start with this customization documentation.