Creating a Development Environment

The following is our recommedation for creating an Arches environment that works well for developers. The first thing to consider is the general structure that will be in place, presumably all in the same directory:

• /ENV - A virtual environment, we’ll name it ENV. This should be built from Python 2.7.x, and you should make sure pip is up-to-date. python -m pip install –upgrade pip
• /arches - The local clone of your fork of the archesproject/arches repo, which gets installed into your virtual environment. Often, this part of the code is referred to as “core Arches”.
• /my_project - The location of your Arches project. This is the app in which you will be making the majority of your front-end customizations (new images, new template contents, etc.).
• /my_package - The location of your Arches package. Packages contain all of the custom database definitions that you will use. Resource Models, Branches, Concepts, Datatypes, Widgets, Functions, business data (resources for initial load)… these are all stored in a package. Packages are loaded into Projects via the command line.

Setting Everything Up

1. Make sure all dependencies are installed. You may also have external services in mind for some of the Arches dependencies, like a remote Postgres/Postgis or ElasticSearch installation. In that case you’ll those credentials eventually, but not immediately. You’ll also need git installed locally.

2. Make a new virtual environment built from Python 2.7.x and activate it.

   virtualenv ENV
   source ENV/bin/activate
   

   or, to activate on Windows:

   ENV\Scripts\activate
   

3. Clone the archesproject/arches repo. We recommend that you clone your own fork of the repo, but you can also clone the original repo if you don’t plan to contribute code.

   (ENV)$ git clone https://github.com/archesproject/arches.git
   

4. Link your local clone of the repo to ENV. This is instead of using pip install arches which would install the pypi Arches distribution directly into ENV. When you install the local clone, any code changes you make inside of /arches (like checking out a new git branch) will be immediately reflected in your runtime environment.

   (ENV)$ cd arches
   (ENV)$ pip install -e .
   (ENV)$ pip install -r arches/install/requirements.txt
   (ENV)$ pip install -r arches/install/requirements_dev.txt
   (ENV)$ cd ..
   

5. Create the new project you will be working on. In this project you’ll make all of the necessary changes to your templates, define all of your settings.py variables, run manage.py, etc. This is also where all your yarn components will be installed.

   (ENV)$ arches-project create my_project
   

   or on Windows:

   (ENV)\> ENV\Scripts\python.exe ENV\Scripts\arches-project create my_project
   

   Note

   You can use the option [{-d|--directory} <directory_name>] to change the directory your new project will be created in.

6. You can now enter your new project and create a package

   (ENV)$ cd my_project
   (ENV)$ python manage.py packages -o create_package -d ../my_package
   

   on Windows remember to change the forward slashes to backward slashes.

---

You now have your development environment ready. It should look like:

/Projects
    /env        # virtual environment, activate this but don't modify things inside of it
    /arches     # clone of your core Arches fork (git repo)
    /my_project # the project, where you store settings and from which you run manage.py_package (could be a git repo)
    /my_package # the package, where you should export your resource models, etc. so you can share them (could be a git repo)

Before proceeding, you should either alter the settings.py file in your project to give it your postgres/postgis credentials DATABASES['default'], or add a settings_local.py file and put the credentials there to keep them out of version control (and, if you are on windows, you need GDAL_LIBRARY_PATH = path/to/gdalxxx.dll). Then get ElasticSearch running and you can run python manage.py packages -o setup_db. Now you can run python manage.py runserver and view Arches in a browser.

Note

Whenever changes occur in the Arches code base, you may want to update your local clone. If you are not going to make a new project from the updated code, you should run yarn install and python manage.py migrate to fully update your local install. These commands should be run from within /arches.