npm package: @mapgear/geoapps-cli
Description: Provide the GeoApps CLI tools, used when building GeoApps apps
Author: MapGear B.V.
Latest version: 1.0.3

# GeoApps Command Line Interface (CLI)

 * [Using the GeoApps CLI](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli)
   * [init](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli-init)
   * [verify](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli-verify)
   * [serve](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli-serve)
   * [pack](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli-pack)
   * [publish](#geoapps-command-line-interface-(cli)-using-the-geoapps-cli-publish)
 * [Configuration](#geoapps-command-line-interface-(cli)-configuration)
 * [Changelog](#geoapps-command-line-interface-(cli)-changelog)
 * [Troubleshooting](#geoapps-command-line-interface-(cli)-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
```

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 `<filename>` is an optional parameter to specify an app package that can be published.

## 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:

| Command | Description |
| --- | --- |
|`debug` | The debug-property contains all the information about the app that is used when running `geoapps serve`. This is especially for develop and debugging-purposes of this app. Remark: any configuration specified in the `debug`-section is ignored by the `geoapps publish` command, you need to specify these parameters during publication of the app. |
|`package` | Within the `package`-section, you specify which data is part of the app that is packages using the `geoapps pack` and `geoapps publish` command.|

## Changelog

### 1.0.3
- Bugfix: Some urls for services were incorrectly routed to the remote GeoApps-instance, instead of the proxy that is provided through the CLI. By excluding the proxy, unauthorized requests were made causing layers not to render properly when used with the CLI.

### 1.0.2
- Bugfix: With latest releases of GeoApps, CORS headers were not correctly applied on specific internal requests to GeoApps. This release adds the CORS headers during debugging for the proxy-service to resolve this issue.

### 1.0.1
- Bugfix: Remove allowance of version 2 manifests through the CLI with GeoApps CLI version 1.0

### 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:
```json
{
    "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:
```json
{
    "$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 <file> 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://<tenant>/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.