Installing Core Arches#
See also
If you plan to extend or contribute to Arches, please see Creating a Development Environment.
See also
We have an in-progress Docker install, and would love help improving it. You can also review some works-in-progress and community-created approaches to using Docker Installation with Docker
Create a Virtual Environment#
You need a Python 3.10+ virtual environment. Skip ahead if you have already created and activated one. Otherwise, use the commands below for a quick start.
Create a virtual environment:
python3 -m venv ENV
This will generate a new directory called ENV
.
Note
On some linux distributions, if the python version is less than 3.10, entering the following command may yield an error but it should alert you to any dependencies you may need to install, after which you’ll be able to run this command.
Activate the virtual environment
The following are relative paths to an activate
script within ENV.
Linux and macOS:
source ENV/bin/activate
Windows:
ENV\Scripts\activate.bat
Note
After you activate your virtual environment, your command prompt will be prefixed with (ENV)
. From here on the documentation will assume you have your virtual environment activated. Run deactivate
if you need to deactivate the virtual environment.
Test the Python version in ENV:
python
This will run the Python interpreter and tell you what version is in use. If you don’t
see at least 3.10, check your original Python installation, delete the entire ENV
directory, and create a new virtual environment. Use exit()
or ctrl+C
to
leave the interpreter.
Upgrade pip
A recommended step, though not always strictly necessary:
python -m pip install --upgrade pip
Install Arches with pip#
Use the following to get the latest stable release of Arches:
pip install arches
Creating a New Arches Project#
A Project holds branding and customizations that make one installation of Arches different from the next. The name of your project must be lowercase and use underscores instead of spaces or hyphens. The example below uses my_project
.
Create a Project#
Linux and macOS:
arches-project create my_project
Windows:
python ENV\Scripts\arches-project create my_project
Note
You can add --directory path/to/dir
to change the directory your new project will be created in.
Warning
On Windows, open my_project\my_project\settings_local.py
and add the following line:
GDAL_LIBRARY_PATH = "C:/OSGeo4W64/bin/gdal201.dll"
Be sure to adjust the path as necessary for your GDAL installation, and note the forward slashes.
Warning
On macOS, pip install
will often fail because the installation of psycopg
(a Postgres driver for Python) needs to access Postgres’ pg_config
and does so by looking in the PATH
. Some methods for installing Postgres on macOS will require one to manually edit their user profile to edit their profile configuration file e.g. .zprofile
or .zshrc
(see background). You’ll need to create or update your user’s .zshrc
as so:
# Use a text editor to create or modify your user's .zshrc file
nano ~/.zshrc
# Add this line to the .zshrc file, then save the update.
export PATH="/Applications/Postgres.app/Contents/Versions/14/bin:$PATH"
# Make sure the update to the .zshrc file takes effect
source ~/.zshrc
In addition, a macOS installation will likely require some modifications to settings.py
(or settings_local.py
) in your project directory to specify GDAL and GEOS related paths. (See macOS and GDAL, GEOS)
Setup the Database#
First, enter the project directory:
cd my_project
and then run:
python manage.py setup_db
Note
You may be prompted to enter a password for the postgres
user. Generally, our installation scripts set this password to postgis
, however you may have set a different password during your own Postgres/PostGIS installation.
Build a Frontend Asset Bundle#
In your current terminal, run the Django development server (with the Arches virtual environment activated):
python manage.py runserver
Then, in a second terminal, activate the virtual environment used by Arches (this is a required step). Then navigate to the root directory of the project. ( you should be on the same level as package.json) and build a frontend asset bundle:
cd my_project/my_project
yarn build_development
If you have trouble with this step, see Troubleshooting Frontend Builds below.
Note
yarn build_development
creates a static frontend asset bundle. Any changes made to frontend files (eg. .js
) will not be viewable until the asset bundle is rebuilt. run yarn build_development
again to update the asset bundle, or run yarn start
to run an asset bundler server that will detect changes to frontend files and rebuild the bundle appropriately.
View the Project in a Browser#
Navigate to localhost:8000
in a browser. Use ctrl+C
to stop the server.
Configure the Map Settings#
The first thing everyone wants to do is look at the map, so let’s set this up first.
Go to Mapbox.com and create a free account.
Find your default API key (starts with
pk.
) and copy it.Now go to
localhost:8000/settings
.Login with the default credentials: username:
admin
password:admin
Find the Default Map Settings, and enter your Mapbox API Key there.
Feel free to use the
?
in the top-right corner of the page to learn about all of the other settings, and change any that you like (heed warning below).Save the settings.
Navigate to
localhost:8000/search
to make sure the basemap appears.
Note
We recommend exporting these settings by running python manage.py packages -o save_system_settings
.
This will create a JSON file in your project, which will be used if you ever need
to setup your database again.
Warning
If you create a new Project Extent, you should also update the Search Results Grid settings, otherwise you could get a JSON error in the search page. To be on the safe side, choose a high Hexagon Size combined with a low Hexagon Grid Precision.
Load a Package#
An Arches “package” is an external container for database definitions (graphs, concept schemes), custom extensions (including functions, widgets, datatypes) and even data (resources). Packages are installed into projects, and can be used to share schema between installations.
To get started, load this sample package:
python manage.py packages -o load_package -s https://github.com/archesproject/arches-example-pkg/archive/master.zip -db
Go to localhost:8000/graph
to see 6 Resource Models that you can now use. You can also create new Resource models from scratch.
Go to localhost:8000/resource
to begin creating resources based on one of these resource models.
Go to localhost:8000/search
to find and inspect resources that you have created.
You can add -dev
to the load_package command to create a few test user accounts.
What Next?#
Read more about Projects and Packages
Common Errors#
On macOS, If you get this error
Error
ValueError: –enable-zlib requested but zlib not found, aborting.
try running
xcode-select --install
(reference)Getting a connection error like this (in the dev server output or in the browser)
Error
ConnectionError: ConnectionError(<urllib3.connection.HTTPConnection object at 0x0000000005C6BC50>: Failed to establish a new connection: [Errno 10061] No connection could be made because the target machine actively refused it) caused by: NewConnectionError(<urllib3.connection.HTTPConnection object at 0x0000000005C6BC50>: Failed to establish a new connection: [Errno 10061] No connection could be made because the target machine actively refused it)
means Arches is not able to communicate with ElasticSearch. Most likely, ElasticSearch is just not running, so just start it up and reload the page. If you can confirm that it is running, make sure Arches is pointed to to correct port.
Postgres password authentication error
Error
django.db.utils.OperationalError: FATAL: pw authentification failed for user postgres
Most likely you have not correctly set the database credentials in your
settings.py
file. Many of our install scripts set the db user topostgres
and password topostgis
, so that’s what Arches looks for by default. However, if you have changed these values (particularly if you are on Windows and had to enter a password during the Postgres/PostGIS installation process), the new values must be reflected in insettings.py
orsettings_local.py
.Note
On Windows, you can avoid having to repeatedly enter the password while running commands in the console by setting the PGPASSWORD environment variable:
set PGPASSWORD=<your password>
.
Troubleshooting Frontend Builds#
Building the frontend assets can sometimes be a source of challenge and frustration. Sometimes a “locked down” computer (with strict security configurations) may cause some trouble. If this is the case, you can try the following steps to interate toward a successful build.
- Edit your
.yarnrc
file to disable strict SSL. To do so, navigate to your project’s root directory and open the
.yarnrc
file in a text editor. Add the following lines to the end of the file: .. code-block:: bashcafile null strict-ssl false
- Edit your
After the above edits, save the file.
- Remove the
node_modules
folder andyarn.lock
file if they exist: cd path/to/dir/my_project/my_project rm -rf node_modules rm yarn.lock
- Remove the
- If you’re using a virtual environment, activate it. ENV should be replaced with the name of your virtual environment.
source ENV/bin/activate
- Run your Arches Django server and leave it running.
python manage.py runserver
Open a *new terminal* to complete the following steps below.
- If you’re using a virtual environment, activate it as in step 4 above. ENV should be replaced with the name of your virtual environment.
source ENV/bin/activate
- Navigate to the same directory as package.json, and install the frontend dependencies:
cd path/to/dir/my_project/my_project yarn install
- Once the dependencies are installed, build your static asset bundle:
yarn build_development
If successful, you should see a message indicating that the build was successful. A successful build should make a message looking something like this:
cacheable modules 8.62 MiB (javascript) 3.28 KiB (asset) modules by path ./media/ 6.48 MiB 996 modules modules by path ../../ 2.15 MiB (javascript) 3.28 KiB (asset) modules by path ../../arches/arches/app/media/ 1.2 MiB (javascript) 3.28 KiB (asset) 264 modules modules by path ../../arches/arches/app/templates/views/ 970 KiB 90 modules ../../arches-rdm/arches_rdm/media/js/.gitkeep 1 bytes [built] [code generated] ./media/js/ sync ^./.*$ 207 bytes [optional] [built] [code generated] ../../arches/arches/app/media/js/ sync ^./.*$ 18.9 KiB [optional] [built] [code generated] ../../ENV/lib/python3.10/site-packages/ sync ^./.*/media/js/.*$ 160 bytes [optional] [built] [code generated] ../../arches-rdm/arches_rdm/media/js/ sync ^./.*$ 160 bytes [optional] [built] [code generated] ../../arches/arches/app/media/js/utils/ sync ^.*/media/js/.*$ 160 bytes [optional] [built] [code generated] ./media/node_modules/moment/locale/ sync ^./.*$ 3.21 KiB [optional] [built] [code generated] webpack 5.89.0 compiled successfully in 8545 ms ✨ Done in 10.71s.