Configuring Settings

Quick Start

Once Arches is installed, there are a few settings you must configure to make it fully operational. In the Arches interface, head to the System Settings menu (you must be logged in as the admin user, default password is admin).

The most important settings to begin with are related to the map on the Search page.

  1. Enter your Mapbox API Key.

    By default, Arches uses a few basemap services from Mapbox, for which you need to provide a key. You can get a free key at mapbox.com, and for installations that do not expect exceptionally heavy traffic, this free key will be sufficient. Once you have obtained the key, copy it from Mapbox (it will start with pk.). Go to System Settings – > Map Settings –> Mapbox API and enter it there.

    Note

    If you don’t want to use MapBox, you can avoid this step by loading in a different basemap and removing all of the default MapBox layers. More about loading different basemaps in Creating New Map Layers.

  2. Set the default Map Zoom and Project Extent settings

    The Map Zoom is useful for geometry editing, but note that the Search page will automatically zoom to the extent of your search results every time they are updated. The Project Area is very important as it defines the area for your hexagon bins. It may be best to open a new tab with your Search page, make a change here in the Settings, and then refresh your Search page to preview the changes you make.

  3. Change Hexagon Bin Settings

    Finally, you can change the size and precision of the search result hexagon bins. We recommend changing these settings in small increments, as making a small bin size with a large project area (for example) can be costly for your browser and may cause it to crash when loading the Search page.

After getting the Map Settings figured out, you may want to change the name of your app which can be accomplished through the System Settings and changing the index.htm file in your arches_projects folder, or create some Saved Searches to make it easier for the users to explore your database (Saved Searches).

Arches Production Deployment

Changing the Admin Password

The first item of business when preparing your production of Arches is to change the Admin user’s password. You cannot change the Admin user’s password in the Arches UI because the Admin account is not associated with an email. Instead you’ll need to use the Django admin page:

  1. Login as admin to Arches or in the Django admin (http://[your arches domain]/admin/)
  2. Navigate to the Django admin user page http://[your arches domain]/admin/auth/user/.
  3. In the upper right of the page select CHANGE PASSWORD and follow the steps to update the password.
../_images/change-admin-pwd.png

Configuring Captcha

Setting up your captcha will help protect your production from spam and other unwanted bots. To set up your production with captcha, first register your captcha and then add the captcha keys to your project’s settings.py. Do this by adding the following:

RECAPTCHA_PUBLIC_KEY = 'x'
RECAPTCHA_PRIVATE_KEY = 'x'

Replace the x’s with your captcha keys.

User Sign-up

To enable users to sign up through the Arches UI, you will have to add the following lines of code to your project’s settings.py:

EMAIL_USE_TLS = True
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'xxxx@xxx.com'
EMAIL_HOST_PASSWORD = 'xxxxxxx'
EMAIL_PORT = 587

Update the EMAIL_HOST_USER and EMAIL_HOST_PASSWORD with the correct email credentials and save the file. It is possible that this may not be enough to support your production of Arches. In that case, there’s more information on setting up an email backend on the Django site.

To configure what group new users are put into, add the following lines of code to your project’s settings.py:

# group to assign users who self sign up via the web ui
USER_SIGNUP_GROUP = 'Crowdsource Editor'

If you would like to change which group new users are added to, replace ‘Crowdsource Editor’ with the group you would like to use.

Configure Media Directory

The media directory identifies the destination directory of uploaded files. To do so, add the following lines of code to your project’s settings.py file:

# Absolute filesystem path to the directory that will hold user-uploaded files.
MEDIA_ROOT =  os.path.join(ROOT_DIR)

# URL that handles the media served from MEDIA_ROOT, used for managing stored files.
# It must end in a slash if set to a non-empty value.
MEDIA_URL = '/files/'

Replace the ROOT_DIR with the pathway to the folder where you want the directory to be created. For example:

ROOT_DIR = os.path.join('projects','my_project')

Permissions Settings

Permissions allow you to tailor the user experience by letting you control which data a user or group can view and edit. Permissions are applied to each card and by default, the guest users (aka anonymous user) has read privileges to all data. If you have data you do not want to share with all users, simply perform the following steps in the Arches UI:

  1. Navigate to the ‘Resource Models’ tab of the Arches Designer

  2. Select a resource model and click on the Manage button. This will trigger a drop-down menu with a few different managers; select the Permissions Manager.

  3. Be sure to select a user or group within the Group Library and then select a card from the Card Library.

  4. Choose which permissions to grant the user.

    • No Access will deny the user from viewing or editing data in that card.
    • Read permissions allow the user/group to see the data presented in that card, but not edit it.
    • Create/Update allows the user/group to view and edit the data in that card, as well as create new data.
    • Delete permissions allow the user to delete data from the database.
  5. Click on the Apply Permissions button.

Set DEBUG = False

Most importantly, you should never run Arches in production with DEBUG = True. Open your settings.py file (or settings_local.py) and set DEBUG = False (just add that line if necessary).

Turning off the Django debug mode will:

  1. Suppress the verbose Django error messages in favor of a standard 404 or 500 error page.

    You will now find Django error messages printed in your arches.log file.

    Important

    Make sure you have 500.htm and 404.htm files in your project’s templates directory!

  2. Cause Django to stop serving static files.

    You must set up a real webserver, like Apache or Nginx, to serve your app. To help with this, we have created a basic tutorial on how to Serving Arches with Apache.

Full Explanation of the System Settings UI

System Settings

Default Application Settings

  • Application Name - Name of your Arches app, to be displayed in the browser title bar and elsewhere.
  • Default Data Import/Export User - Name to associate with data that is imported into the system.

Web Analytics

If you have made a Google Analytics Key to track your app’s traffic, enter it here.

Thesaurus Service Providers

Advanced users may create more SPAQRL endpoints and register them here. These endpoints will be available in the RDM and allow you to import thesaurus entries from external sources.

Map Settings

Mapbox API

Arches uses the Mapbox mapping library for map display and data creation. Arches also supports Mapbox basemaps and other services.

  • Mapbox API Key (Optional) - By default, Arches uses some basemap web services from Mapbox. You will need to create a free API key (or “access token”) for these services to be activated. Alternatively, you could remove all of the default basemaps and add your own, non-Mapbox layers.
  • Mapbox Sprites - Path to Mapbox sprites (use default).
  • Mapbox Glyphs - Path to Mapbox glyphs (use default).

Project Extent

Draw a polygon representing your project’s extent. These bounds will serve as the default for the cache seed bounds, search result grid bounds, and map bounds in search, cards, and reports.

Map Zoom

You can define the zoom behavior of your maps by specifying max/min and default values. Zoom level 0 shows the whole world (and is the minimum zoom level). Most map services support a maximum of 20 or so zoom levels.

Search Results Grid

Arches aggregates search results and displays them as hexagons. You will need to set default parameters for the hexagon size and precision.

Warning

A large project area combined with a small hexagon size and/or high precision will take a very long time to load, and can crash your browser. We suggest changing these settings in small increments to find the best combination for your project.

Basic Search Settings

Set the default search results behavior. This is also where you will define the max number of resources per export operation.

Temporal Search Settings

Arches creates a Time Wheel based on the resources in your database, to allow for quick temporal visualization and queries. A few aspects of this temporal search are defined here.

  • Color Ramp - Currently unused (saved for future implementation). The color ramp for the time wheel. For further reference, check out the d3 API reference.
  • Time wheel configuration - Currently unused (saved for future implementation). You can, however, modify the time wheel configuration using the advanced settings, Time Wheel Configuration.

Saved Searches

Arches allows you save a search and present it as convenience for your users. Saved Searches appear as search options in the main Search page. Creating a Saved Search is a three-step process.

  1. Specify Search Criteria - Go to the Search page and enter all the criteria you would like to use to configure your Saved Search. You may notice that with the addition of each new search filter (either by using the term filter, map filtering tools, or temporal filters) the URL for the page will change.
  2. Copy the URL - In your browser address bar, copy the entire URL. This will be a long string that defines each of the search filters created in step 1.
  3. Create the Saved Search - Finally, head back to this page and fill out the settings that you see at left. You can also upload an image that will be shown along with your Search Search.

Maintaining UI-Defined Settings

Because these settings are stored in the database, as opposed to a settings.py file, if you drop and recreate your database, you will lose them and need to re-enter them by hand. To avoid this, you should run this command after you have finished configuring settings through the UI:

python manage.py packages -o save_system_settings [-d arches/db/system_settings]

A file named “System_Settings.json” will be saved to the directory indicated. If no directory is indicated the file will be saved to settings.SYSTEM_SETTINGS_LOCAL_PATH, which is my_project/my_project/system_settings/ by default. This same path is used to import settings when a new package is loaded into your project.