Installing and running Indigo

This guide is for developers who want to install and run their own instance of the Indigo platform.

Indigo is a Django web application that can be run as a standalone project, or as part of an existing Django project. This guide will explain how to run Indigo as a standalone project.


Indigo requires:

  • Python 3.8+

  • PostgreSQL 9.3+

  • An AWS S3 account and bucket for storing attachments

  • Apache FOP 2.4+ for generating PDFs

  • pdftotext for reading PDFs

Optional but useful:

  • An SMTP server to send email through, or an appropriate service

Using Heroku/Dokku means that we’re using well-document and widely understood mechanisms for specifying dependencies and configuration across multiple languages. It takes care of all this for you and we highly recommend using them.

Installing Indigo locally

  1. Ensure you have Python 3.8+ installed

  2. Clone the repository. It has all Indigo’s dependencies for Python described in it:

    $ git clone
    $ cd indigo
  3. Setup and activate the virtual environment:

    $ python3 -m venv env
    $ source env/bin/activate
  4. Install Python dependencies. It is recommended to install psycopg2-binary in local development only, and to use psycopg2 in production:

    $ pip install -e '.'
    $ pip install psycopg2-binary
  5. Install sass. The simplest is to install the node version (below), otherwise see the sass installation docs.:

    $ npm install -g sass
  6. Ensure you have PostgreSQL installed and running. Create a postgresql user with username and password indigo, and create a corresponding database called indigo:

    $ sudo su - postgres -c 'createuser -d -P indigo'
    $ sudo su - postgres -c 'createdb indigo'
  7. Run the Django database migrations to setup the initial database:

    $ python migrate
    $ python update_countries_plus
    $ python loaddata languages_data.json.gz
  8. Then create the superuser:

    $ python createsuperuser
  9. Finally, run the server:

    $ python runserver
  10. Visit the website to login: http://localhost:8000/

  11. Configure a language and a country:

  • Visit http://localhost:8000/admin.

  • Under Indigo API click Languages, then click Add Language in the top right corner.

  • Choose a language from the dropdown list and click Save.

  • Under Indigo API click Countries, then click Add Country in the top right corner.

  • Choose a country and primary language from the dropdown lists.

  • Click Save.

  1. Now go back to http://localhost:8000/ and your country will be included in the list.

PDF support

Indigo creates PDF files using Apache FOP 2.4+. Install it as appropriate for your platform.

Indigo reads from PDF files using pdftotext, which is part of the poppler-utils package. Install it as appropriate for your platform.

Django customisation

You can now easily change Django settings, add your own modules, change URLs, etc. You simply need to create your own settings file, import the settings from Indigo, and update to reference your new settings file. For example:

  1. Create a python module folder my_app:

    $ mkdir my_app; touch my_app/
  2. Create my_app/ so that it looks like this:

    from indigo.settings import *
    # override any Django settings, as you would normally.
    # add your own apps, eg:
    # add your own URLs
    # ROOT_URLCONF = 'my_app.urls'
    # etc.
  3. Update so that it references your new my_app.settings file:

    #!/usr/bin/env python
    import os
    import sys
    if __name__ == "__main__":
        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_app.settings")
        from import execute_from_command_line
  4. Run your updated app with python runserver

Production installation

Indigo requires some non-Python dependencies. This guide explains how to deploy Indigo and these dependencies on Heroku or Dokku. Dokku uses Docker to emulate a Heroku-like environment on your own servers (or cloud).


We don’t recommend using Heroku for production because some Indigo functionality – such as parsing new documents – can take longer than the 30 seconds Heroku allows for web API calls. However, Heroku is great for quickly trying Indigo out.

Installation on Heroku and Dokku are similar and only really differ in the commands that are run. We describe using Dokku below, and assume that you have already have Dokku installed.

  1. Use the Dokku PostgreSQL plugin to create a database:

    $ sudo dokku plugin:install
    $ dokku postgres:create indigodb
  2. Create a new Dokku application and link the postgres database to the application:

    $ dokku apps:create indigo
    $ dokku postgres:link indigodb indigo
  3. (optional) Create a new AWS S3 account and bucket for storing attachments. You’ll need the AWS Access Key Id and AWS Secret Access Key in the next step. You can safely skip this step if you don’t care about saving attachments just yet. If you decide to skip this step, delete the trailing backslash () after the DJANGO_SECRET_KEY variable in step 4 and ignore the last three lines.

  4. Set config options as follows (ensure you enter your correct database and AWS settings):

    $ dokku config:set indigo \
        DJANGO_DEBUG=false \
        DJANGO_SECRET_KEY=some random characters \
        AWS_ACCESS_KEY_ID=aws access key \
        AWS_SECRET_ACCESS_KEY=aws secret access key \

Indigo uses the DATABASE_URL environment variable to determine which database to connect to. This is set automatically by the Dokku PostgreSQL plugin. If you are not using the plugin, you must set DATABASE_URL yourself, using the format postgres://USER:PASSWORD@HOST:PORT/DBNAME.

  1. Deploying requires using git push to push to dokku. So you’ll need to add dokku as a git remote on your local host.:

    $ git remote add dokku dokku@DOKKU-HOSTNAME:indigo
  2. Disable HOSTS check for first deployment as this will cause a failure:

    $ dokku checks:disable indigo
  3. Now deploy to dokku using git push dokku. This is how you deploy any and all updates:

    $ git push dokku
  4. Create an admin user by running this command on the Dokku server:

    $ dokku run indigo python createsuperuser
  5. Install countries and languages:

    $ dokku run indigo python update_countries_plus
    $ dokku run indigo python loaddata languages_data.json.gz
  6. Enable HOSTS check for future updates and ensuring post-deployment checks:

    $ dokku checks:enable indigo
  7. Visit your new Indigo app in your browser at or (depending on how your Dokku installation was configured using the dokku domains:set-global command; read the Dokku Getting Started documentation for details).

  8. Configure a country:

  • Visit

  • Under Indigo API click Countries, then click Add Country in the top right corner.

  • Choose a country and primary language from the dropdown lists.

  • Click Save.


See the example docker-compose.yml <> for inspiration.

Background tasks

Indigo can optionally do some operations in the background. It requires a worker or cron job to run the django-background-tasks task queue. Indigo tasks are placed in the indigo task queue. See django-background-tasks. for more details on running background tasks.

To enable background tasks, set INDIGO.NOTIFICATION_EMAILS_BACKGROUND to True.