generator-living-atlas/README.md

A Yeoman Generator for Living Atlas Ansible Inventories

# generator-living-atlas [![npm version](https://badge.fury.io/js/generator-living-atlas.svg)](https://badge.fury.io/js/generator-living-atlas)

> A Yeoman Generator for Living Atlas Ansible Inventories

* [Intro](#intro)
* [Installation](#installation)
* [Options](#options)
* [Screens](#screens)
* [Rerunning the generator](#rerunning-the-generator)
* [Ansible wrapper](#ansible-wrapper)
* [Sample ~/.ssh/config](#sample-sshconfig)
* [Maintain your inventories over time](#maintain-your-inventories-over-time)
* [Caveats](#caveats)
* [Any problem with this generator?](#any-problem-with-this-generator)
* [Development and Testing](#development-and-testing)
* [About Yeoman](#about-yeoman)
* [License](#license)


## Intro

This is a simple [yeoman](http://yeoman.io/) generator, so, just by asking some simple questions about your [Living Atlases](https://living-atlases.gbif.org/) Node, you will get a functional configuration for the setup of your Virtual Machines (VMs) using `ansible`.

The main goal of this utility is to allow you to configure, install & maintain a [Living Atlas](https://living-atlases.gbif.org/) infrastructure in a fast & smooth way.

In others words, with the `ansible` inventories produced by this `yeoman` generator and the [ala-install](https://github.com/AtlasOfLivingAustralia/ala-install/) `ansible` playbooks you should deploy the main LA services quickly and without too much pain.

Also, thanks to `yeoman`, you can rerun this generator, for instance, to enable new modules in the future, or to enable eg. SSL, etc. and reuse your previous settings and compare the differences (see the [screenshots](#screens)).

You can also use this generator via the [LA Toolkit](https://github.com/living-atlases/la-toolkit).

## Prerequisites

### node/npm

We assume you have pre-installed a recent version of [node.js](https://nodejs.org/), you can use for eg. https://www.npmjs.com/package/n to get update it.

### ala-install

You will need also to clone or download the [ala-install](https://github.com/AtlasOfLivingAustralia/) repository. We recommend to use the latest [release](https://github.com/AtlasOfLivingAustralia/ala-install/releases), for instance with:

```bash
git clone --depth 1 --branch v2.1.5 https://github.com/AtlasOfLivingAustralia/ala-install.git
```

### yeoman

Install [Yeoman](http://yeoman.io) and `generator-living-atlas` using [npm](https://www.npmjs.com/):

```bash
npm install -g yo
```
As this is a `yeoman` development environment you can get some `EPERM` or `EACCESS` errors, so check the [yeoman setup guide](https://yeoman.io/codelab/setup.html) for proper configuration.

### python docopt 

```
apt install python-docopt
```

## Installation

Later, install the LA generator itself:

```bash
npm install -g generator-living-atlas
```

Then generate your new LA project, just type:

```bash
yo living-atlas
```

and follow the questions.

## Options

- Use `yo living-atlas --replay` to reuse all the previous responses and regenerate the inventories with some new modifications (or improvements if you update this repo). More info below.
- Use `yo living-atlas --replay-dont-ask` if you only want to repeat the inventories generation (for instance, with a new version of this generator to get some update, or when you edit carefully the `../.yo-rc.json` answers file to, for instance, enable ssl or some service, and only want to regenerate the inventories with the changes).
- Also, you can use `--debug` to see some verbose debug info.

## Screens

A screen recording re-running the generator but using another solr hostname and switching to use SSL (see the differences in the generated inventories):

![](yo-living-atlas.gif)

After running the inventories following the instructions from the generated README over two VMs (like in the Paris 2019 Workshop):

![](after-running-inventories.png)

Using it for Tanzania demo session:

![](tz.png)

Differences beween two runs:

![](re-running-diff.png)

## Rerunning the generator

You can rerun the generator with the option `yo living-atlas --replay` to reuse all the previous responses and regenerate the inventories with some modifications (if for instance you want to add a new service, or use a new version of this generator with improvements or other **upgrades**).

With `--replay-dont-ask` you can regenerate the playbooks with previous answers without being asked again. This is useful for new versions of this generator, or if you manually edit `.yo-rc.json` where your answers are stored, or for automated processes (like CI integrations).

We recommend to override and set variables adding then to `quick-start-local-extras.ini` and `quick-start-spatial-local-extras.ini` without modification of the generated `quick-start-inventory.ini` and `quick-start-spatial-inventory.ini`, so you can rerun the generator in the future without losing local changes.  The `*-local-extras.sample` files will be updated with future versions of this generator, so you can compare from time to time these samples with your `*-local-extras.ini` files to add new vars, etc.

See the [changelog](https://github.com/living-atlases/generator-living-atlas/blob/master/CHANGELOG.md) for more upgrade details, new variables to take into account, etc.

## Ansible wrapper

Furthermore the utility `ansiblew` is generated. `ansiblew` is an `ansible-playbook` wrapper that can help you to use the inventories and can be easily modified by you to suit your needs. It depends on `python-docopt` package (`sudo apt install python-docopt` in debian and derivatives).

Help output:

```
$ ./ansiblew --help

This is an ansible wrapper to help you to exec the different playbooks with your
inventories.

By default don't exec anything only show the commands. With --nodryrun you can exec
the real commands.

With 'main' only operates over your main host.

Usage:
   ansiblew --alainstall=<dir_of_ala_install_repo> [options] [ main | collectory | ala_hub | biocache_service | ala_bie | bie_index | images | lists | regions | logger | solr | cas | biocache_backend | biocache_cli | spatial |  all ]
   ansiblew -h | --help
   ansiblew -v | --version

Options:
  --nodryrun             Exec the ansible-playbook commands
  -p --properties        Only update properties
  -l --limit=<hosts>     Limit to some inventories hosts
  -s --skip=<tags>       Skip tags
  -h --help              Show help options.
  -d --debug             Show debug info.
  -v --version           Show ansiblew version.
----
ansiblew 0.1.0
Copyright (C) 2019 living-atlases.gbif.org
Apache 2.0 License
```

So you can install the CAS service or the spatial service with simple commands like:

```bash
./ansiblew --alainstall=../ala-install cas --nodryrun
```

and

```bash
./ansiblew --alainstall=../ala-install spatial --nodryrun
```

or all the services with something like:

```bash
./ansiblew --alainstall=../ala-install all --nodryrun
```

Without `--nodryrun` you will get only the full `ansible-playbook` command to use these inventories .

## Docker Compose local deployment

For local container-based deployments using [la-docker-compose](https://github.com/living-atlases/la-docker-compose), `ansiblew` supports two additional flags:

- `--docker-local` — use the generated `*-dev-docker-inventory.ini` (all hosts mapped to `127.0.0.1`) instead of the standard `*-inventory.ini`
- `--ladocker=<dir>` — path to a local `la-docker-compose` repo; uses its playbooks (`config-gen.yml`, `site.yml`) instead of the per-service `ala-install` playbooks

Example — generate config and deploy all services locally:

```bash
./ansiblew --alainstall=../ala-install --ladocker=../la-docker-compose --docker-local --nodryrun all
```

Dry-run (shows command without executing):

```bash
./ansiblew --alainstall=../ala-install --ladocker=../la-docker-compose --docker-local all
```

The `*-dev-docker-inventory.ini` and `*-local-extras.ini` files are generated alongside the standard inventory. They include Docker container hostname overrides (e.g. `solr_host = la_solr`, `cas_db_hostname = la_mysql`) required by the `la-docker-compose` roles.

## Sample `~/.ssh/config`

A sample `dot-ssh-config.sample` is generated that you can edit and move to `~/.ssh/config` in orther to access to you VMs easily.

## Maintain your inventories over time

As we mentioned previously you can rerun the generator with the option `yo living-atlas --replay` to reuse all the previous responses and regenerate the inventories with some modifications (if for instance you want to add a new service, or use a new version of this generator with improvements).

## Caveats

- Currently running several services in the same machine and the same domain doesn't configure correctly `nginx` `vhosts`. See [this enhancement issue](https://github.com/AtlasOfLivingAustralia/ala-install/issues/256) in `ala-install`. **Workaround**: Use different hostnames per each service in the same machine. So, if for instance, `bie` and `bie-ws` are in the same machine, this machine receives multiple names (like `bie.example.org` and `bie-ws.example.org`) and `nginx` doesn't overwrite each service vhost configuration. See the [LA FAQ](https://github.com/AtlasOfLivingAustralia/documentation/wiki/FAQ) for more details.

## Any problem with this generator?

Please [add an issue](https://github.com/living-atlases/generator-living-atlas/issues/new) give us details of your problem and we'll try to help you and to improve the generator. Thanks!

## Development and Testing

If you want to contribute to this generator or run the tests:

1. Clone the repository and install dependencies:
   ```bash
   npm install
   ```
2. Run the tests using `npm test`. Since this project uses ES modules, you must provide the `--experimental-vm-modules` flag to Node (this is handled by the test script, but if you run jest directly use `NODE_OPTIONS="--experimental-vm-modules" npx jest`):
   ```bash
   npm test
   ```

## About Yeoman

 * [Learn more about Yeoman](http://yeoman.io/).

## License

Apache-2.0 © [Living Atlases](https://living-atlases.gbif.org)