# CliDesc

## dev install (lando)

1. install lando, docker-ce and docker-compose
2. $ git clone git@gitlab.catalyst.net.nz:SilverStripe/niwa-clidesc.git
3. $ cd niwa-clidesc
4. $ git checkout UPGRADE
5. $ lando start
6. $ lando composer install
7. $ cp .env.lando .env
8. $ lando build
9. $ lando test

## build package

1. complete at least steps 1 - 5 of the above "dev install (lando)"
2. acquire gitlab token with all read permissions: https://gitlab.catalyst.net.nz/SilverStripe/niwa-clidesc/-/settings/access_tokens
3. run: `lando package 1.0.0-rc1`

## usage

1. log into the cms
2. security > [your user]:
    - fill in all required fields
    - set all countries to 'samoa'
    - set all languages to 'english'
    - make sure you have permission to create and delete product instances
3. security > groups > users > bundles: add existsing "master"
4. in products > environments add new environment: name = "PHP8.1", runtime = "/usr/local/bin/php"
5. in products > generators add new generator:
    - set name: some
    - set description: some desc
    - set country applicable: Samoa
    - set category: general
    - set primary script: tools/png_output_script_v6.sh or tools/test-cli-script.php
    - set environment: sh or php
    - Make this product active: check
    - Show this product in menus: check
    - set Bundles: master
    - set station: none (if you have not yet created stations)
    - set additional args: `--csv test.csv` or `--filename test.png --csv test.csv`
    - set produced artefacts: none or test.png,test.csv
6. in jobs: run product generator initialisation jobs: 'initialising some'
7. in open layers > samoa:
    - set background to open streetmaps
    - go to Layers > Stations
    - set tag: stations
    - go to source: take note of the url
    - go to styles: set all styles to: type a
8. go to the frontend > classic view > click on 'some' and run
9. now that we have stations in the cms go to products > generators > some
10. switch stations to: multiple
11. in jobs re-run initialisation
12. in frontend re-run: some
13. done, explore frontend, check geojson url in the browser, etc

check ./gis/GetFeatures/Station.json in your browser, verify that you see generated stations.

## Compile fe distro

Provided you have node (e.g. v8.6.0), npm (e.g. 6.10.3), nvm (e.g. 0.39.3) and gulp (e.g. CLI 2.3.0, Local 3.9.1) installed:

```sh
cd themes/bootstarter
gulp
```

## Package

You will need (a) an up-to-date git tag and (b) a gitlab access token: https://gitlab.catalyst.net.nz/SilverStripe/niwa-clidesc/-/settings/access_tokens

Then run e.g.:

```sh
lando package 1.0.0-rc4
```

Install on a server with all required dependencies (Ubuntu 22.04, Apache2, PHP8.1, Postgres) installed, e.g.:

```sh
dpkg -i CliDESC_1.0.0-rc4.deb
```

Multi-host installer:

For an installation name 'somename' run:

```sh
sudo CLIDESC_INSTALL_NAME=somename dpkg -i CliDESC_1.0.0-rc4.deb
```

sudo -u postgres createdb "SS_some"
sudo -u postgres psql -c "grant all privileges on database \"SS_some\" to clidescdbadmin"


See .deb/.env.deb for db creds you have to use.

## Requirements for the target server

- Ubuntu 22.04 or equivalent Debian OS
- Apache2 (modules: rewrite)
- PHP8.1 (extensions: curl, dom, fileinfo, gd, hash, iconv, mbstring, pdo_pgsql, session, simplexml, tokenizer, xml)
- Postgres DB server 8.4+ (see .deb/.env.deb for db and user configuration)

Checkout the .target folder for more info.

## Mime types

To register mime types

1. add them to ./app/_config/mimevalidator.yml:

- SilverStripe\Assets\File::$allowed_extensions
- SilverStripe\Assets\File::$app_categories['scripts']
- SilverStripe\Control\HTTP::$MimeTypes
- SilverStripe\MimeValidator\MimeUploadValidator::$MimeTypes

2. add them to ./themes/bootstarter/templates/PublicAssetAdapter_HTAccess.ss

## Logging

A generic file logger is configured with the lowest log level (debug). To activate set CLIDESC_LOG_FILE in the .env file to a path relative to the ./public/ folder e.g. "../clidesc/log/app.log" or an absolute path.

This starts logging error, warnings and notices.

You can log anything you like in the PHP code, most likely in a controller action, e.g. ProductController::work(). For this we have added a convenience function `logger()`, which returns the logger. You can then call a method named after the log level you want to use (info, debug, notice, warning, error) and pass it a messgae string and optionally an array containing context, e.g.:

```
logger()->info("Product generator '{$generator->Name}' was run", [$generator->ID, $instance->ID]);
```