Customising checklist

Every time we help set up a new, custom FixMyStreet site, we follow the same basic process to make sure all the key things get done. We've listed the steps here so you can follow them too.

Checklist: 13 things to do

To create a custom FixMyStreet installation, these are the key things you need to do. You don’t have to do them exactly in this order – some can be done at the same time as others – but if you’re not sure then just work through the list.

Pick a name

You need a name for your cobrand right at the start because that's the name you'll use for the directories where your own resources and templates go.

Your name needs to be unique (that is, no other FixMyStreet cobrands are already using it), suitable as a directory name (so no punctuation), and ideally related to the domain name you're going to use for it (although this isn't 100% obligatory).

For example, if your project is called FixMyPark, the cobrand name will be fixmypark.

Set up the domain name

If you're hosting the site yourself and you already own the domain name, you're good to go. But if this is a new project and you don't have the domain set up already, don't leave it too late to register the domain and point it at your server.

If we're hosting the site for you, it's usually easiest if you use a subdomain, and CNAME that onto our server.

Translate into language(s) you need

If FixMyStreet doesn't already have translations for the language(s) you need, you can start work on that right away — see more about languages.

Install the software on the server

There are several different ways of doing this — see installation instructions.

Even if you're not hosting the site yourself, you might want to install the software in order to see how your customisation looks before putting it live. If we're hosting it, we might be able to do this for you.

Secure access to the admin

Make sure you're being challenged to provide a username and password when accessing the admin at /admin.

Typically this means using creating a superuser. If you've not already done so, run the `bin/createsuperuser` script to create a user that has access to the admin.

Change the colour scheme

See changing colour and CSS for detailed instructions.

You can just change the colour variables without needing to touch any other CSS.

Change the logo

You'll need an understanding of CSS in order to change the logo — it's optimised in the FixMyStreet design for good perfomance on old or narrow clients, which makes it a little bit more difficult than just dropping in a graphics file.

We'll be adding instructions later, but meanwhile see the page about changing the CSS.

Write your own FAQ

You almost certainly need to re-write the FAQ and other information pages to match your project.

To do this, copy the template files into your own cobrand's directory and rewrite them. The generic base FAQ can be found at templates/web/base/about/faq-en-gb.html

See more about templates.

Limit geocoder lookups to your area

When someone enters a place name, you only want your FixMyStreet to look for it in the place your site covers. This is controlled by the GEOCODING_DISAMBIGUATION setting. See more about the geocoder.

We've listed this separately from the other config settings because it may take a little bit of testing to see what options work best — this depends on which geocoder you are using.

Configure your admin boundaries (MapIt)

You need to decide what kind of boundary data you'll be using — see more about boundaries.

As part of that work, you'll need to set MAPIT_URL and the other MapIt config settings to match the service you're using.

Set non-default config settings

Many of the configuration settings can be left with their defaults, but some you must change.

As well as system settings (for example, FMS_DB_NAME), every new site needs custom EMAIL_DOMAIN and EXAMPLE_PLACES settings. Make sure the example places you choose really do work if you enter them as the location on the front page.

Even though your site might work with other settings left as defaults, you should go through the whole cong/general.yml file to check everything is how you want it.

Create the bodies (authorities, councils)

Once your site is running log into the admin and add the bodies.

You should have set up the admin boundaries by this stage, because you need to associate each body with the area it covers. For more information, see how FixMyStreet uses MapIt.

Add category names & contact emails

Once you've created the bodies to whom reports will be sent, you can add their problem categories (for example, "Potholes", "Streetlights"). At the same time, add the contact email addresses for each one — see more about contacts and categories.

Further customisation

Remember that this just covers the key parts of a custom installation. There’s a lot more you can change — for example, you can write custom Perl code for the Cobrand module if you want to override specific behaviour not covered by config variables.