@mapgear/geoapps-cli v1.0.1

GeoApps Command Line Interface (CLI)

• Using the GeoApps CLI
  • init
  • verify
  • serve
  • pack
  • publish
• Configuration
• Changelog
• Troubleshooting

Using the GeoApps CLI

To get started with the GeoApps CLI, please install it as a global package. This can be done by entering the following command:

npm i -g @mapgear/geoapps-cli

To verify if the CLI is installed correctly, type geoapps in the command line. This should start the GeoApps CLI and show the implemented options

This GeoApps CLI package provides access to methods that simplifies developing apps for GeoApps. Within this command line interface, the following tools are provided:

• init
• verify
• serve
• pack
• publish

Init

With init, you generate a new manifest and local config file to get started with GeoApps Development. To run this command, you can use the following syntax:

geoapps init --only-config

With release of version 2.0 you are able to initialize V2 apps, blocks or extensions. In order to generate a manifest and a config file for different types, use the following syntax:

geoapps init --only-config --version <version> --type <type>

• Supported types are: app, block or extension.
• Support versions for apps are: 1.0 or 2.0.
• Supported versions for blocs or extensions are: 2.0.

In a future version, it will be possible to generate an extended configuration file or demo app using this command.

Verify

The verify tool can be used to verify the configured manifest file. Any validation errors are outputted so these can be resolved after modifying the file. To simplify the configuration of our configuration files, take also a look at our Visual Studio Code add-in: https://marketplace.visualstudio.com/items?itemName=mapgear.geoapps-vscode

geoapps verify

Serve

Serve starts a local development environment that can be used to test your app on the local development environment. To use serve, a tenant must be specified in the geoapps.json config file. When a token is also specified in this file, any request is made based on this token. The serve-command starts on port 8080 and 8081. It runs on 8080 your development app, and on 8081 it runs proxied access to the GeoApps environment that is specified. With the automatic addition of the token, you can access also protected resources.

To run the local development environment, it is necessary to use https-resources. To facilitate this, the GeoApps-cli automatically generates self signed certificates in the .geoapps folder in your project. It is required to allow this certificate in your browser when visiting the app in your browser in development mode.

geoapps serve

Pack

The pack-command allows you to pack the current app into a GeoApps app package which can be imported or distributed to be imported. The pack-command uses the manifest.yaml and the geoapps.json files to find out which files should be included in the app package. To verify if everything is added, you can inspect the final app package created by this command using any zip-utility.

geoapps pack <file>

In the above example, <file> is an optional argument. If it isn't specified, the GeoApps CLI will determine the filename based on the package.json name and version.

Publish

Use this command to publish your app to a GeoApps environment. To publish the app, internally is an app package being generated, which it automatically published to the specified tenant. The token that is specified must belong to a user with admin privileges to be able to publish the app.

geoapps publish --tenant <tenant>.geoapps.nl --token <token> <file>

In the above example, the <tenant> and <token> need to be replaced with your own information. The <file> is an optional parameter to specify an app package that can be published.

geoapps publish help opens the help message for publish.

Configuration

To configure the GeoApps CLI, you may use the geoapps.json configuration file. This json file will be auto-generated when using geoapps init. The following properties are available in this configuration file:

Changelog

2.0.1

• Bugfix: geoapps pack does not copy the existing resources folder, but creates a new, main resources folder where the manifest files are copied to.

2.0.0

We moved with this release to version 2.0 of the GeoApps CLI.

• Feature: Added support for V2 apps, blocks and extensions. All of these items have their own manifest verification.
• Feature: Added a help parameter on publish.
• Feature: Able to initialize a V2 app, block or extension. init generates a manifest and config file for the given type (app, block or extension) and version (1.0 or 2.0).
• Feature: Able to publish to (V2) apps, blocks or extensions.

1.0.0

We moved with this release to version 1.0 of the GeoApps CLI. Make sure you update your products to use the 1.0 version, instead of the pre-release versions.

• Bugfix: when the situation occurs that the token is expired or invalid, a clear error message is now returned.

0.7.1

• Enhancement: changed the processing of the access token used for debug. With GeoApps version 28.1, the handling of WFS services is changed, which caused the WFS layers not be loaded when using geoapps serve when these layers were not in a public map

0.7.0

• Enhancement: allow configuration of the web and proxy ports used by the CLI. This can be configured in the geoapps.json in the following way:

{
    "debug": {
        "ports": {
            "web": 8080,
            "proxy": 8081
        }
    }
}

• Enhancement: we published the schema of the geoapps.json config file. To get autocompletion and validation in the more advanced editors like Visual Studio Code, please update your geoapps.json with the $schema-property in the following way:

{
    "$schema": "https://raw.githubusercontent.com/mapgear/json-schemas/main/geoapps/cli-config.schema.json",
    "debug: { ... }
}

0.6.3

• Enhancement: added correct error message when invalid token is specified for connecting to GeoApps, used by geoapps serve and geoapps publish
• Bugfix: When a failure occur when using the CLI, the app did not report the exit-code correctly to the console. This caused for instance problems with the Azure DevOps tools not to detect a failure in the process

0.6.2

• Bugfix: fix geoapps pack when a non-existing directory is specified causing the output file not being generated

0.6.1

• Feature: Add support for <file>-parameter in the geoapps publish command, to make it possible to distribute an app package and publish it at a different moment.

0.6

• Feature: Add support to specify a specific output path for the pack command: geoapps pack <file> where is the output location

0.5.9

• Bugfix: geoapps serve inserted a wrong tenant url, causing the redirection service not to work correctly

0.5.8

• Bugfix: fix less file generation after refactor

0.5.7

• Bugfix: wrong dependency for UUID generation was used, causing validation errors

0.5.6

• Enhancement: add tenant check when running serve-method, to make sure that also the targeted tenant provide the expected capabilities
• Bugfix: improve the config file verification process during geoapps verify
• Bugfix: fix null value handling when no content directories are linked to the app package

0.5.5

• Bugfix: the geoapps.Initialize() api call coudn't recognized the tenant url specified in the geoapps.json config file, causing any api calls to fail.

0.5.4

• Bugfix: the geoapps serve-command didn't parse the less variables incorrect, which caused errors when starting when using branding variables.

0.5.3

• Bugfix: resolved an issue where refered files (e.g. stylesheets or javascript files) couldn't be loaded during local debug when the index.html was placed in a subfolder.
• Bugfix: resolved an issue with the geoapps serve-command exiting before launching the http services, preventing the usage of the local development mode
• Bugfix: resolved an issue that caused the geoapps serve to fail when no variables are specified for branding

0.5.2

• Bugfix: resolve an issue that a file was multiple times added in the zip file while executing geoapps pack. This issue occured when the main file specified in the manifest file was in a path that was also in the content dirs folder.

0.5.1

• Bugfix for the generated geoapps.json on geoapps init. If you have used this method before, replace the 'packages'-object in the file with 'package' (without an 's'), this was incorrect created

0.5.0

• Added support for geoapps publish
• Extended the verify command to verify also if the file paths are correct, the UUIDs are valid and not duplicated through the file and a default theme is specified
• Modified the init command to also generate the branding-section in the manifest.yaml
• Extended release notes of 0.4.1 and 0.4.2 as some changes were not correctly documented

0.4.2

• Resolves an issue where sometimes geoapps wasn't reconigzed in the command-line

0.4.1

• Extended the README with another troubleshooting section about powershell execution policies
• Added in the README the explanation for the pack-command
• Added update notifications, to inform you when a new version of the GeoApps CLI is available without checking by hand

0.4

• Automatically open the default browser when geoapps serve is executed. You can disable this option by setting the configuration value debug.browser.autoOpen to false in the geoapps.json config file

0.3

• Added support for geoapps init --only-config
• Updated Troubleshooting in the docs when using the CLI on windows with Chromium-based browsers

0.1

• Initial release

Known issues

• Sometimes the app import verifies the manifest.yaml correctly, but the publish fails due to an incorrect manifest. We are extending the verification-methods in the CLI and will resolve the issue as soon as possible.
• After running geoapps serve, sometimes the web service will exit automatically. To allow correct debugging, set autoOpen to false in the geoapps.json.

Roadmap

The following features is being worked on for the following updates of the CLI:

• geoapps serve --watch: Provides a watch mode to ease your development, which will reload configurations from your code without manually restarting your build services
• geoapps init: Full configuration of a basic app
• geoapps init --create-react-app: An integration with the create-react-app to easily create a new GeoApps-app based on the create-react-app template
• Extension of the verify-method: this resolves the mentioned known issue above

Troubleshooting

Edge or Chrome gives the message that the SSL-certificate is invalid

Visit the page chrome://net-internals/#hsts in your (Chromium-based) browser like the new Edge or Google Chrome. Locate on this page the section 'Delete domain security policies', and enter here in the input field the value 'localhost'. Click on the button 'Delete' and re-open your browser. After this, it should be possible to visit the app on your localhost-url without any additional configuration.

Running GeoApps results in a powershell exception about an unsigned script

To run the GeoApps-CLI, a powershell script is used on Windows computers. When running geoapps wont work but just results in an Powershell Exception, allow powershell to run unsigned scripts. This can be changed by running Set-ExecutionPolicy -Unrestricted. More details about the Execution Policy can be found here: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy.

Resource files aren't found while using the relative path ~/

The path ~/ is defined from the path where the manifest file is located. When you move for instance your html-files into a dist/-folder, it still requires the relative paths to be referenced to the ~/dist-folder. When using webpack, parcel, or any other packaging tool, this can be configured as the public url to be automatically replaced.

I received the message: FetchError: request to https:///api/version failed, reason: self signed certificate in certificate chain

This message shows up as NPM tries to connect with GeoApps. To connect to GeoApps, in the past it used an internal, self signed certificate. To resolve this issue, you need to tell NPM to stop using the self signed certificates. This can be done in one of the following ways:

1. Disable strict ssl

npm config set strict-ssl false

2. Disable the default CA of NPM to empty

npm config set ca=""

After changing these options, everything should work as expected. If the problem still persists, verify if NPM has access to the internet and isn't blocked by any (corporate) firewall.