FixMyStreet: Platform

Configuration settings

You can control much of how FixMyStreet looks and behaves just by changing the config settings.

The general configuration file

You can look at a summary of the live configuration of your site by going to the Configuration page of your administration interface, at /admin/config.

The FixMyStreet code ships with an example configuration file: conf/general.yml-example.

As part of the installation process, the example file gets copied to conf/general.yml. You must edit this file to suit your needs.

When you edit this file, remember it must be in the YAML syntax. It’s not complicated but — especially if you’re editing a list — be careful to get the indentation correct. If in doubt, look at the examples already in the file, and don’t use tabs.

Config settings by topic

The following are all the configuration settings that you can change in conf/general.yml.

Database config

Site settings and behaviour

URLs and directories

Photo storage

Emailing

Login methods, authentication

Staging site (not production) behaviour

MapIt (admin boundary service)

Localisation and maps

Sundry external services

All the general settings

FMS_DB_HOST, FMS_DB_PORT, FMS_DB_NAME, FMS_DB_USER, FMS_DB_PASS & FMS_DB_SSLMODE
These are the PostgreSQL database details for FixMyStreet.

Example:

  • FMS_DB_HOST: 'localhost'
    FMS_DB_PORT: '5432'
    FMS_DB_NAME: 'fms'
    FMS_DB_USER: 'fmsuser'
    FMS_DB_PASS: 'aSecretWord' FMS_DB_SSLMODE: 'require'
BASE_URL
The base URL of your site.

Examples:

  • BASE_URL: 'http://www.example.org'

  • Use this if you're using the Catalyst development server:

    BASE_URL: 'http://localhost:3000'
SECURE_PROXY_SSL_HEADER
If you are behind a proxy that is performing SSL termination, and so FixMyStreet is e.g. responding locally on a non-HTTPS connection, then you need to make your proxy set a custom HTTP header saying that the request was via HTTPS, and then set this value to a two-element list containing the trusted HTTP header and the required value.

Example:

  • SECURE_PROXY_SSL_HEADER: [ 'X-Forwarded-Proto', 'https' ]
CONTENT_SECURITY_POLICY
A Content-Security-Policy header can prevent cross-site scripting, clickjacking and other code injection attacks (see Wikipedia for more). To have FixMyStreet output such a header, set this setting to 1. If you load third-party JavaScript on your site, you will need to set this setting to a space-separated list of domains; whatever is here, if not 1, will be included in the header output.

Example:

  • CONTENT_SECURITY_POLICY: 1
  • CONTENT_SECURITY_POLICY: 'www.example.org other.example.org'
  • CONTENT_SECURITY_POLICY: [ 'www.example.org', 'other.example.org' ]
EMAIL_DOMAIN, CONTACT_EMAIL & CONTACT_NAME
The email domain used for emails, and the contact name and email for admin use.

Example:

  • EMAIL_DOMAIN: 'example.org'
    CONTACT_EMAIL: 'team@example.org'
    CONTACT_NAME: 'FixMyStreet team'
DO_NOT_REPLY_EMAIL
The address used for emails you don't expect a reply to (for example, confirmation emails). This can be the same as CONTACT_EMAIL, of course, if you don't have a special address.

Example:

  • DO_NOT_REPLY_EMAIL: 'do-not-reply@example.org'
STAGING_SITE
Is this site a staging (or development) site?

On a staging site, templates/CSS modified times aren't cached. Staging sites also don't send reports to bodies unless explicitly configured to (see STAGING_FLAGS) — this means you can easily test your site without really sending emails to the bodies' contacts that may be in your database.

Example:

  • If this is your live production server:

    STAGING_SITE: 0

  • If this is a development or staging server:

    STAGING_SITE: 1

STAGING_FLAGS

A variety of flags that change the behaviour of a site when STAGING_SITE is 1.

Setting send_reports to 0 will send reports to the reporter instead of the relevant body's contact address.

Setting skip_checks to 1 will stop cobrands from performing some checks such as the map pin location being within their covered area, which makes testing multiple cobrands much easier.

Setting hide_staging_banner to 1 will hide the red “Staging site” banner in the top left corner of the site.

enable_appcache lets you say whether the appcache should be active or not.

Note that this setting is only relevant on a staging server. On your production server (where STAGING_SITE is 0) it will be ignored.

Example:

STAGING_FLAGS:
  send_reports: 0
  skip_checks: 1
  hide_staging_banner: 1

Any reports created will now be sent to the email of the reporter and not the body's; and any location checks are skipped. Great for testing!

EXAMPLE_PLACES
The suggested input for a place name or names. By default, this appears as a placeholder in the text input on FixMyStreet's front page, and in alert emails. It defaults to displaying "High Street, Main Street".

You should ensure that the example places do return clear, relevant results if they're entered in the font page text input — this will probably depend on how you've set GEOCODING_DISAMBIGUATION.

Example:

  • The default behaviour is this, which you should certainly change:

    EXAMPLE_PLACES: [ 'High Street', 'Main Street' ]

  • EXAMPLE_PLACES: [ 'Iffley Road', 'Park St, Woodstock' ]
LANGUAGES
An array of languages the site supports, each in the following format:

<language code>,<pretty name>,<locale>

Some important things to note:

  • Put the default language as the first entry in the list.
  • Don't put any extra spaces in the strings (e.g., after the commas).
  • Remember that if you want your site to run in languages other than English, you'll also need to check that the translations are available, and your system supports the appropriate locales.

Just adding a language here does not necessarily mean FixMyStreet will always use it (for example, a language coded subdomain name or browser preference may be considered). See this page about languages and FixMyStreet for more information.

Example:

  • LANGUAGES:
  - 'en-gb,English,en_GB'

  • LANGUAGES:
  - 'de,German,de_DE'
  - 'en-gb,English,en_GB'
TIME_ZONE
If you're running an installation that is being used in a different time zone from the server, set the time zone here. Use a standard time zone (TZ) string.

Example:

  • TIME_ZONE: 'Asia/Manila'
  • Leave the setting blank to use your server's default:

    TIME_ZONE: ''

GEO_CACHE
The file location for cached geocoding results. Normally you don't need to change this setting from the example.

Example:

  • GEO_CACHE: '../cache/'
FACEBOOK_APP_ID & FACEBOOK_APP_SECRET
If these parameters are set to a Facebook App's ID and secret, then a user will be able to log in using their Facebook account when reporting, updating, or logging in. More details
TWITTER_KEY & TWITTER_SECRET
If these parameters are set to a Twitter App's key and secret, then a user will be able to log in using their Twitter account when reporting, updating, or logging in. More details
SMS_AUTHENTICATION
Set this to 1 if you wish people to be able to use their mobiles as login identifiers, receiving confirmation codes by text to report, update or login in a similar way to how they receive a link in a confirmation email. More details
PHONE_COUNTRY
Set this to the country code of where you are operating the site, so that phone number parsing knows how to deal with national phone numbers entered.
TWILIO_ACCOUNT_SID & TWILIO_AUTH_TOKEN
These are your Twilio account details to use for sending text messages for report and update verification. See the Twilio docs for more information.
TWILIO_FROM_PARAMETER
This is the phone number or alphanumeric string to use as the From of any sent text messages. You must specify either this or TWILIO_MESSAGING_SERVICE_SID. See the Twilio docs for more information.
TWILIO_MESSAGING_SERVICE_SID
This is the unique id of the Twilio Messaging Service you want to associate with this message. You must specify either this or TWILIO_FROM_PARAMETER. See the Twilio docs for more information.
LOGIN_REQUIRED
If you're running an installation that should only be accessible to logged in people, set this variable.

Example:

  • LOGIN_REQUIRED: 1
SIGNUPS_DISABLED
If you don't want any new people to be able to use the site, only the users you have already created, then set this variable.

Example:

  • SIGNUPS_DISABLED: 1
MAPIT_URL, MAPIT_TYPES, MAPIT_API_KEY
FixMyStreet uses the external service MapIt to map locations (points) to administrative areas: see this explanation of MapIt.

You must provide the URL of a MapIt server, and nominate what types of area from it you want to use. If you leave this blank, a default area will be used everywhere (a URL needs to be given for non-web things, like sending of reports, to function). If the MapIt you are using requires an API key, you can provide one.

See also MAPIT_ID_WHITELIST to efficiently limit the areas you need (especially if you're using global MapIt).

Example:

  • If using the Catalyst development server, set to:

    MAPIT_URL: 'http://localhost:3000/fakemapit/'
    MAPIT_TYPES: [ 'ZZZ' ]

  • In the UK, you probably want, to cover all councils:

    MAPIT_URL: 'https://mapit.mysociety.org/'
    MAPIT_API_KEY: '12345'
    MAPIT_TYPES: [ 'DIS', 'LBO', 'MTD', 'UTA', 'CTY', 'COI', 'LGD' ]

    ...but perhaps MAPIT_TYPES: [ 'WMC' ] if you want to report on a per-constituency basis?

  • If our global MapIt (which is loaded with OpenStreetMap data) contains boundaries you can use:

    MAPIT_URL: 'http://global.mapit.mysociety.org/'

    And then specify whichever type code have the boundaries you want:

    MAPIT_TYPES: [ 'O06' ]

    OSM type codes consist of the letter O followed by two digits indicating the type of boundary. Typically, the higher the number, the more specfic (localised) the boundary type.

MAPIT_ID_WHITELIST
If you are using global MapIt (see MAPIT_URL), you might want to restrict FixMyStreet usage to only one or more areas, rather than all areas of the specified type (afer all, there are a lot of O04 boundaries in the whole world, for example). Provide a list of all the MapIt IDs that your FixMyStreet should recognise.

Note that you must still set MAPIT_TYPES to match the type or types of each of these areas. And we recommend you set MAPIT_GENERATION too.

We recommend you use this setting, because doing so can improves the efficiency of your site's calls to MapIt considerably.

Examples:

  • If you don't specify a whitelist, all results (of the given area type) will be considered. This may be OK if you're using a MapIt server which is already only returning relevant results.

    MAPIT_ID_WHITELIST: []

  • Otherwise, explicitly list the IDs (from the MapIt server you're using) of the areas you're interested in:

    MAPIT_ID_WHITELIST: [ 240838, 246176, 246733 ]

MAPIT_GENERATION
If you have set MAPIT_ID_WHITELIST, then you should also specify the generation of MapIt data you are using, especially if you are using our global MapIt service.

Global MapIt uses OpenStreetMap data. From time to time we import the latest data in order to pull in newly-added boundaries, or reflect changes to existing ones. When this happens, the area IDs may change, which means the values in your MAPIT_ID_WHITELIST might no longer be correct (because, by default, MapIt returns values from the latest generation of data). Use the MAPIT_GENERATION setting to lock the area IDs in your whitelist — and the geometry described by their boundary data — to the specific generation they belong to. MapIt's generations are numbered with an integer that we increment with each update.

To determine the generation of the data you're using, when you initially identify the area IDs look at the generation-high and generation-low values MapIt is returning. For example, here's the global MapIt data for a point within Thailand — the national border for Thailand is the top level returned ("OSM Administrative Boundary Level 2"). Look on that page for "Exists in generations" (or "generation-" in the JSON data, available by changing MapIt's .html URL to .json) to see the range of generations in which this area appears. You should probably use the highest number (that is, the most recent update).

Examples:

  • In this example, the whitelist contains a single area ID from global MapIt's generation 4 for Thailand's national border (hence 507455 and area type O02): 
    MAPIT_URL: http://global.mapit.mysociety.org/
MAPIT_TYPES: ['O02']
MAPIT_ID_WHITELIST: [507455]
MAPIT_ID_GENERATION: 4
  • If you're not using a MAPIT_ID_WHITELIST you usually don't need to specify a MAPIT_ID_GENERATION.
MAPIT_TYPES_CHILDREN
If your MapIt has the concept of council wards (subareas of councils, where people can sign up for alerts, but not report things), then you can give the MapIt type codes for them here.

You can leave this blank if your jurisidction doesn't use subareas.

Example:

  • It's OK to leave this setting blank:

    MAPIT_TYPES_CHILDREN: ''

  • In the UK we use something like:

    MAPIT_TYPES_CHILDREN: [ 'DIW', 'LBW', 'MTW', 'UTE', 'UTW', 'CED', 'COP', 'LGW' ]

GEOCODER
Which geocoder service to use to look up results, for example, from front page "Enter your location" searches.

Possible choices are Google, Bing, or OSM. By default, FixMyStreet will use OSM, the OpenStreetMap geocoder.

For more information, see the page about geocoding.

It's also possible to add a new geocoder (for example, if your jurisdiction provides a custom one). This requires some coding work, but you can see exampes of supported geocoders in the FixMyStreet repo.

Whichever geocoder you use, check the terms of use for it — there may be restrictions. You may also need to provide an API key to use it: see GOOGLE_MAPS_API_KEY and BING_MAPS_API_KEY.

See also GEOCODING_DISAMBIGUATION for restricting geocoder service to specific places.

Example:

  • FixMyStreet defaults to OSM if you don't specify a geocoder:

    GEOCODER: ''

  • GEOCODER: 'Bing'
GOOGLE_MAPS_API_KEY & BING_MAPS_API_KEY
If you wish to use Google Maps or Bing Maps Geocoding, get the relevant key and set it here. See also the GEOCODER setting.

Example:

  • GOOGLE_MAPS_API_KEY: ''
    BING_MAPS_API_KEY: ''
GEOCODING_DISAMBIGUATION
This setting provides parameters that are included in geocoding requests, to hopefully return more useful results. The options that will be applied vary depending on which geocoder you are using (although unwanted options will be ignored, so you can specify all of them, which might be convenient if you change geocoder).

Remember that you specify which geocoder you are using with the GEOCODER setting.

For OSM, which is the default, you can use: 

GEOCODING_DISAMBIGUATION:
  bounds: [ <min lat>, <min lon>, <max lat>, <max lon> ]
  country: <country code to restrict results to>
  town: <string added to geocoding requests if not already there>

If using Bing, you can use town and bounds, plus any of: 

  centre: "<lat><lon>"
  bing_culture: <culture code: see Bing docs>
  bing_country: <country name: only accept results that match this>

If using Google, you can use: 

  bounds: [ <min lat>, <min lon>, <max lat>, <max lon> ]
  google_country: <.ccTLD to restrict results to>
  lang: <language for results>

Example:

  • This limits geocoding requests to only return results in Mumbai, India: 
              
GEOCODER: 'OSM'
GEOCODING_DISAMBIGUATION:
  country: 'in'
  town: 'Mumbai'
MAP_TYPE
The type of map you want to use. If left blank, the default is OSM for OpenStreetMap. Other options are GoogleOL for Google Open Layers, and other UK-specific values, including FMS for UK FixMyStreet.

Check the usage terms for the type of map you use — there may be restrictions.

Example:

  • MAP_TYPE: 'OSM'
ALLOWED_COBRANDS
FixMyStreet uses a templating cobrand system to provide different looks (and behaviour) for different installations. For example, if you create a cobrand called moon, then FixMyStreet will look for templates in the templates/web/moon directory and CSS in web/cobrands/moon. To make this work, set: 
ALLOWED_COBRANDS:
  - moon

If you specify only one cobrand in this way, your FixMyStreet site will simply run using that cobrand (so that would be moon in the example above). This is probably all you need!

However, it is possible for a FixMyStreet site to support more than one cobrand at the same time. Most installations don't need this, but if yours does, it's very useful: the server decides which cobrand to use by inspecting the hostname of the incoming request.

If you wish to use multiple cobrands, specify them in a list, optionally with hostname-matching regular expressions if the name of the cobrand is not enough. If the hostname of the current request does not match with any in the list, FixMyStreet will use the Default cobrand. For example: 

ALLOWED_COBRANDS:
  - moon
  - venus

Any hostname with "moon" in it will use the moon cobrand (for example, fixmymoon.org), any with "venus" will use the venus cobrand. Anything else (such as www.example.com, which contains neither "moon" nor "venus") will use the Default cobrand.

Instead of using the cobrand's name as the matching string, you can specify an alternative string to match on (in fact, the string can be a regular expression): 

ALLOWED_COBRANDS:
  - moon: 'orbital'
  - venus

Here, any hostname with "orbital" in it will use the moon cobrand. Conversely, a request to www.fixmymoon.org won't match anything, so it would be served with the Default cobrand instead. This also allows development servers to map to different cobrands if needed, using DNS subdomains, for example.

If you're running a site with multiple cobrands, you'll never want to serve the Default cobrand on your production server, so make sure you've set ALLOWED_COBRANDS correctly.

Examples:

  • Note that specifying a single allowed cobrand is a special, simple case: FixMyStreet will always use the mycobrand. This is probably all you need! 

    ALLOWED_COBRANDS:
  - mycobrand

  • If there's more than one allowed cobrand, FixMyStreet uses string matching (described above) on the hostname to determine which one to use: 

    ALLOWED_COBRANDS:
  - cobrand1
  - cobrand2: 'hostname_substring2'
  - cobrand3

    Make sure you've covered everything, because any requests to a hostname that don't match will be served using the Default cobrand, which isn't what you want.

ADMIN_BASE_URL
This is used in "offensive report" emails to provide a link directly to the admin interface, and to make sure the admin can work through a proxy. It defaults to `/admin` in your installation.

Example:

  • ADMIN_BASE_URL: ''
RSS_LIMIT
How many items are returned in the GeoRSS feeds?

Example:

  • RSS_LIMIT: '20'
OPEN311_LIMIT
How many items are returned by default in an Open311 response?

Example:

  • OPEN311_LIMIT: 100
ALL_REPORTS_PER_PAGE
How many reports to show per page on the All Reports pages?

Example:

  • ALL_REPORTS_PER_PAGE: 100
SMTP_SMARTHOST
The default SMTP smarthost is localhost, a mail server on the same machine you are running FixMyStreet. If you wish to send email through a SMTP server elsewhere, change this and the other SMTP settings.

Example:

  • SMTP_SMARTHOST: 'localhost'
SMTP_TYPE
If your SMTP server supports SSL or TLS, set this variable to 'ssl' or 'tls', otherwise leave it as '' for unencrypted SMTP.
SMTP_PORT
The default SMTP port is 25 for unencrypted, 465 for SSL and 587 for TLS. Leave as '' to use the default, otherwise set to your SMTP server port.
SMTP_USERNAME
The username for authenticating with your SMTP server, if required.
SMTP_PASSWORD
The password for authenticating with your SMTP server, if required.
AREA_LINKS_FROM_PROBLEMS
Should problem reports link to the council summary pages? Set to 0 to disable, or 1 to enable.

Example:

  • Disable links to the summary page:

    AREA_LINKS_FROM_PROBLEMS: '0'

CACHE_TIMEOUT
The time, in seconds, that the front page stats/recent list should be cached for. Also used for the max-age of /reports. Defaults to 3600s (1 hour).
GAZE_URL
Gaze is a world-wide service for population density lookups. You can leave this as is. It is used to provide the default radius for email/RSS alerts and to set the default zoom level on a map page (so in rural areas, you're more likely to get a slightly more zoomed out map).

Example:

  • GAZE_URL: 'https://gaze.mysociety.org/gaze'
MESSAGE_MANAGER_URL
If you're using Message Manager, integrated with an SMS gateway, include the URL here. FixMyStreet does not usually use this, so you can leave it blank.

Providing a URL does not automatically enable the service — your cobrand must be explicitly coded to use it. Contact us if you need to use Message Manager with your FixMyStreet site.

Example:

  • MESSAGE_MANAGER_URL: ''
PHOTO_STORAGE_BACKEND
The storage backend to use for uploaded photos.

Possible choices are FileSystem or S3. By default, FixMyStreet will use FileSystem.

The chosen backend can be configured via the PHOTO_STORAGE_OPTIONS setting, see below.

PHOTO_STORAGE_OPTIONS

Contains backend-specific configuration options for photo storage.

For the FileSystem backend, the following apply:

For the S3 backend, the following apply:

UPLOAD_DIR

The file location for uploaded photos. Normally you don't need to change this setting from the example.

Only applies when PHOTO_STORAGE_BACKEND is FileSystem.

Example:

  • PHOTO_STORAGE_OPTIONS:
  UPLOAD_DIR: '../upload/'
SYMLINK_FULL_SIZE

Defaults to false; if this is true, then requests for full size images will be symlinked from the photo cache, not copied there. You can use this if static files are being served by your web server.

Only applies when PHOTO_STORAGE_BACKEND is FileSystem.

BUCKET

The name of the S3 bucket to store photos in.

Required when PHOTO_STORAGE_BACKEND is S3.

Example:

  • PHOTO_STORAGE_OPTIONS:
  BUCKET: 'fixmystreet-photos'
ACCESS_KEY & SECRET_KEY

The AWS access & secret keys to use when connecting to S3. You should use a role with minimal privileges to manage objects in a specific S3 bucket, not your root keys.

Required when PHOTO_STORAGE_BACKEND is S3.

Example:

  • PHOTO_STORAGE_OPTIONS:
  ACCESS_KEY: 'AKIAMYSUPERCOOLKEY'
  SECRET_KEY: '12345/AbCdEFgHIJ98765'
PREFIX

An optional directory prefix to prepended to S3 filenames. Useful if, for example, you are using a bucket shared between other projects or FixMyStreet instances.

Optional. Only applies when PHOTO_STORAGE_BACKEND is S3.

Example:

  • PHOTO_STORAGE_OPTIONS:
  PREFIX: '/fixmystreet_photos/'
CREATE_BUCKET

Set to 1 (or true) if FixMyStreet should create the S3 bucket specified in BUCKET if it doesn't already exist.

Optional. Only applies when PHOTO_STORAGE_BACKEND is S3.

REGION

The AWS region to create the S3 bucket in.

Optional. Only applies when CREATE_BUCKET is enabled.

Example:

  • PHOTO_STORAGE_OPTIONS:
  CREATE_BUCKET: 1
  REGION: 'eu-west-2'