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 beta 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, you can use pip to install Arches. It’s best to do this in a virtual environment. Using a command prompt, follow these 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==4.0b3
    

    Note

    Windows users should use pip install arches==4.0b3 --no-use-wheel. The extra argument will avoid some extraneous error messages during the installation process. However, Arches will install successfully whether you add that argument or not.

    Arches is now installed! At this point you should install ElasticSearch (unless you have done so already), and then continue with the next steps to guide you through the creation of an Arches “project”.

  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
    
  6. Run the bower installation

    Enter your new project directory (cd my_project) and run:

    bower install
    
  7. 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
    
  8. 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.

If you want to install Arches directly from the GitHub repo (instead of from the stable pip distribution), use this documentation.

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 default structure of a new Arches project is (not all files shown):

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

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