# Workingtitle "gemma"

//"gemma" is a working title and is likely to be changed.//


# Quick Start

## Build

- To build all components of gemma, simply type `make` on the top
  level directory of the repro.

- To build all components of gemma, with client in demo mode, use `make demo`.

- To only (re)build the back end you can use `make gemma`.

- To only build the SPA-Client you can use `make client`.

- To only build the SPA-Client in demo mode you can use `make clientdemo`.

Check [client/README](client/README.md) for details, especially
if you want to do a production setup.

For further details see [docs/DEVELOPMENT](docs/DEVELOPMENT.md).


## Running Tests

- Running database tests:

  * You will need a PostgreSQL cluster with PostGIS and pgTAP.
  * To run the tests use the script `./schema/run_tests.sh`.
  * `./schema/run_tests.sh --help` shows you available options.
    Per default the script will create (and drop if it already exists)
    a database named "gemma_test" and all necessary roles in the postgres
    default cluster (listening on port 5432) and run the tests
    in that database.
  * The script must be run as a user with PostgreSQL super user rights.
    By convention this is "postgres" on most systems.


## Setup Database

- You will need a PostgreSQL cluster with PostGIS.

- To install the **gemma** schema, roles and some default system configuration
  use the script
  `./schema/install-db.sh`.

- `./schema/install-db.sh --help` shows you available options.
  Per default the script will create a database named "gemma" and all
  necessary roles in the postgres default cluster (listening on port
  5432).

- The script must be run as a user with PostgreSQL super user rights.
  By convention this is the "postgres" on most systems.


## Setup GeoServer

- Install and run GeoServer as described here:
  http://docs.geoserver.org/stable/en/user/installation/

- Add addional tables you want to publish as OGC-Service Layers via GeoServer in
  the database. For example publish the bottleneck areas:
  ```
  INSERT INTO sys_admin.published_services (name, as_wfs) VALUES
    ('waterway.bottlenecks', true);
  ```
  In case your gemma is already running (see next section), restart it.
  Published WFS services will be available at `/api/internal/wfs`. Currently,
  the same layers will also be available as WMS services at
  `/api/internal/wms`, regardless of the value of `as_wms` in
  `sys_admin.published_services`.

## Running gemma

- Best is to create a configuration file.  Copy the example from
  `example_conf.toml` to get started:
  ```
  cp example_conf.toml gemma.toml
  ```

- Edit `gemma.toml`, some parameters you probably want to change:

  * `host` and `port` to make gemma listen on a public interface
  * `metamorph-db-password` to match the password for your database user
  * `geoserver-url`, `geoserver-user` and `geoserver-password` to match
     your instance of GeoServer

- `./cmd/gemma/gemma -h` gives you an overview of more available
  options.

- Then start gemma:
  ```
  ./cmd/gemma/gemma
  ```

## Adding default style templates for geoserver

- To add default style layers for geoserver run the script:
  ```
  ./style-templates/upload-styles.sh
  ```

- `./style-templates/upload-styles.sh --help` shows an overview of its options.


## Proxying OGC services through gemma

- Add services you want to publish via gemma (e.g. for same-origin policy
  compliance reasons) in the database. For example:
  ```
  INSERT INTO sys_admin.external_services (local_name, remote_url, is_wfs)
    VALUES ('d4d', 'https://service.d4d-portal.info/wamos/wfs', true);
  ```
  In case your gemma is already running (see previous section), restart it.
  The services will be available at `/api/external/${local_name}`, thus in
  the example given above: `/api/external/d4d`.

# License

//gemma// source code itself is licensed as Free Software
under GNU Affero GPL v>=3.
```
SPDX-License-Identifier: AGPL-3.0-or-later
```
See the specific source files
for details, the license itself can be found in the directory `LICENSES`.

To build a complete product, a number of other Free Software components
are used, which have their own licenses.

To get an overview about the components which are partly included
in the resulting production ready-product for the `client/`
use `yarn licenses`, e.g. like

```sh
yarn licenses list | grep '^├─ '
```

Additionally inspect `3rdpartylibs.sh` for Go components used
for the middleware and their licenses.

# Credits

Holder of the exclusive usage rights
(comparable to common-law's "copyright holder"):
```
SPDX-FileCopyrightText: 2018-2021 via donau – Österreichische Wasserstraßen-Gesellschaft mbH, Austria
```

Software-Engineering: Intevation GmbH, Germany