How to automate app deployment

The most obvious way to deploy an app to a map.apps instance is to sign in to the map.apps Manager in a browser and create a new app. Then — if you already have an app as a zip file (hand-crafted or as the result of an app export) — you can upload the file creating a new app in the Manager.

This does not work in scenarios where a map.apps instance should be equipped with a set of apps without user interaction. One example is an automated map.apps setup, where the same set of standard apps should be deployed into a fresh map.apps instance.

Your options to deploy apps to map.apps
In this how-to…​
This guide demonstrates, how to use the automatic app import feature to deploy a zipped app, when map.apps starts up.

Checklist

To follow this guide you need:

  • map.apps 4.18+ installed

  • An app, as a zip file

  • Write access to the map.apps data directory location folder. Default is $HOME/.mapapps, i.e. the home folder of the Tomcat process owner.

  • Permission to start and stop Tomcat

Step 1: Preparing the app import folder

  1. Stop the Tomcat instance running map.apps.

  2. Create the folder app-import inside the map.apps data directory location.

  3. Copy the zip file that contains the app into the app-import folder.

You should now have a file structure similar to this:

.mapapps/
├── app-import/
│   └── myapp.zip
├── application.properties
└── ...

Step 2: Running the app import

  1. Start the Tomcat instance running map.apps.
    After the map.apps web app was deployed by Tomcat, it will instantly run the app import. In the Tomcat log output for map.apps, you will find the following lines (you need to enable the INFO log level):

    [INFO ] 2024-01-01T13:01:00,000 [SHARED_TIMER] de.conterra.appmgmt.appimport.ImportTask - Importing 1 app(s) from '/home/myuser/.mapapps/app-import'; override mode 'BASED_ON_MODIFIED_AT'; delete mode 'IMPORTED'
[INFO ] 2024-01-01T13:01:00,001 [SHARED_TIMER] de.conterra.appmgmt.appimport.Importer - App 'myapp': Imported app creating new one

  2. Sign in to the map.apps Manager as an admin user.
    You will now see the imported app in the list of apps.

Step 3 (optional): Updating an app

To update a previously imported app, follow these steps:

  1. Update the app zip file in the app-import folder, for example by adding a file to the zip or changing the contained app.json

  2. Stop the Tomcat instance running map.apps.

  3. Start the Tomcat instance running map.apps.
    In the Tomcat log output for map.apps, you will find the following lines (you need to enable the INFO log level):

    [INFO ] 2024-01-01T13:06:00,000 [SHARED_TIMER] de.conterra.appmgmt.appimport.ImportTask - Importing 1 app(s) from '/home/myuser/.mapapps/app-import'; override mode 'BASED_ON_MODIFIED_AT'; delete mode 'IMPORTED'
[INFO ] 2024-01-01T13:06:00,001 [SHARED_TIMER] de.conterra.appmgmt.appimport.Importer - App 'myapp': Imported app replacing existing one

Option: Multiple zip files and app folders

You can put any number of apps into the import folder, map.apps will import all of them automatically.

Apps don’t have to be provided as a zip file to get imported automatically, you can also put expanded app folders into the app-import folder. The folder below will prompt map.apps to import the apps yourapp and myapp.

.mapapps/
├── app-import/
│   ├── yourapp/
│   │   └── app.json
│   └── myapp.zip
└── application.properties

With the default settings an app, which is imported from an expanded app folder, is only updated if you modified its app.json file. To trigger an update when modifying, adding, or deleting other files of the app, you need to change the override mode.

Option: Use properties to configure the app

When an app is imported, properties from the app.json file inside the app are read by the import. You can use these properties to configure the app to be imported. All properties are optional.

Property Default value Description

title

App ID

The title of the app.

description

App ID

The description of the app.

editorState

DRAFT

The state of the app. Possible values are DRAFT, EDITED, VERIFIED, PUBLISHED and DEPRECATED.

sharedInGroups

[]

Array of groups the app is shared with. The app is shared with everyone if an empty array is used.

preoptimize

false

true, if the app should be pre-optimized when imported.

version

''

If you configured the override mode BASED_ON_VERSION and if this version does not match the version of an existing app with the same ID, the existing app is overridden by the import.
Example app.json
{
    "properties": {
        "title": "Sample app",
        "description": "A sample app",
        "editorState": "PUBLISHED",
        "sharedInGroups": ["usergroup-a", "usergroup-b", "maEditor", "maAdmin"],
        "preoptimize": true,
        "version": "1"
    }
    ...
}

Option: Override modes

The app import behavior can be adjusted regarding what happens when map.apps imports an app with an app ID that is already present in map.apps.

Use the map.apps configuration parameter appservice.appimport.override to specify how map.apps should act in that case:

  • NEVER: The existing app is not changed while the app to be imported is ignored.

  • ALWAYS: The existing app is overwritten even if the zip file or app.json (of an expanded folder) to be imported did not change or is older than the existing one.

  • BASED_ON_MODIFIED_AT (default): The existing app is only overwritten, if the zip file or app.json (of an expanded folder) the app to be imported has a newer modification date than the existing app on the server.

  • BASED_ON_VERSION: The existing app is overwritten if the property 'properties.version' inside the app.json (app properties) does not match.

Option: Delete modes

When you remove an app from the app import folder, it will be removed from the server the next time the app import is run.

Use the map.apps configuration parameter appservice.appimport.delete to specify what happens to an app that exists in map.apps but is not present in the app import folder.

  • NONE: An app is not deleted from the server, even if missing from the app import folder. All apps remain on the server.

  • IMPORTED (default): Only apps created or modified by the app import are deleted.

  • ALL: An app is deleted regardless of being imported or created manually. Only imported apps will remain in the application.

Other options

For other options to fine-tune the app import, check the appservice.appimport.* properties in the default-application.properties.