How to get set up your Oskari development environment
1. GitHub, the collaboration platform
The Oskari source code is stored in several separate Git repositories hosted under the nls- oskari organization on GitHub.
The source code projects on GitHub also facilitate collaboration through hosting the project's external bug / ticket trackers.
Source code contributions to the project should be sent in as GitHub Pull Requests to the relevant repository's "develop" branch, according to the Git Flow branch policies.
Pull Requests and the merging thereof are amply documented in the GitHub documentation.
You will need to install
git and the Git Flow extension to actively participate to the development
1.1 Collaboration activities
Register a personal account at GitHub.
Fork the oskariorg/oskari and oskariorg/oskari-server repositories, and check out the source code from your forks to your local computer.
Read Atlassian's Git Flow documentation.
Create a new feature branch with
git flow feature start and publish/push it into your own GitHub
repository as a feature branch.
Please make sure to configure your Git tooling so that any new files, or changes to old files, use only UNIX End-Of-Line markers, and never DOS/Windows End-Of-Line markers.
A successfully installed Git Flow plugin can be validated by running the command line command
git flow version
1.2 Oskari source code
code. It assumes being served from webserver path /Oskari with a capital O so you can checkout the repository under the name
Oskari or configure the webserver to do this. The Jetty bundle is configured properly for this.
github.com/oskariorg/oskari-server contains the Oskari serverside code and
github.com/nls-oskari/oskari-liferay contains a Liferay 6.0.6 portlet replacement for the webapp in oskari-server.
Not all of the source code files contain a license header.
2. Software development tools
2.1 Java development tools
A large part of the Oskari software development process consists of adding new features to the backend server, using the Java development environment.
The principal tools necessary for Java development are:
- Java Development Kit (JDK) 8+
- Maven 3.2.x
- IntelliJ IDEA 14 Community
You will need to install those tools in the manner relevant to your development platform, principally Linux, Mac OS X or Windows with Cygwin.
For Java files, the project uses indentation of 4 spaces, and the so-called Sun-Style with the exception of maximum line length of 120 characters.
If you have never used IDEA before, you'll need to specifically register the JDK you previously installed as a development JDK, and explicitly set the project Java version to Java 8 from Project Structure settings, after opening the Maven parent projects.
2.2 Java development tools, validation
A properly installed Java Development Kit should report version 8, or some update version of it, in response to the command line command
Maven, on the other hand, should report both its own version, as well as the Java version, in reponse to the command line command
Therefore, a developer must install a platform-appropriate Node.js execution and runtime environment, along with the NPM package manager and Grunt build tool.
oskariorg/oskari-frontend repository currently has only Windows-specific build scripts,
but they are trivial, and can be translated into a
bash script suitable for Mac OS X and Linux
with a minimal effort.
The primary Oskari server components store their data on PostgreSQL 9.x databases, and perform some of the spatial analysis of the data on the database layer, using the PostGIS extension.
Some of the backend components (transport) cache map tiles on a Redis server.
Again, these components should be installed locally, in a platform-appropriate manner. On Linux,
yum, on Mac OS X using Homebrew, and on Windows, installer EXE or MSIs.
The PostGIS extension must be separately enabled on each database it is invoked on. Please follow the relevant documentation.
To validate a successful installation of these tools, use either the
psql command line tool, or a
GUI tool, if you prefer, to connect to the PostgreSQL server.
To validate a successful installation of PostGIS, use your connection to the PostgreSQL database to execute the PostGIS version query
Your Redis installation can be checked with the command line command
2.5 Application server - Jetty
The Oskari server builds into a WAR file executed inside a servlet runner.
A good servlet runner for development and production is Jetty 8 / 9, but the application can just as well be run on a properly configured Tomcat instance.
oskari-server/webapp-map Maven project doesn't currently have the
maven-plugin configured for running the application in an embedded container, but that should be
trivial to do for an active developer, who doesn't want to keep manually moving WAR files around to
The application configuration settings reside in the
oskari.properties configuration file in the
The servlet in the WAR will attempt to connect to a pre-existing PostgreSQL database using the
settings specified in the
2.6 Application server - Liferay 6.0.6
oskari-liferay/portlet-map-example portlet WAR requires a Liferay 6.0.6 instance to run,
specifically the Tomcat-integrated package.
Liferay needs its own configuration and user data database JNDI configuration, as well as the Oskari portlet application database JNDI connection. For development, you can use the same database for both sets of tables, if you like.
If your Liferay installation has a customized theme, as www.paikkatietoikkuna.fi has, make sure to install the theme WARs, as well as the layout WARs, as you're installing the map portlet.
2.7 GeoServer and customization components
Currently, the customized GeoServer configuration data directory can be found inside the
Jetty bundle under
oskari-server/geoserver-ext module collection contains various GeoServer extension
Maven projects, which need to be built according to the module documentation
referred to above (prebuilt on the Jetty bundle).
3. Configuring and building the service
3.1 Database creation and configuration
The PostgreSQL tools
createdb should be used to create a new database user
oskari with a password. These settings should also be transferred to your
After creating the database, you can manually populate it with tables and data, as described in the Oskari documentation or let the servlet do this for you.
The documentation for the process of upgrading the database is also worth going over.
3.2 Building the backend
The development build for the backend is compiled and run using Maven, as described in the development documentation.
Last modified: Tue Dec 19 2017 13:21:20 GMT+0200 (EET)