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 itENV
. 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¶
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.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
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
Link your local clone of the repo to
ENV
. This is instead of usingpip install arches
which would install the pypi Arches distribution directly intoENV
. When you install the local clone, any code changes you make inside of/arches
(like checking out a newgit
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 ..
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 youryarn
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.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
.