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
  • Switching tenant
    • Working locally with ember
    • Working with docker only
  • Visual Studio Code
  • GraphQL
  • 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).

Module	Description	Backend	Frontend	Part of ember-ebau
Main Nav (resource)
Dossier list	Show a list of dossiers	✔️	✔️	✔️
Task list	Show a list of tasks	✔️	✔️	✔️
Templates	Manage document templates (docx)	✔️	✔️	✔️
Organization / Permissions	Manage own organization and permissions	✔️	✔️	✔️
Static content	Static content, markdown editor	✔️	⏳	⏳
Text components	Manage snippets for usage in text fields	✔️	⏳	⏳
Subnav (instance resource)
Tasks	View and manage tasks	✔️	✔️	✔️
Form	View and edit main form	✔️	✔️	✔️
Distribution	Get feedback from other organizations	✔️	✔️	✔️
Alexandria	Document management	✔️	✔️	✔️
Template	Generate document from template	✔️	✔️	✔️
Journal	Collaborative notebook	✔️	✔️	✔️
History	Shows milestones and historical data	✔️	✔️	✔️
Publication	Manage publication in newspaper	✔️	✔️	✔️
Responsible	Assign responsible users	✔️	✔️	⏳
Audit	Perform structured audit	✔️	✔️	⏳
Audit-Log	Shows form changes	✔️	⏳	⏳
Claims	Ask applicant for additional info	✔️	⏳	⏳

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
• ember-ebau.local/mailhog/ - Mailhog UI
• ember-ebau.local/minio/ui/ - MinIO Admin UI

Predefined credentials

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

Application	Role	Username	Password	Notes
demo	Admin	user	user
kt_schwyz	Admin	admin	admin
	Publikation	adsy	adsy
kt_uri	Admin	admin	admin
	PortalUser	portal	portal
kt_bern	Admin	user	user
kt_gr	Admin	admin@example.com	admin

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/.

Switching tenant

To switch from the demo config to kt_bern, one has to make sure that the frontend apps take up the right environment variables.

Working locally with ember

1. Stop the frontend servers started with yarn start-proxy
2. Run make kt_bern
3. Run docker-compose up -d && make loadconfig
4. Start using command from step 1

Working with docker only

1. Run docker-compose down
2. Run make kt_bern
3. Run docker-compose build
4. Run docker-compose up -d

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.

GraphQL

In order to talk to the /graphql endpoint with authentication, you can install a GraphQL Tool (much like Postman). Tools you might consider here:

• Insomnia
• Altair GraphQL client

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.