Configuring OpenBlock¶
You should have a look at ebpub/ebpub/settings_default.py
. It
contains many comments about the purpose and possible values of the
various settings expected by OpenBlock.
A few items are worth special mention.
Sensitive Settings¶
These are settings you must customize, and avoid putting in a public place eg. a public version control system.
PASSWORD_CREATE_SALT
- this is used when users create a new account.PASSWORD_RESET_SALT
- this is used when users reset their passwords.STAFF_COOKIE_NAME
andSTAFF_COOKIE_VALUE
- this is used for allowing staff members to see some parts of the site that other users cannot, such as types of news items that you're still working on.
Choosing Your Map Base Layer¶
If you don't like the look of OpenBlock's default maps, you have many options for your base layer - the tiled images that give your map its street lines, geographic features, place names, etc.
Default: OpenStreetMap tiles hosted by OpenGeo¶
This is the default setting in ebpub/ebpub/settings_default.py
. It
is a fairly clean design inspired by everyblock.com, and was derived
from OpenStreetMap data. It is free for use for any purpose, but note
that there have been some reliability issues with this server in the
past.
Other Publicly Available Layers¶
It's easy to use any base layer supported by olwidget. More specifically:
Google Maps¶
If your intended usage on your website meets Google's Terms of Service, or if you have a Premier account, you may be able to use Google Maps for your base layer.
In your settings.py, set MAP_BASELAYER_TYPE
to any of
'google.streets', 'google.physical', 'google.satellite', or 'google.hybrid'.
Then be sure to get an API key from Google and put it in your settings
file as GOOGLE_API_KEY
.
Open Street Map¶
Set MAP_BASELAYER_TYPE
to either 'osm.mapnik' or 'osm.osmarender'.
Microsoft VirtualEarth / Bing Maps¶
Set MAP_BASELAYER_TYPE
to any of 've.road', 've.shaded',
've.aerial', or 've.hybrid'.
Yahoo Maps¶
Set MAP_BASELAYER_TYPE = 'yahoo'
and be sure to set YAHOO_APP_ID
to your Yahoo app id.
Other public WMS servers¶
Set MAP_BASELAYER_TYPE
to either 'wms.map' (not very useful for
OpenBlock) or 'wms.nasa'.
CloudMade¶
Cloudmade hosts a lot of community-designed map base layers. You can even design your own online using their tools.
Get an API key from them and put it in your settings as
CLOUDMADE_API_KEY
. Then set MAP_BASELAYER_TYPE = 'cloudmade.<num>'
(where <num> is the number for a cloudmade style).
For example, 'cloudmade.998'.
To find interesting cloudmade style numbers, browse at http://maps.cloudmade.com/editor ; the style number is at bottom right of each style.
Blank (no base layer)¶
Try MAP_BASELAYER_TYPE = 'wms.blank'
Custom or Other Base Layers¶
Do you have your own tile server running, or have a URL to something else not in the above list? Great! You can use that with a few extra settings. This option takes a little more work; you will have to know which OpenLayers layer subclass is appropriate, and what parameters to pass to it.
In fact, this is how our default OpenGeo / OpenStreetMap layer is configured, so let's use that as an example:
MAP_BASELAYER_TYPE = 'custom.opengeo_osm'
MAP_CUSTOM_BASE_LAYERS = {
'opengeo_osm': # to use this, set MAP_BASELAYER_TYPE='custom.opengeo_osm'
{"class": "WMS", # The OpenLayers.Layer subclass to use.
"args": [ # These are passed as arguments to the constructor.
"OpenStreetMap (OpenGeo)",
"http://maps.opengeo.org/geowebcache/service/wms",
{"layers": "openstreetmap",
"format": "image/png",
"bgcolor": "#A1BDC4",
},
{"wrapDateLine": True
},
],
}
}
Multiple databases?¶
Note that while Django supports using multiple databases for different model data, OpenBlock does not. This is because we use South to automate database migrations, and as of this writing South does not work properly with a multi-database configuration.
Configuring Cities / Towns: METRO_LIST¶
If you look at obdemo/obdemo/settings.py.in
, or at the
settings.py
that is generated when you start a custom app, you will notice it contains a list named METRO_LIST
.
This list will (almost) always contain only one item, a dictionary with configuration about your local region.
Most of the items in this dictionary are fairly self explanatory. Here's an example for Boston:
METRO_LIST = [
{
# Extent of the metro, as a longitude/latitude bounding box.
'extent': (-71.191153, 42.227865, -70.986487, 42.396978),
# Whether this area should be displayed to the public.
'is_public': True,
# Set this to True if the region has multiple cities.
'multiple_cities': False,
# The major city in the region.
'city_name': 'Boston',
# The SHORT_NAME in the settings file.
'short_name': SHORT_NAME,
# The name of the metro or region, as opposed to the city (e.g., "Miami-Dade" instead of "Miami").
'metro_name': 'Boston',
# USPS abbreviation for the state.
'state': 'MA',
# Full name of state.
'state_name': 'Massachusetts',
# Time zone, as required by Django's TIME_ZONE setting.
'time_zone': 'America/New_York',
# Only needed if multiple_cities = True.
'city_location_type': 'city',
},
]
More information on a few of these follows.
short_name¶
This is how OpenBlock knows which dictionary in METRO_LIST
to use.
It must exactly match the value of settings.SHORT_NAME
.
extent¶
This is a list of (leftmost longitude, lower latitude, rightmost longitude, upper latitude).
One way to find these coordinates would be to use Google Maps to zoom to your region, then point at the lower left corner of your area, right-click, and select "Drop LatLng Marker". You will see a marker that displays the latitude,longitude of that point on the map. Then do the same in the upper right corner.
This defines a bounding box - the range of latitudes and longitudes that are relevant to your area. It is used in many views as the default bounding box when searching for relevant NewsItems. It is also used by some data-loading scripts to filter out data that's not relevant to your area.
multiple_cities¶
Set multiple_cities
to True
if you want one OpenBlock site to serve
multiple cities or towns in the same region.
For example, you might be setting it up for a county. In this example
you could use the county name for city_name
and metro_name
. Or
you might be somewhere like the San Francisco Bay Area and wanting to
include San Francisco, Oakland, Berkeley, and so on. So city_name
might be 'San Francisco' and metro_name
might be something like
'Bay Area'.
If multiple_cities
is True, you must also set
city_location_type
, see below.
This option affects numerous URLs on the site; users will be able to
browse first by city, then by street, then by block, and so on.
If it's False
, the city browsing page will be left out of the site
structure.
city_location_type¶
You only need this if multiple_cities
is True. In that case you
will need to create a LocationType for cities,
and city_location_type
should be set to that LocationType
's slug.
You will then want to create a Location
for each city in your
region. See Loading Location Data for more.
When would you put more than one dictionary in METRO_LIST?¶
The only dictionary in METRO_LIST
that has any effect is the one whose
short_name
matches settings.SHORT_NAME.
The purpose of having more than one metro dictionary in METRO_LIST
would be to run multiple OpenBlock sites for multiple metro areas with
some shared configuration. You are probably not doing this.
The idea is that you could have one settings file containing the master
METRO_LIST
, and then for each site you'd have its own settings
file that imports METRO_LIST
(and any other shared stuff you like)
from the master settings file. Each site-specific settings file would also set
settings.SHORT_NAME
to match the 'short_name'
key of one of
the dictionaries.
Most people will probably not be doing that. This feature serves the needs of everyblock.com, which runs separate sites for many cities across the USA.
Email¶
OpenBlock uses email for two things: account confirmation, and alerts to which users can subscribe in order to get notified when news happens in their neighborhood or other area of interest.
OpenBlock is configured like any other Django application
.
In your settings.py
, you'll want to set these:
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST='localhost'
EMAIL_PORT='25'
# If your email host needs authentication, set these.
#EMAIL_HOST_USER=''
#EMAIL_HOST_PASSWORD=''
#EMAIL_USE_TLS=False # For secure SMTP connections.
# This is used as "From:" in emails sent to users.
GENERIC_EMAIL_SENDER = 'admin@example.com'
Don't have an SMTP Server?¶
You may be able to use an appropriate account on Gmail or another public mail service. See for example this blog post).
Email on AWS EC2
If you are installing on amazon's EC2 servers, note that you must use a different server to send mail, as Amazon limits the amount of mail you can send, and most ISPs will block it as likely spam anyway. So use another service such as Gmail as per the previous paragraph, or you might try Amazon's own email service: https://aws.amazon.com/ses/
OpenBlock REST API¶
MAX_KEYS_PER_USER
-- how many API keys each OpenBlock user can register.
Default 1.
API_THROTTLE_TIMEFRAME
, API_THROTTLE_AT
-- Together these
control how many API requests a user or API key can make in certain
period of time. If the user makes more than API_THROTTLE_AT
requests within a period of API_THROTTLE_TIMEFRAME
seconds, then
all further requests will be denied until another API_THROTTLE_TIMEFRAME
seconds have passed.
API_THROTTLE_EXPIRATION
-- How long to keep track of last access
times per user. This is just for housekeeping, in practice it doesn't
affect your users.
Enable caching too!
In order to enable throttling, you MUST also configure CACHES['default'] to something other than a DummyCache, as per the DJango caching documentation.
Django-Static¶
OpenBlock currently uses Django-Static to manage static media such as Javascript and CSS files. The advantage over Django's built-in "StaticFiles" app is that Django-Static automatically handles timestamping media URLs and minify-ing scripts. With eg. a suitable Apache config, you can safely set far-future expiration dates and never have stale scripts.
The relevant settings are DJANGO_STATIC
, DJANGO_STATIC_MEDIA_ROOTS
,
DJANGO_STATIC_NAME_PREFIX
, DJANGO_STATIC_SAVE_PREFIX
.
All have sensible defaults in ebpub/settings_default.py.
If you need to override them, see
the README.
Note there are some exceptions: we don't use django-static for either JQuery or OpenLayers because you might want to use hosted versions of those, and django-static probably isn't the best way to minify large frameworks anyway.
Django Background Tasks¶
For long-running jobs, we currently use
django-background-task.
This is currently used only by some data loading pages in the admin
UI. The relevant settings are MAX_RUN_TIME
and MAX_ATTEMPTS
.
See the README
for more information.
Miscellaneous Settings¶
AUTH_PROFILE_MODULE
-- A module and class name to use for user
profile data. Default is "preferences.Profile", you can override this
if you want to do something custom, but may require diving in to the
code to understand what assumptions we make about profiles.
DEFAULT_DAYS
-- How many days of news to show on many views.
DEFAULT_LOCTYPE_SLUG
-- Which LocationType to show on the /locations page.
Once you've created some LocationTypes,
this should be set to the slug of your preferred LocationType
.
DEFAULT_MAP_CENTER_LAT
, DEFAULT_MAP_CENTER_LON
,
DEFAULT_MAP_ZOOM
-- Where to center citywide maps by default,
eg. on the home page.
EBPUB_CACHE_GEOCODER
-- True by default; this caches geocoding
results in the database, which makes geocoding faster, but
debugging harder, and can add a bit to the size of database.
EB_DOMAIN
-- The domain used for the root of some generated
URLs, eg. in feeds, widgets, and generated emails.
EB_MEDIA_ROOT
-- Directory that's the root of ebpub's static media files.
By default this is calculated from the location of the installed ebpub
package.
HTTP_CACHE
-- Cache directory used by scrapers when fetching data
from remote sites. By default this goes in a subdirectory of '/tmp'.
NEIGHBORNEWS_USE_CAPTCHA
-- Whether to put a ReCaptcha form on
the forms for adding user-contributed news. Only relevant if
ebpub.neighbornews
is in settings.INSTALLED_APPS
.
This can be True, False, or a function that takes a "request" argument
and returns True or False. You'll also need to acquire API keys from
recaptcha.org and set them as
RECAPTCHA_PUBLIC_KEY
and RECAPTCHA_PRIVATE_KEY
.
JQUERY_URL
-- URL where our version of JQuery lives. Default is a
hosted version.
OPENLAYERS_URL
-- URL where our version of OpenLayers
lives. Default is currently OpenLayers 2.11, hosted locally.
OPENLAYERS_IMG_PATH
-- URL where OpenLayers images are found.
SCRAPER_LOGFILE_NAME
-- Where scrapers
should log their output.
SCRAPER_LOG_DO_EMAIL_ERRORS
-- Whether scrapers
should log their output.
SHORT_NAME
-- The short name for your city, in lowercase,
eg. "chicago". This is used mainly for determining the default metro
(see Configuring Cities / Towns: METRO_LIST), which is used through the OpenBlock code.