2 Setup instructions

This section contains instructions for setting up a new Oskari instance. First a PostgreSQL database with PostGIS extension is set up, then the actual Oskari instance with related programs is downloaded and installed. These instruction use usernames, passwords and other values that you should change for production, but are ones that the Oskari downloadable example installation uses as defaults and pre-configured settings. For your first install you should probably use the defaults and see that you can get the server running. After that you can start over by dropping the database and start tinkering with the configurations to use your preferred credentials and other environment specific changes.

This manual focuses on Oskari and gives you the basic guidance to the related software/libraries which should be enough to get you through the setup process. If you encounter issues with PostgreSQL or other Oskari-related libraries, please refer to their respective manuals.

The diagram below shows the components that are commonly used in Oskari installations.

C4Deployment

Person(user, "User", "")

Boundary(service, "Oskari-based service", "") {
    Boundary(frontend, "Web server", "nginx/httpd"){
        Component(sample-app, "sample-application", "Javascript")
    }
    Boundary(server, "Servlet container", "tomcat/jetty") {
        Component(sample-server, "sample-server-extension", "Java")
    }
    Boundary(db, "Databases", "") {
        ContainerDb(postgres, "PostgreSQL", "PostGIS/SQL", "Application config and user data")
        ContainerDb(redis, "Redis", "", "Caching")
    }
}
System_Ext(sdi, "OGC and other APIs", "External services")


Rel(user, sample-app, "", "")
Rel(sample-app, sample-server, "", "")
Rel(sample-server, postgres, "", "")
Rel(sample-server, redis, "", "")
Rel(sample-server, sdi, "", "")
Rel(user, sdi, "", "")

2.1 Setup database

This document describes how to set up a single database for the oskari-server component.

The standalone Oskari server depends on the availability of PostgreSQL with PostGIS extension for serving content and authenticating users.

2.1.1 Database requirements:

The following components are assumed pre-installed:

• PostgreSQL 11+ (Known to work with 11, 12, 14 mainly affected by the version of FlywayDB-dependency that is used by oskari-server. Developed using 14.)
• PostGIS (Developed using 3)

2.1.2 Steps to create the database

Install a supported version of PostgreSQL and PostGIS on your environment. The default configurations assume PostgreSQL is installed on localhost with the default PostgreSQL port (5432). This is configurable in oskari-ext.properties file (found under oskari-server/lib/ folder in the downloadable file).

Create an empty database with PostGIS extension

The default configurations assume the database name is oskaridb (configurable in oskari-ext.properties file).

Run the create database SQL in for example psql or pgAdmin (see if they were installed in the PostgreSQL installation package):

CREATE DATABASE oskaridb
WITH OWNER = postgres
  ENCODING = 'UTF8'
  TABLESPACE = pg_default
  CONNECTION LIMIT = -1;

Connect to the database with \c oskaridb in psql or by opening the query tool on pgAdmin or similar for the oskaridb database.

Run this SQL on the database to add the PostGIS extension:

CREATE EXTENSION postgis;

Setup a database user for oskaridb

Run these commands to create default user with all privileges

CREATE USER oskari WITH PASSWORD 'oskari';
GRANT ALL PRIVILEGES ON DATABASE oskaridb TO oskari;

The preconfigured database user in Oskari example application is oskari with the password oskari (configurable in oskari-ext.properties file).

Some versions of PostgreSQL might also need you to run:

GRANT ALL PRIVILEGES ON SCHEMA public TO oskari;

If you see error messages like this when starting the server: Message: ERROR: permission denied for schema public you need to add privileges for the schema as well. For production environments you can define lesser privileges for the database user, however the migration scripts (run on version updates) can create, drop or alter tables on the database so you will need to allow these. It is also possible to run the migrations required on server updates with a user that has more privileges while using another user with lesser prileges for operational use.

Application initialization and database content

The empty database will be populated with table structure and example data when the application server is started for the first time using automatic migrations. The database migrations are split into modules. The core module creates and migrates the main database tables used by Oskari. Changes to these need to be done on the oskari-server repository itself and usually can't be skipped by the application.

The example configuration includes a migration module named app (in oskari-ext.properties) that will populate initial example data for the demo application to get a nice unboxing experience. Changing or replacing the app module is the intended way of customizing any application specific migrations and possible initial data and/or users. These application specific migrations also create the default users and their credentials that can be used to login to the example application. These you must change or remove when creating your own Oskari-based application.

Note that migrations are run only once so making changes to existing migration files and restarting the application server requires an empty database for migrations to be run again (or removing related rows on the migration status database tables). However the migrations follow versioning through naming so you can add migrations to modify an existing database by naming the migrations in a certain way.

The next step after having the database ready is installing the application that runs these migrations. If you want to skip way ahead and learn how to customize Oskari including populating the database with your own content instead of example content see:

• Create a custom Oskari-server extension

2.2 Setup application server

This section contains instructions on setting up a Java application server for Oskari using the download package with Tomcat and pre-installed/configured Oskari

After completing this section you will have the Oskari-based example application running, including:

• Oskari-frontend based sample-application (https://github.com/oskariorg/sample-application)
• Oskari-server based sample webapp (https://github.com/oskariorg/sample-server-extension)

Requirements

The following are required for setting up Jetty.

• JDK 17 (Java Development Kit)
• Database available: Instructions for setting up database

Setting up Tomcat

Follow the steps below to get Tomcat properly set up.

1) Download the Oskari example application

2) Unpack the zip file to selected location

The zip includes:

• Readme.md
• licence folder
• oskari-map.war as prebuilt server application
• sample-application folder with the prebuilt frontend application code
• apache-tomcat-10.1.39 (referred as {tomcat.home})
• oskari-server folder (referred as {tomcat.base})

3) Configure the database properties (host/credentials) by editing {tomcat.base}/lib/oskari-ext.properties

db.url=jdbc:postgresql://[host]:[port]/[dbname]
db.username=[user]
db.password=[passwd]

4) Startup the Tomcat

By running the command (in {tomcat.base}):

• server.bat start for Windows OR
• server.sh start for *nix-based OS (Ubuntu, MacOS, Windows WSL etc)

Note that it's important where you run the command/what is the working directory so run the command in the oskari-server folder. Otherwise folder references in those scripts might not work as expected. The scripts are for convenience only, you could download Tomcat from their site and use that to run Oskari. Separating {tomcat.base} and {tomcat.home} is useful if you want to use Tomcat binaries as shared library (the {tomcat.home} folder) and have multiple different Oskari-based applications with their own config and code on their own Tomcat instances. You can add parallel instances by just making copies of the {tomcat.base} and changing their configurations.

The main configurations you might want to take a look at under {tomcat.base} when setting up a different setup are:

• eveything under lib/* with the most important file being lib/oskari-ext.properties. This is the main configuration file and is searched from the Java classpath on server startup.
• context XML-files under conf/Catalina/localhost/*.xml
• log files are generated under the logs folder

The zip has sample-application and oskari-map.war as the actual applications that are served from Tomcat. These are referenced in the conf/Catalina/localhost/*.xml files. If you want to have the files somewhere else, you can modify the XML-files to use some other location.

5) After Tomcat is up and running open a browser with URL

http://localhost:8080

You can login as:

• user with username "user" and password "user"
• admin with username "admin" and password "oskari"

Note! These default users are introduced in the database migration module for the example application (sample-server-extension) and publicly advertized on the sample-info bundle in the sample-application (frontend repository). You should change/remove these for any applications you create based on the example setup.

Advanced configuration

For further configuration check out Server configuration

2.3 Build customized server-side application

This section describes how to replace the prebuilt server side webapp with your own version. This is the intended way of customizing Oskari-based applications.

2.3.1 Server requirements

The following items are required for the development process:

• JDK 17
• Maven 3+ (developed using 3.6.3)
• Git client (optional)
• GitHub account (optional)

You will need an environment to run the code in as described on Setup application server

Feel free to use the git conventions used in Oskari development with your own customizations, but it's your app so you can make your own choices.

2.3.2 Create your server application repository

You can use our sample-server-extension template for creating a repository that will have your application customizations under your own GitHub user/organization: https://github.com/new?template_name=sample-server-extension&template_owner=oskariorg

Clone the repository to your own computer with git. You can use any program you are comfortable with to work with git, but on command line you can run:

git clone https://github.com/oskariorg/sample-server-extension.git

Replace oskariorg with your own username/organization name and sample-server-extension if you changed the repository name for your app.

For simple testing you can also just clone our template repository for tinkering, but BEWARE the template repository is intended to be a starting point and it will be updated in ways where the migrations and initial content will be modified in place (skipping the migration history like is usually done for maintained apps). This means that going forward you can't simply merge released changes from the template repository to your application repository using git so it's best to create a copy and not a fork of the sample-server-extension for your own app.

If you don't use git you can also just download the repository code as zip from GitHub.

2.3.3 Build your version of the server application

Once you have the server application repository cloned (or downloaded and unzipped) you can use Maven to build your own version of the oskari-map.war.

Go to the root folder of the repository (cd sample-server-extension) and run the Maven command:

mvn clean install

This will create the oskari-map.war file under webapp-map/target.

You can replace the oskari-map.war from the Oskari download package with this newly created file and restart the server.

2.3.4 Simple server modifications

These are some easy to test modifications to see that your server application has changed:

• JSP-files under webapp-map/src/main/webapp/WEB-INF/jsp has the base HTML in them. You can simply change the value of <title> tag for example.
• JSON-files under app-resources/src/main/resources/json/apps select the functionalities (Oskari "bundles") that will be used on the application (Note! changing these will require an empty database to see changes)
• Flyway migrations under app-resources/src/main/resources/flyway/app and app-resources/src/main/java/flyway/app (Note! changing these will require an empty database to see changes)

Note! When you change something in the code, you need to recompile/build a new version of oskari-map.war and deploy the new version on the server. If you change anything on the initial data/migrations you need to drop the database and create a new empty one. To migrate the content from it's initial state you can add new migrations that will be run on an existing database, but modifying ones that have already been executed on the database will not be rerun on a non-empty database.

2.3.5 WAR-file location

If you want to use the war-file from another location you can change the reference to the war-file. This can be changed in oskari-server/conf/Catalina/localhost/ROOT.xml (https://github.com/oskariorg/sample-configs/blob/master/tomcat-10/oskari-server/conf/Catalina/localhost/ROOT.xml) by changing the value of docBase:

<Context docBase="../../oskari-map.war" reloadable="true" />

For development it's easiest to have it reference the {your.git.repo.root}/webapp-map/target/oskari-map.war directly so it will be redeployed as soon as you compile a new version without need to copy the file around.

2.4 Build customized frontend application

This section describes how to replace the prebuilt frontend application with your own version. This is the intended way of customizing Oskari-based applications.

2.4.1 Frontend requirements

The following items are required for the development process:

• NodeJS (developed using 18+)
• Git client (optional)
• GitHub account (optional)

You will need an environment to run the code in as described on Setup application server

Feel free to use the git conventions used in Oskari development with your own customizations, but it's your app so you can make your own choices.

2.4.2 Create your frontend application repository

You can use our sample-application template for creating a repository that will have your application customizations under your own GitHub user/organization: https://github.com/new?template_name=sample-application&template_owner=oskariorg

Clone the repository to your own computer with git. You can use any program you are comfortable with to work with git, but on command line you can run:

git clone https://github.com/oskariorg/sample-application.git

Replace oskariorg with your own username/organization name and sample-application if you changed the repository name for your app. For simple testing you can also just clone our template repository for tinkering, replacing the existing sample-application folder with your cloned repository.

If you don't use git you can also just download the repository code as zip from GitHub.

Note! The sample application, including its source code and build, is available in the sample-application folder within the Oskari download package. The frontend application builds are generated in the dist folder under the sample-application and the prebuilt version is included in the download zip file.

2.4.3 Build your version of the frontend application

Modern web applications are developed using JavaScript syntax that is not fully supported by older browsers and the code needs to be processed before it can be used by the end-user browsers. This step also includes bundling and minifying the code so it's more compact for consumption than the human-friendly version that is used for development. This will reduce the startup time for the end-user dramatically.

1. Go to the root folder of the repository (cd sample-application)
2. On the first time (or after you have updated Oskari version) run npm install to install dependencies
3. Run the npm command to generate new build product:

npm run build

This creates a new version folder under sample-application/dist/. The version is named after version in the package.json file (having package.json version as 1.0 will generate sample-application/dist/1.0/).

2.4.4 Frontend location and version

If you want to use another name than sample-application you can change the folder in which the application server looks for the frontend. For example you might want to use some other name for the repository that holds your version of the frontend application. This can be changed in oskari-server/conf/Catalina/localhost/Oskari.xml (https://github.com/oskariorg/sample-configs/blob/master/tomcat-10/oskari-server/conf/Catalina/localhost/Oskari.xml) by changing the value of docBase:

<Context docBase="../../sample-application" reloadable="true" />

Note that the frontend code doesn't need to be server through the application server and could be served with servers like nginx or Apache HTTPD. However the server does have a configuration which version of the frontend it uses on oskari-server/lib/oskari-ext.properties https://github.com/oskariorg/sample-configs/blob/master/tomcat-10/oskari-server/lib/oskari-ext.properties:

oskari.client.version=dist/2.0.0

Where the version in oskari-ext.properties must match the folder where the frontend app build product was generated to (package.json version).

2.4.5 Simple frontend modifications and dev-server

An easy way of seeing a Hello world type of modification is adding something like console.log("Hello world") in the start() function of the SampleInfoBundleInstance.js.

Unfortunately any change to the frontend requires a build to be run to see the changes updated. To help with this the frontend offers the option to use Webpack dev-server by running npm run start instead of npm run build. The dev-server starts serving the frontend files from http://localhost:8081 and requires the server to respond from http://localhost:8080. It also requires that the server is configured to use this client version in oskari-server/lib/oskari-ext.properties (as opposed to version from package.json):

oskari.client.version=dist/devapp

Note! Changes to oskari-ext.properties requires the server to restart to take effect.

The dev-server provides the changed version after automatic page reloading so it's much more convenient to use for development than running the build after every change, but it's not perfect so if you don't see your changes you might need to restart the dev-server during development.

Frontend build details

The build scripts work by reading a main.js file that links all the functionality/bundles you want to use in your application together and should match the appsetup (bundle collection) used on the website you are creating including any dynamic (role-based) bundles that are added on the fly. So basically all the bundles you want to use in that application. Here's an example for the basic geoportal appsetup and for an embedded map. These are both processed when running npm run build. Note that linking the bundles to be part of the frontend application in main.js only includes the functionalities that CAN be used in an application. The server/database configurations dictates which of the functionalitise that have been included is actually started for a given application. This allows for example admin-bundles to be shown only when the user has the admin role, but also allows reusing the same frontend application to show different kinds of applications based on the database configuration. For example using the same embedded application for all different kinds of published maps where end-users can select through a browser-based UI which functionalities will be included in any given embedded map.

If you take a look at the package.json script for build you can see that the parameter --env appdef=applications is used to point the build to search for main.js files under the applications folder. You can change this in your own app as you wish.

The best point to start customizing your app is changing the main.js file under the sample geoportal application to only include the bundles that you are using. This reduces the amount of code the end-user needs to load. You can also safely remove the 3D applications if you don't need them. The embedded application (code for published maps) usually stays more or less the same and the geoportal one is usually customized based on requirements.

When changing main.js to include application specific bundles and/or customizing the application you need to run npm run build again to create new build product under the dist folder. You will also need to do this when updating the new version of Oskari or after changing any application specific code/bundles you want to use.

2.5 Setup Redis for Oskari (Optional)

Redis is used for caching data for example from statistical datasources to provide a cleaner user experience for statistical map functionalities (optional part of oskari-map webapp). It is also used in clustered environment (when you have multiple instances running an Oskari-based server) for session management (servers see sessions initiated by the other nodes) and cluster messaging like flushing caches from all nodes when something is updated on one node.

1) Get Redis

Install binaries from http://redis.io/ or from your platforms package repository.

2) Install

And startup redis-server. The default port Redis listens to is 6379.

3) Configure Oskari (Optional)

Oskari expects Redis to be found in the default port (6379) on the same server as Oskari ("localhost"). If you have it running on another host/port you need to change the oskari-ext.properties:

redis.hostname = localhost
redis.port = 6379

# # Credentials
# redis.user = (optional)
# redis.password = (optional)

# # Timeout configuration is milliseconds
# redis.timeout.connect = 2000
# redis.ssl = false
# redis.pool.size = 30

# # BlockWhenExhausted setting
# redis.blockExhausted = false

The commented ones are optional and depend on your environment. The values are the defaults (user/pass defaults are not defined).