Open Business Portal

Local business information centre

License: MIT

API

Access the API exploration GUI at /api/v1/ using your browser.

Examples

Search businesses by name

e.g. for a name containing "brass"

GET /api/v1/businesses/?search=brass

Development

Setup

In one shell:

npm install
npm run dev

This will keep running and rebuilding our js and css upon changes.

In another shell:

Each time you pull in changes that might contain database changes:

docker-compose -f docker-compose.local.yml run --rm django python manage.py migrate

Build the necessary services

docker-compose -f docker-compose.local.yml build django test

Then run collectstatic (only needed for tests, the dev server will serve static files without collectstatic)

docker-compose -f docker-compose.local.yml run --rm django python manage.py collectstatic

Now you can start the server

docker-compose -f docker-compose.local.yml up

If you're setting up for the first time, you need to run this before starting the server, or in another shell:

docker-compose -f docker-compose.local.yml run --rm django python manage.py createsuperuser --username admin --email [email protected]
docker-compose -f docker-compose.local.yml run --rm django python manage.py loaddata business_statuses business_types regions sectors groups

Next you need to import businesses. Businessess' registration data is not directly-editable, because it should only be official registration data. We import registration data as CSV by clicking Import on the Business admin page (top right).

Now you can visit http://localhost:8000

Normally, docker-compose down won't delete the database so your database setup and changes will persist. To delete the database for a completely fresh setup, run

docker-compose -f docker-compose.local.yml down --volumes

Running tests

docker-compose -f docker-compose.local.yml run --rm test

Javascript and CSS

Javascript and CSS build and bundled using Node.js goes in assets/js and asets/scss. See package.json and webpack.config.js.

The Django staticfiles system picks the bundle up and serves it with, for example:

<link rel="stylesheet" href="{% static muni_theme %}">
<script src="{% static 'biz-portal.bundle.js' %}" defer></script>

Muni branding/theme

The municipality logo can be shown in the menu. The logo should be added to this repository in assets/images using the naming convention logo-{mdb_code}.png where {mdb_code} is the municipality's demartcation code. The static path for the image should then be set in the municipality in Admin. The logo should be no wider or higher than 221px.

We use Material Components for the web's theming to customise colours for a municipality. To let it calculate colours when SCSS is transpiled to CSS, we produce a CSS bundle per theme. Each theme entry-point needs to

• be named biz-portal-{name}.scss
  • apart from default, name should be the municipality MDB code. e.g. WC033 for Cape Agulhas
• define the theme colours
• import "@material/theme/mdc-theme" after defining the colours
• import "biz-portal.scss"
• added as an entry-point in webpack.config.js like ./assets/scss/biz-portal-{name}.scss
• added as a rule in webpack.config.js like themeBundle("{name}")

If a theme bundle does not exist for a given municipality, biz-portal-default.scss will be used.

To test markup/style changes for the default and muni-specific bundle, change the MDB code for the muni in Admin to match the appropriate bundle, or fall back to default.

Python

Best practises:

• Format your code using Black: black config biz_portal
• Sort imports using isort: isort --recursive config biz_portal
• Blacken and isort automatically by installing the pre-commit hook:
  • pip install pre-commit
  • pre-commit install
• Create fixtures using manage.py dumpdata --indent 2 ... so that they're readable and formatted consistently to minimise diffs

Test coverage

To run the tests, check your test coverage, and generate an HTML coverage report::

coverage run -m pytest
coverage html
open htmlcov/index.html

Running tests with py.test

pytest

Production deployment

First time setup

First time the app is set up on a server:

dokku condig:set bizportal DATABASE_URL=postgres://bizportal:[email protected]/bizportal \
                           DJANGO_SECRET_KEY=... \
                           [email protected] \
                           SENTRY_DSN=https://[email protected]/...

Locally, add the dokku git remote to be able to push

git remote add dokku [email protected]:bizportal

Temporarily set DJANGO_SITE_ID=1 to be able to run migrations, deploy, login to admin and set up the actual sites with appropriate hostnames, then unset it again so that current_site is identified from the Host header.

After the first deploy as per the next section, create an admin user:

dokku run bizportal python manage.py createsuperuser

Ongoing development

Migrations are run by the python buildpack upon deploy to dokku.

Deploy the latest master branch by pulling locally and pushing it to the dokku remote

git push dokku master