CLA Backend API

by ministryofjustice


CLA Backend


Backend API for the Civil Legal Aid Tool.



Clone the repository:

git clone

Next, create the environment and start it up:

cd cla_backend
virtualenv env --prompt=\(cla_be\)

source env/bin/activate

Update pip to the latest version:

pip install -U pip

Install python dependencies:

pip install -r requirements/dev.txt

Create the database inside postgres. Type psql -d template1 to enter postgres, then enter:

\c cla_backend
create extension pgcrypto;

You should see a message saying CREATE EXTENSION. If you get an error instead, if means that you don't have the related lib installed. This is a rare case as postgresql-contrib gets installed automatically by homebrew and postgresapp. In linux, you can install it using sudo apt-get install postgresql-contrib

Now make postgres create the extension automatically when new databases are created, this is useful otherwise the test command will error.

Open a terminal and type:

psql -d template1 -c 'create extension pgcrypto;'

For OSX, update the PATH and DYLD_LIBRARY_PATH environment variables if necessary:

export PATH="/Applications/$PATH"

Create a settings file from the example file:

cp cla_backend/settings/ cla_backend/settings/

Sync and migrate the database (n.b. see Troubleshooting if the postgres role is missing):

./ migrate

Create an admin user by running the following command and specifying username == password == 'admin':

./ createsuperuser

Load initial data:

./ loaddata initial_groups.json kb_from_knowledgebase.json initial_category.json test_provider.json test_provider_allocations.json initial_mattertype.json test_auth_clients.json initial_media_codes.json test_rotas.json

Start the server:

./ runserver 8000

See the list of users in /admin/auth/user/. Passwords are the same as the usernames.

Lint and pre-commit hooks

To lint with Black and flake8, install pre-commit hooks:

. env/bin/activate
pip install -r requirements/dev.txt
pre-commit install

To run them manually:

pre-commit run --all-files


Each time you start a new terminal instance you will need to run the following commands to get the server running again:

source env/bin/activate
./ runserver 8000


When making changes to text (e.g. GraphML files) translations should be updated. To update translations run:

 ./ translations update

Or on macOS ~10.14

brew install gettext
PATH="/usr/local/opt/gettext/bin:$PATH" ./ translations update

Using the a Transifex account that has been added as a Project maintainer to the cla_public project, fetch an API token from

Create ~/.transifexrc in the following format and insert the API token:

api_hostname =
hostname =
username = api

Then ./ translations push to Transifex and ./ translations pull when complete.

Scope Graphs

  • Edit the .graphml files, e.g. using a tool like yEd, to change the scope diagnosis trees
  • Run Django management command python translations update to update translations and templated graph files

See more detailed instructions in the how-to guide on Confluence (log-in required).


If you are experiencing errors when creating and syncing the database, make sure the following are added to your PATH var (amend path to postgres as necessary):

export PATH="/Applications/$PATH"

If you get the error django.db.utils.OperationalError: FATAL: role "postgres" does not exist, you will need to create the user postgres on the database.

createuser -s -e postgres


Releasing to non-production

  1. Wait for the Docker build to complete on CircleCI for the feature branch.
  2. From the output of the Tag and push Docker images job, note the tag pushed to the DSD docker registry, e.g.
    Pushing tag for rev [9a77ce2f0e8a] on {}
  3. Use Jenkins to deploy your branch.
    • APP_BUILD_TAG is the tag name you noted in the previous step: the branch name, a dot separator, and latest e.g.some-feature-branch.latest
    • environment is the target environment, select depending on your needs, e.g. demo or staging
    • deploy_repo_branch is the deploy repo's default branch name, usually master.

Releasing to production

⚠️ Release to production outside of business hours

Business hours: 09:00 to 20:00
Why? Any downtime on the frontend and backend between 09:00 and 20:00 can have serious consequences, leading to shut down of the court legal advice centres, possible press reports and maybe MP questions.
Is there downtime when a release occurs? Usually it's just a few seconds. However changes that involve Elastic IPs can take a bit longer.

  1. Please make sure you tested on a non-production environment before merging.
  2. Merge your feature branch pull request to master.
  3. Wait for the Docker build to complete on CircleCI for the master branch.
  4. Copy the master.<sha> reference from the build job's "Push Docker image" step. Eg:
    Pushing tag for rev [d96e0157bdac] on {}
  5. Deploy master.<sha> to production.

🎉 :shipit: