Local business information centre

License: MIT

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

e.g. for a name containing "brass"

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

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 admin@admin.admin
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

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

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>

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.

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

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

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

pytest

First time the app is set up on a server:

dokku condig:set bizportal DATABASE_URL=postgres://bizportal:...@postgresql94-prod.cnc362bhpvfe.eu-west-1.rds.amazonaws.com/bizportal \
                           DJANGO_SECRET_KEY=... \
                           DOKKU_LETSENCRYPT_EMAIL=webapps@openup.org.za \
                           SENTRY_DSN=https://...@sentry.io/...

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

git remote add dokku dokku@dokku9.code4sa.org: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

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