Electronic building permit application for Swiss cantons.

Table of Contents

• Overview
  • Folder structure
  • Modules
• Requirements
• Development
  • Basic setup
  • Predefined credentials
  • Debugging
  • Working locally with ember
  • Yarn workspace
  • Django profiling
  • Visual Studio Code
  • GWR API
  • Customize API
  • Sending email
• License

Overview

This repository contains the source code for the web applications used to handle electronic building permits and comparable processes in the Swiss cantons of Berne, Schwyz and Uri.

The following image shows a high-level overview of the architecture:

• The application is composed of various Docker containers, which are shown in light blue in the architecture overview.
• The frontend consists of two Ember.js apps, one for applicants submitting building permit applications ("portal"), and another used by members of the public authorities ("internal area"). The two apps can share code through the Ember Addon ember-ebau-core.
• The backend is based on Python/Django and exposes a GraphQL API for forms and workflows based on Caluma and set of domain-specific REST endpoints (Django REST Framework).
• PostgreSQL is used as database.

Folder structure

├── compose                # docker-compose files
├── db                     # database Dockerfile and utils
├── django                 # backend code, containing both API and Caluma
├── document-merge-service # document generation templates and config
├── ember-caluma-portal    # Caluma-based portal
├── ember-camac-ng         # Ember.js app optimized for embedding in other applications
├── ember-ebau             # Ember.js based application for internal area
├── ember-ebau-core        # Ember.js addon for code sharing between multiple Ember.js apps
├── keycloak               # Keycloak configuration for local development
├── proxy                  # Nginx configuration for local development
└── tools                  # miscellaneous utilities

Modules

Due to ongoing modernization work, some Frontend modules are not yet integrated in ember-ebau, but instead are still part of ember-camac-ng. Few Frontend modules are not part of this repository yet at all. The following table lists the most important modules in the "internal" part of the application and their respective completeness / integration state (in the demo configuration).

Requirements

The preferred development environment is based on Docker.

• Docker >= 20.04
• Docker-Compose

For local development:

Python:

• python 3.8
• pyenv/virtualenv

Ember:

• current LTS of Node.js
• yarn

Development

Basic setup

Docker can be used to get eBau up and running quickly. The following script guides you through the setup process. We recommend using the demo config for now, since it features the highest number of modules in the ember-ebau app.

make start-dev-env

In case you want to manually modify /etc/hosts following domains need to point to 127.0.0.1 (localhost):

ebau-portal.local ebau.local ebau-keycloak.local ember-ebau.local ebau-rest-portal.local

For automatic checks during commit (formatting, linting) you can setup a git hook with the following commands:

pip install pre-commit
pre-commit install

After, you should be able to use to the following services:

• ember-ebau.local - new main application used for "internal" users
• ebau-portal.local - public-facing portal (Caluma-based, default choice for new projects, used in Kt. BE, UR)
• ebau.local/django/admin/ - Django admin interface
• ebau-keycloak.local/auth - IAM solution

Predefined credentials

The following administrator accounts are present in Keycloak or the DB, respectively:

Debugging

For debugging inside container shell, use this:

make debug-django

Working locally with ember

docker-compose up -d --build db django
cd {ember|ember-camac-ng|ember-caluma-portal|ember-ebau} # Enter ember from the top level of the repo
yarn # Install dependencies
yarn test # Run tests
yarn start-proxy # Run dev server with proxy to django api

Yarn workspace

Note however that those two apps ember-caluma-portal and ember-camac-ng share the same node modules tree through a yarn workspace.

The common yarn workspace allows us to share code (e.g. addons) between the apps which are part of this repo (instead of following the typical approach of publishing releases on npm). This also means that

• (+) we save some disk space because of the avoided duplication in the node_modules directory
• (-) the docker build processes of the two frontend containers have to run in the context of the root of the repo, in order to access the shared dependencies during build time
• (-) the ember versions ember-caluma-portal and ember-camac-ng need to be kept in sync

Django profiling

To enable django-silk for profiling, simply add DJANGO_ENABLE_SILK=True to your django/.env file. Then restart the django container and browse to http://ebau.local/api/silk/.

Visual Studio Code

The remote debugger settings for VS Code are committed to the repository.

• The configuration file is located at .vscode/launch.json.
• The keyboard shortcut to launch the debugger is F5.
• Information on VS Code debugging

To enable debugging in the django container the ptvsd server must be started. Since this debug server collides with other setups (PyCharm, PyDev) it will only be started if the env var ENABLE_PTVSD_DEBUGGER is set to True in django/.env.

GWR API

The GWR module is developed in two separate repositories:

• Frontend: inosca/ember-ebau-gwr
• Backend: inosca/ebau-gwr

If you use the GWR module, you need to generate a Fernet key according to the documentation of the gwr backend.

You need to set this key in each environment/server in your env file. Generate a separate key for each environment, since this is used to store / read the gwr user passwords.

Customize API

The API should be designed in a way, that allows it to be used by any eBau project. For needed customization, the following rules apply:

• each permission may be mapped to a specific role in the specific project. In case a role may have different set of permissions than already available, introduce a new one and adjust the different views accordingly.
• for features which may not be covered by permissions, introduce feature flags.

For different feature flags and permissions, see APPLICATIONS in settings.py.

Sending email

In development mode, the application is configured to send all email to a Mailhog instance, so unless you specify something else, no email will be sent out from the development environment.

You can access the Mailhog via http://ebau.local/mailhog . Any email sent out will be instantly visible there.

License

This project is licensed under the EUPL-1.2-or-later. See LICENSE for details.