Getting started

Installing system dependencies

You will need:

  • Docker, with Compose

  • npm (best obtained through installing Node)

  • Python 3.12 and pip

  • GDAL (required for the mapping functions)

Make sure your user is in the docker group, by running sudo usermod -a -G docker <username>.

GDAL has to be installed at the OS level as it relies on binaries that can’t be obtained through pip. On Ubuntu or Debian this is as simple as:

$ sudo apt install proj-bin gdal-bin

It’s recommended you install a Sass binary - otherwise you’ll be using a much slower pure JS version. Get one from the Sass GitHub project.

Setting up the Python environment

It is highly recommended to use a Python “virtual environment”, which lets you install a separate parallel set of packages for each app you’re working on.

I (Anna) recommend using virtualenvwrapper. First read its installation instructions, and then create a new virtual environment and install dependencies in one step with:

$ mkvirtualenv -a . -p /usr/bin/python3 -r requirements/local.txt cc-powershaper

Note that the codebase requires Python 3.8, so if your default Python interpreter is an earlier version of 3.x then you will need to install 3.8 and specify /usr/bin/python3.8 in the -p argument.

Activate the new virtual environment:

$ workon cc-powershaper

Add a line to automatically load environment variables to the the postactivate script:

$ echo "source `cat $VIRTUAL_ENV/.project`/.env" >>$VIRTUAL_ENV/bin/postactivate

Set up pre-commit hooks

This project uses pre-commit to ensure that you can’t push changes before they pass tests and linting. Every time you check out a fresh copy of the project you need to run:

$ pre-commit install

Initialise environment variables

Copy example.env to .env.

If you did the above steps, this file will be loaded every time you run workon cc-powershaper. To reload it after changes, run deactivate && workon cc-powershaper. You should do this now.

There is a list of possible environment variables under Environments.

Setting up the database

PowerShaper’s dev setup uses Docker to avoid you having to set up a database server, redis server, and development mail server yourself. Your .env file already has a working DATABASE_URL set up for this.

You will however have to run the Django database migrations:

$ django migrate

(NB django is a nice shortcut for the python manage.py command, provided by the django-shortcuts package. You can shorten the command further to django m.)

Bringing up the app

Install the necessary npm modules using npm ci.

For the first use of a docker container you need to build it with the “up” command: docker-compose -f local.yml up

To get going, inside the virtualenv, just run npm run dev. This will:

  • Bring up the database, mailhog (see below) and redis Docker containers

  • Runs gulp, which compiles assets and sets up hot reload.

  • Bring up the PowerShaper server on http://localhost:3000/ (check the terminal output to confirm the port number as it will depend on which other servers you may have running) and open it in your browser.

Mailhog is a local email server that captures email sent to it rather than relaying it, so you can see what your application is sending. It has a nice UI so you can see what email it has captured, which runs on http://localhost:8026. PowerShaper is configured to use this when in local development mode.

Top tip: if you find browsersync annoying you can connect to http://localhost:8010/ to avoid it.

Creating a superuser account

To create a normal user account, you can either go through the meters signup process, grant yourself a free meter, or add an account through Auth0, or the Django admin in you have USE_AUTH_SERVICE set to False. New Auth0 accounts will receive a “Verify Your E-mail Address” page. Go to your MailHog console to see a simulated email verification message. Copy the link into your browser. Now the user’s email should be verified and ready to go.

To create an superuser account, use this command:

$ django createsuperuser

For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.

If you create an account in Auth0 a User account will be created locally when you log in for the first time.

Running tests

You can run tests by using one of:

  • npm test - which will run all tests in powershaper/ and also the flake8 linter

  • pytest <path> - to run individual test files

  • npm run coverage - which will run the tests, and output detailed coverage reports in htmlcov/index.html

You might also want to run type checks with mypy:

$ mypy powershaper

If you use type annotations, this can be useful to run occasionally, though it also has quite noisy output.

Scheduled tasks

To activate the Redis Queue <http://python-rq.org/> background task runner & scheduler in your local environment you need to run:

$ django rqworker
$ django scheduler

(Though it’s usually easier to call a scheduled task individually from a Django shell.)

The task scheduler is set up by custom commands which are common to PowerShaper and the Hub - you can read about this in the Hub documentation.

Shutting down

To stop Docker running containers in the background, you can use:

$ npm run docker-down

Or instead, without npm witchcraft:

docker-compose -f local.yml down

If you want to bring it down and delete all extant data, use npm run docker-clean instead. You will have to re-run migrations after this if you want to bring the server back up again.

Nuke the database

Again, without npm witchcraft:

docker-compose -f local.yml down
docker system prune --volumes
docker-compose -f local.yml up
docker-compose -f local.yml start
npm run dev