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 can be found under https://github.com/oskariorg with main ones being:

The sample-application and sample-server-extension can be used as templates for generating your own customized Oskari-based applications. If you are not developing Oskari itself, but creating an Oskari-based application these repositories are for you. The oskari-documentation repository contains the documentation content that is shown on oskari.org (like this page). Some links on the documentation only work when the content is viewed on oskari.org. We also have centralized our GitHub issue tracking under oskari-documentation. If you want to take a look how Oskari works, how the framework/library/common functionalities are implemented or even contribute code to Oskari you can take a look at oskari-frontend and oskari-server the repositories.

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 Application environment

An Oskari-based web application consists of frontend code for browser-based user interface and backend functionalities that are run on the server. The user interface is implemented in JavaScript and the server functionality in Java. Both, the frontend and the backend, are built with extensibility in mind.

An example for building your own service is provided as a template application that can be run as is and it enables an easy starting point for customizing the service.

The picture below shows the generic idea of Oskari.

1.4 Frontend

The user interface for Oskari-based services usually is a Javascript-based single-page app. The UI is built by selecting a series of bundles that provide functionalities/capabilities for an application. You can mix and match the bundles or create new ones to customize the application for your needs.

Bundles are used as uniform containers to ship and share new functionality to the application setups. Additions to an existing functionality can be implemented as plugins shipped within the bundles.

A bundle can work "as is" for providing its functionality with its own user interface and/or it can provide a documented API that can be used to interact with the functionality programmatically. One example of a bundle that doesn't have an UI itself would be a bundle called drawtools that only provides an API that is used by measurement tools, my places functionality and others that has the user "draw" something on the map. The API also helps implementing a customized drop-in replacements for functionalities when required.

Bundle functionality

Bundles can provide an API for other bundles to request some operation through a request handler.
A bundle can provide a request class and register a handler for the request in the Oskari framework. This is refered to as the request API for the bundle and should be fairly stable.
Another bundle can then send the request which will be processed by the other bundle.
Another way to communicate with other bundles is to send out an event through Oskari framework.
Any bundle registered as an eventlistener for the given event is then notified about the event.

1.4.1 Frontend source code and folder structure

The frontend for Oskari-based applications can be divided into two (or more) parts:

the application that can be customized for a specific need
oskari-frontend that provides the frontend framework, built-in UI-component library and bundles that can be used as building blocks when creating applications.
you can also use bundles from oskari-frontend-contrib repository like ones from oskari-frontend and/or another third party repository

You can find an Oskari-based sample application source code here.

The sample application frontend source code has the following folder structure:

/applications - References to bundles that will be used in a specific application
/bundles - Implementation for application specific bundles

The applications folder has for example geoportal and embedded as applications as both of these use different set of bundles. For the sample-application the geoportal is what you expect to see when opening the Oskari application and lists all the bundles that will be used on different geoportal views on the example application (https://demo.oskari.org etc). The embedded application references the bundles that users can select to be included when publishing maps from the geoportal. We need to reference any bundle that could be started on an embedded map, but we can still optimize by using the oskari-bundle loader for ones that are always used (like the map) and use oskari-lazy-bundle to reference ones that see less use (like thematic maps). This way the file that end-users need to download when opening the map only has the ones that are common to get a smaller file size while also enabling users to use the more specific functionalities that are only loaded when used on the embedded maps.

Applications can and usually do use many of the bundles provided in oskari-frontend. You can find a list of these bundles in the bundle documentation. If you want to learn more about about oskari-frontend in general, you will find documentation for it under the "Frontend framework" section of the documentation.

1.5 Backend

Backend functionality of the platform is implemented with Controllers from Spring framework and can be easily extended to handle new functionality. Also the Spring-layer is very light on top and could be substituted with another if needed.

The server-side codebase can be divided into two parts:

the application that can be customized for a specific need
oskari-server as library of maven modules

1.5.1 Backend architecture

The Java webapp archive (war-file) for Oskari server is packaged as oskari-map.war in sample-server-extension (the webapp-map module).

It handles most of the server side functionality alone, but doesn't need to include much code as it uses the Maven modules from oskari-server that handle most of the things it needs.

You can find Oskari-server source code here.

The webapp is extensible and you can add more modules from oskari-server or remove ones you don't need to adjust the functionalities your app requires. It is also very easy to add more handlers/controllers for any application specific needs when creating your own geoportal/web mapping application.

The server application template has Maven modules for an example setup with:

app-resources (has initial database data and migrations for the application)
app-specific-code (has a "Hello World" request/action handler as an example of app specific code)
webapp-map (uses the other two modules and packages everything up in a Java war-file)

1.5.2 Server-side libraries and technologies

Oskari backend uses the following libraries and technologies:

Tomcat/Jetty or similar as Java servlet container
PostgreSQL (database)
PostGIS (spatial data extension for PostgreSQL)
Redis (for caching and communication in clustered server environment)

Based on your needs you can decorate your architecture by adding components like these in front of the Oskari server:

HAProxy (proxy, load balancer)
Apache HTTPD (proxy, load balancer)
Nginx (proxy, load balancer)
F5 load balancer

Having HTTPD or nginx for serving the static frontend application and passing other requests to Tomcat/Jetty is a popular choice.

1.5.3 Server-side source code

You can find Oskari backend source code in here.

Note that oskari-server doesn't have a runnable webapp to reduce forking as webapps are usually (heavily) customized per application requirements.

You can find a template to start your server customization with our example template here.

Documentation