1 Welcome

1.1 Introduction to Oskari

Welcome to Oskari's documentation!

Oskari is an open source Web Map Framework. The aim of Oskari is to help organisations to create better map applications to be used on web browsers and mobile devices. Oskari supports EU's INSPIRE directive and OGC standards.

Oskari enables you to create a map service that is either a full blown geoportal, a highly customized embedded map or something in between.

Oskari's appearance, UI and functionalities are customizable. Oskari is easily extendable and allows adding application specific functionalities.

As an open source project Oskari is developed together. The development is coordinated by National Land Survey of Finland. Oskari is dual-licenced MIT/EUPL 1.2.

Oskari's GitHub repositories are

Note that this document is a work in progress. If you find any outdated information, notice that something is missing or that some sections could be improved, let us know by making an issue in GitHub or a Pull request to the Oskari documentation repository.

If you have further questions or need help with your Oskari instance, see our Contribute and FAQ pages or feel free to reach out to us in Gitter or the mailing list!

1.1.1 Technical overview

Here is a brief technical overview of Oskari. More information about frontend and backend can be found in section 2 Application environment.

Oskari has a separate browser-based frontend and a server-side backend that combine into an Oskari-based service.

Oskari's frontend is a JavaScript-based collection of "bundles". A bundle in Oskari is a technical term used to describe a frontend code package that implements a specific functionality. The bundles can be easily used by developers to mix-and-match different functionalities and used as building blocks for their own Oskari-based application. Frontend's GitHub repository can be found here.

The backend is a Java web application built with Maven that can be deployed to a Java Servlet container like Tomcat or Jetty. The oskari-server GitHub repository can be found here and consists of Maven modules that can be used as building blocks for Oskari-based webapps. Oskari.org provides a Maven repository as an easy way to use these in Oskari-based applications.

The sample server extension is a template repository that can be used to quickly start working on a customized backend for Oskari-service and can be found here.

The sample application of Oskari's frontend is a Single Page Application (SPA) that uses the modules from oskari-frontend for creating an Oskari-based application. It is a template repository that can be used to quickly start working on a customized application frontend and can be found here.

The template (sample) repositories are meant to be used as starting points for creating an Oskari-based service with your own selection of functionalities, data, users, layout, colors and other customizations. These can also be used to add new service specific functionalities without forking the Oskari codebase.

See also the unofficial Oskari bundles created by the Oskari community here.

Aside of the frontend and backend, Oskari requires a PostgreSQL/PostGIS database. For caching purposes and messaging in clustered environments Oskari uses Redis. Oskari is built for featuring benefits of a spatial data infrastucture and uses data from standard OGC-services.

Previous versions of Oskari required a GeoServer installation for handling user generated data, and even though many organisations that use Oskari have a GeoServer instance too, Oskari does not require it anymore.

The data displayed on the service is fetched from APIs.

1.1.2 Requirements for developing Oskari

Developer is a person who has at least basic understanding of reading/writing or copy/paste/modifying code. Oskari consists of a Java web application running on the server with SPA Javascript frontend for the browser, so working with web applications or similar projects helps understanding how Oskari works. Enabling and disabling functionalities for an Oskari-based service requires less knowledge about coding, but still requires compiling code. Its possible to both develop new functionalities for an Oskari-based application for custom requirements and/or improve existing functionalities in Oskari as we welcome pull requests on GitHub.

The requirements for developing the backend and the frontend differ. But which one should you make changes to? As a rule of thumb:

If you want to add new user-interface elements to your application, you need to develop the frontend.
If those user-interface elements need to access something on the server, you might need to make changes to the backend.
If you want to enable or disable functionalities that are provided in Oskari you should make changes to both the the backend (configuration of functionalities to use) and the frontend (to package in or remove code that is sent to the browser), but this is usually fairly simple copy/pasting of existing code samples.
If you want to customize the way Oskari looks, Oskari supports theming that is represented as JSON on the the backend. However you might want to tweak some settings on the the frontend as well depending on the requirements.

Basic requirements for developing Oskari:

Version management: Git
Frontend: JavaScript, HTML, CSS, SCSS, React, OpenLayers
Backend: Java, PostgreSQL (with PostGIS for user generated data), Redis, Jetty(/Tomcat or similar)
Build infrastructure & tests: Maven/JUnit for server, Webpack/Jest for frontend.
Basic understanding about the following software: PostGIS, Jetty(/Tomcat or similar), Redis, Nginx (/Apache httpd or similar)
Understanding about OGC standards: WMS, WMTS, WFS, WCS

If you are planning to develop Oskari, don't hesitate to contact NLS FI right at the start. The coordinators from NLS are willing to guide your work and give general guidelines for developing work. Remember to always document your work and please use the official Oskari documentation as a reference for your own documentation. As an open source project Oskari requires the contribution of the community that uses it, so please make pull requests to the main Oskari repositories, too.

1.2 Basic concepts

Here are listed the explanations for some of the basic Oskari concepts and Oskari-spesific terms. If you didn't find the term you were looking for from this section, please let us know by creating an issue in GitHub.

Application = Provides a service for the end-user
Application-frontend = The parts of an application that are run on the browser. Combines pre-existing bundles from Oskari-frontend and application specific bundles to provide the user-interface for the service.
Application-server = Provides backend functionality that enables the frontend to do its things.
Bundle = A frontend code package that provides a specific functionality for the application. Basically a frontend implementation of some functionality. Usually referred to with its id like search.
- Same functionality can have multiple implementations. If the API of implementations match they can share the same id. However the same functionality can be provided by bundles with different id's if either their API doesn't match or they have different use cases. For example the search UI is implemented on the bundle search with a window-like UI (see Tile/Flyout) but it's also provided as part of the mapmodule bundle as a small on-map text field.
- Sometimes refered also as modules.
- Bundles can provide an API of requests, events and services allowing other functionalities to interact with them.
- Bundles have a lifecycle API with functions that are called when the functionality is started or stopped etc.
Class = Oskari-frontend uses custom implementation of classes (defined with Oskari.clazz.define()). These will eventually disappear from the frontend.
Component = Oskari provides UI components like buttons, text fields etc with a purpose of making the user interface look coherent with same kind of UI elements implemented in the same way.
Feature = Currently used to refer vector features (points, lines, polygons on map in vector format). Generally not used anymore in Oskari documentation, but sometimes a synonym with functionality.
Module = See Bundle. We sometimes mix our terms.
Plugin = Bundles can contain plugins. They can be considered as mini-bundles that enhance the functionality of a bundle. Mostly used with the map module to add functionality for the map.
RPC = Remote procedure call. In Oskari RPC refers to one of the key features of Oskari, embedding a map to another website. RPC functionality allows a developer to control the embedded map and react to events on the map from the embedding website. The instance that hosts the embedded map and the selections made in the publisher functionality affects what can be done with RPC. Some functionalities can be disabled or not supported depending on the Oskari instance.
Sample application = The sample (=template) repositories are meant to be used as starting points for creating an Oskari-based service with your own selection of functionalities, data, users, layout, colors and other customizations.

1.3 Git process

This document describes the source management process used by the Oskari project. As internal development at NLS uses a rather well documented branching model called Git Flow, this document emphasizes interfacing with external developers/teams instead of reiterating Git Flow documentation readily available on the Web.

1.3.1 Oskari Git Flow overview

Read Atlassian's awesome Git Flow documentation for more information.

1.3.2 Branches & Repos

master

The latest stable release.
Tagged according to Oskari's versioning scheme.
Commits merged from hotfix and release branches.

develop

The work-in-progress next release.
Commits merged from pull requests.

release/x.y.z

A release branch is opened as a code freeze some time before the next release based on the current develop-branch.
Release branch should only include bugfixes to the features that will be in the next release.
Any new features should be merged to develop-branch for a release after the next one.
Once the release testing has been completed the branch will be merged into develop and master.

hotfix/x.y.z

When urgent bugfixes are required for the latest release a hotfix-branch is opened based on the current master-branch.
Once the fixes are completed the branch will be merged into develop and master.

{any-other-branches}

Sometimes opened for developing larger change sets that might require multiple pull requests of development before they can be merged to develop without breaking things unintentionally.
Once the feature is completed the branch will be merged into develop
Most functionality development should be done in forks, not the official repositories.
See how to contribute for Git instructions

External branches

The branching model utilized by an external team is generally irrelevant to the process of handling external contributions. It is, however, assumed for the purposes of this document that there exists a continuous sequence of commits from the latest merge from Oskari branches on GitHub to the commit(s) presented for consideration for inclusion in Oskari proper. This is required in order to be able to rebase such commits on the develop branch.