Kerrokantasi UI is the user interface powering kerrokantasi.hel.fi service. It is a full featured interface for both answering and creating questionnaires as supported by Kerrokantasi API.
- Node v18 LTS (
nvm use) - Yarn
- Docker
config_dev.toml is used for configuration when NODE_ENV != "production". It
is in TOML-format, which for our purposes is Key=Value format.
When NODE_ENV=="production", only environment variables are used for
configuration. This is done because we've had several painful accidents
with leftover configuration files. The environment variables are named
identically to the ones used in config_dev.toml. Do note that the variables
are case insensitive, ie. KeRRokanTasi_aPi_bASe is a valid name. Go wild!
In the repository root there is config_dev.toml.example which contains
every setting and comments explaining their use. If you only want to give
kerrokantasi-ui a test, all configuration you need to do is:
cp config_dev.toml.example config_dev.toml. That will give you a partially
working configuration for browsing test questionnaires in our test API.
yarn build
yarn start
No separate build step is required to start the development server. It is somewhat unstable, but provides hot reloading:
yarn run dev
The server will output the URL for accessing kerrokantasi-ui.
You can use your favorite process manager to run yarn build and yarn start.
Node-specific managers can also directly run compile(/index.js) & server(/index.js).
yarn run fetch-plugins: fetch optional plugins (see below)yarn run test: run testsyarn test -- -uupdate tests
docker compose builddocker compose upThe web application is running at http://localhost:8086
New commit messages must adhere to the Conventional Commits specification, and line length is limited to 72 characters.
commitlint checks every new commit for the correct format.
Add the following line to your hosts file (/etc/hosts on mac and linux):
127.0.0.1 tunnistamo-backend
Go to https://github.com/settings/developers/ and add a new app with the following settings:
- Application name: can be anything, e.g. local tunnistamo
- Homepage URL: http://tunnistamo-backend:8000
- Authorization callback URL: http://tunnistamo-backend:8000/accounts/github/login/callback/
Save. You'll need the created Client ID and Client Secret for configuring tunnistamo in the next step.
Clone https://github.com/City-of-Helsinki/tunnistamo/.
Follow the instructions for setting up tunnistamo locally. Before running docker compose up set the following settings in tunnistamo roots docker-compose.env.yaml:
- SOCIAL_AUTH_GITHUB_KEY: Client ID from the GitHub OAuth app
- SOCIAL_AUTH_GITHUB_SECRET: Client Secret from the GitHub OAuth app
After you've got tunnistamo running locally, ssh to the tunnistamo docker container:
docker compose exec django bash
and execute the following four commands inside your docker container:
./manage.py add_oidc_client -n kerrokantasi-ui -t "id_token token" -u "http://localhost:8086/callback" "http://localhost:8086/silent-renew" -i https://api.hel.fi/auth/kerrokantasi-ui -m github -s dev
./manage.py add_oidc_client -n kerrokantasi-api -t "code" -u http://localhost:8080/complete/tunnistamo/ -i https://api.hel.fi/auth/kerrokantasi -m github -s dev -c
./manage.py add_oidc_api -n kerrokantasi -d https://api.hel.fi/auth -s email,profile -c https://api.hel.fi/auth/kerrokantasi
./manage.py add_oidc_api_scope -an kerrokantasi -c https://api.hel.fi/auth/kerrokantasi -n "Kerrokantasi" -d "Lorem ipsum"
./manage.py add_oidc_client_to_api_scope -asi https://api.hel.fi/auth/kerrokantasi -c https://api.hel.fi/auth/kerrokantasi-uiChange the following configuration in config_dev.toml
kerrokantasi_api_base="http://localhost:8080"
openid_client_id="https://api.hel.fi/auth/kerrokantasi-ui"
openid_audience="https://api.hel.fi/auth/kerrokantasi"
openid_authority="http://tunnistamo-backend:8000"
openid_apitoken_url="http://tunnistamo-backend:8000/api-tokens/"
openid_scope="openid profile https://api.hel.fi/auth/kerrokantasi"
Change the following configuration in config_dev.toml
kerrokantasi_api_base="http://localhost:8080"
openid_client_id="kerrokantasi-ui-dev"
openid_audience="kerrokantasi-api-dev"
openid_authority="https://tunnistus.test.hel.ninja/auth/realms/helsinki-tunnistus"
openid_apitoken_url="https://tunnistus.test.hel.ninja/auth/realms/helsinki-tunnistus/protocol/openid-connect/token"
openid_scope="openid profile email"
Clone the repository (https://github.com/City-of-Helsinki/kerrokantasi). Follow the instructions for running kerrokantasi with docker and using local Tunnistamo.
Questionnaires can make use of plugins. As of yet, their use case has been to provide map based questionnaries. Examples include having citizens indicate places for amenities and polling the public for locations of city bike stations.
A default set of plugins can be installed using yarn run fetch-plugins.
The plugins are installed in assets/plugins. By default, kerrokantasi-ui
expects to find them in assets/plugins URL prefix. The development server
serves that path, but you can also use a web server of your choice for this.
For server insllations, the plugin fetcher supports downloading the plugins
to a directory specified on the command line (yarn run fetch-plugins /srv/my-kerrokantasi-plugins).
It is also possible to change the paths that kerrokantasi-ui will search for
specific plugins. See src/shared_config.json, which is the configuration
source for both the plugin fetcher script and the UI itself. After
changing the paths therein, you can run the plugin fetcher and it will
place the plugins to those directories. Note that specifying path on the
command line overrides the path specified in shared_config.json.
Important:
Kerrokantasi default UI styles are meant to be generic styles (a.k.a whitelabel
styles). This means that no city specific variables or colors should be used
in the assets/sass/ folder. This project supports theming and if there's
a need to style components differently to match a certain city's branding,
theme styles will be used to override any default styles.
The styles are based on Bootstrap version 3 (Sass).
To have a non city specific theme, change the city_config config value to whitelabel
Currently the process of using the theme is not super developer friendly as it does
not support the use of yarn link. This means that to do development on the project
it will have to be installed in the kerrokantasi-ui project and then edited within
the kerrokantasi-ui node_modules/<theme_assets> folder. If someone can find
a solution to this, please fix.
Development steps:
- Place the theme assets folder next to the
kerrokantasi-uifolder- The structure should look like this:
/ /kerrokantasi-ui /<theme-assets-folder>
- The structure should look like this:
- In the
kerrokantasi-uiproject runyarn add ../<theme-assets-folder> - Edit files in
kerrokantasi-ui/node_modules/<theme-assets-folder>for changes to be reflected - Set the
city_configconfig to<theme-assets-folder>
Production installation:
- Add the project to the local
kerrokantasi-uiproject either by installing it the same way as in the dev environment, or from GitHub or if the package is published to npm, then install it from there. - Set the
city_configconfig to<theme-assets-folder>
The assets of a city currently consists of the following things:
- Styling
- Favicons
- Images
- Translation strings
- Service URLs and external URLs
An example of how a theme assets project could look like, either check out the cities/helsinki
folder in this project, or have a look already created theme assets such as:
https://github.com/City-of-Turku/kerrokantasi-ui-turku
How to apply your theme CSS:
Create a file assets/app.scss and apply style imports accordingly:
// This needs to be imported before kerrokantasi variables
@import "my-custom-variables.scss";
// Import the required kerrokantasi styles
@import "~kerrokantasi-ui/assets/sass/kerrokantasi/variables.scss";
@import "~kerrokantasi-ui/assets/sass/kerrokantasi/bootstrap.scss";
@import "~kerrokantasi-ui/assets/sass/kerrokantasi/kerrokantasi.scss";
// These are imported after the kerrokantasi styles to apply overrides
@import "my-custom-styles-and-overrides.scss";
The following aliases are available to use in SCSS and JS files:
kerrokantasi-ui: Points to the root of this projectkerrokantasi-ui-modules: Points to the node_modules of this project@city-config: Points to the root of the city specific assets@city-assets: Points to the assets folder in the city specific assets@city-i18n: Point to the i18n folder in the city specific assets@@city-images: Point to the image folder in the city specific assets
The following naming conventions needs to be used in order to city assets to work.
/assets/app.scss: The base style file that is imported/i18n/[fi, sv, en].json: Language files. If no string changes are to be made, only include{}in the files/i18n/localization.json: Other configuration related to localization. Currently holds map default position/i18n/service-info/content.[fi, sv, en].md: Service info page texts, if no file found service will display information that content was not found./assets/images/logo[fi, sv]-black.svg: Black/Dark site logo/assets/images/logo[fi, sv]-white.svg: White/Light site logo/assets/urls.json: Configure where links point to, also holds path to analytics script. If analytics path is false analytics is disabled.
The following favicons are recommended, but not mandatory to include.
/assets/favicon/favicon.ico/assets/favicon/favicon-32x32.png/assets/favicon/favicon-16x16.png/assets/favicon/manifest.json/assets/favicon/safari-pinned-tab.svg/assets/favicon/browserconfig.xml
If no favicon is provided the UI will use the default kerrokantasi favicon.