# Orchestrating Connectware with Ansible

This guide shows you how to use Ansible to set up and manage a local Connectware instance. You will learn how to deploy Connectware, install services, and manage the instance lifecycle using infrastructure as code.

## Prerequisites

Before starting, ensure you have the following installed on your system:

* **Ansible** (latest version)
* **Docker**
* **Docker Compose**
* **A valid Connectware license key**

This guide assumes you are familiar with:

* **Connectware** and its service concept
* **Docker fundamentals**
* **Ansible basics** ([ansible.com - Getting started with Ansible](https://docs.ansible.com/ansible/latest/getting_started/index.html))

## What is the Connectware Ansible Collection?

Ansible is an open-source infrastructure automation tool that enables infrastructure as code. Cybus provides a specialized Ansible Collection with custom modules designed to manage every aspect of Connectware deployments.

The collection provides the following modules to help you manage Connectware resources:

| Module     | Purpose                       |
| ---------- | ----------------------------- |
| `instance` | Manages Connectware instances |
| `service`  | Manages Connectware services  |
| `role`     | Manages Connectware roles     |
| `user`     | Manages Connectware users     |
| `agent`    | Manages agent instances       |

## Step 1 - Installing the Ansible Collection

* Install the Connectware Ansible Collection from Ansible Galaxy:

```bash
ansible-galaxy collection install cybus.connectware
```

### Verifying the Installation

```bash
ansible-galaxy collection list
```

### Updating an Existing Installation

```bash
ansible-galaxy collection install cybus.connectware --force
```

## Step 2 - Creating Your First Playbook

### Setting Up the Project

1. Create a new project directory:

{% code lineNumbers="true" %}

```bash
mkdir connectware-ansible-demo
cd connectware-ansible-demo
```

{% endcode %}

2. Create a playbook file named `playbook.yaml`:

{% code lineNumbers="true" %}

```yaml
---
- name: Connectware Deployment
  hosts: localhost

  tasks:
    - name: Deploy Connectware instance
      cybus.connectware.instance:
        license: 'YOUR_LICENSE_KEY_HERE'
        install_path: ./
```

{% endcode %}

**Important:** Replace `YOUR_LICENSE_KEY_HERE` with your actual Connectware license key.

### Understanding the Playbook Structure

* **Play**: "Connectware Deployment" runs on `localhost`
* **Task**: "Deploy Connectware instance" uses the `cybus.connectware.instance` module
* **Parameters**:
  * `license`: Your Connectware license (required)
  * `install_path`: Directory for deployment files (current directory)

### Exploring Module Options

* View all available parameters for the instance module:

{% code lineNumbers="true" %}

```bash
ansible-doc cybus.connectware.instance
```

{% endcode %}

## Step 3 - Deploying Connectware

Running this playbook will install and start Connectware on your local system, making it accessible via `https://localhost`.

* Execute the following playbook to deploy Connectware:

{% code lineNumbers="true" %}

```bash
ansible-playbook playbook.yaml
```

{% endcode %}

**Expected Output**

After running the playbook, you should see output like this:

{% code lineNumbers="true" %}

```bash
[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'

PLAY [Connectware Deployment] ***************************************************************************

TASK [Gathering Facts] ***************************************************************************
ok: [localhost]

TASK [Deploy Connectware] ***************************************************************************
changed: [localhost]

PLAY RECAP ***************************************************************************
localhost: ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
```

{% endcode %}

Notice that the state of the `Deploy Connectware` task is marked as `changed`. This indicates that Connectware is now running and is reachable at `https://localhost`.

In addition to the log output, you should now find two new files next to `playbook.yaml`. One is the Docker Compose file managing the Connectware containers, and the other contains additional configuration.

**Result**

* Connectware is now running and accessible at: `https://localhost`
* Two new files were created:
  * `docker-compose.yml`: Container orchestration file
  * A configuration file with additional settings

### Verifying Idempotency

* Run the playbook again to verify that no changes occur:

{% code lineNumbers="true" %}

```bash
ansible-playbook playbook.yaml
```

{% endcode %}

Notice the task shows `ok` instead of `changed`, confirming the desired state is maintained.

## Step 4 - Deploying a Service

### Creating a Service Definition

* Create a file named `example-service.yml` with a basic service configuration:

{% code lineNumbers="true" %}

```yaml
---
description: Example Service demonstrating MQTT connection

metadata:
  name: example_service

resources:
  mqttConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref Cybus::MqttHost
        port: !ref Cybus::MqttPort
        scheme: mqtt
        username: !ref Cybus::MqttUser
        password: !ref Cybus::MqttPassword
```

{% endcode %}

This service creates a connection to the internal Connectware MQTT broker.

### Updating the Playbook

* Add a service installation task to your `playbook.yaml`:

{% code lineNumbers="true" %}

```yaml
---
- name: Connectware Deployment
  hosts: localhost

  tasks:
    - name: Deploy Connectware instance
      cybus.connectware.instance:
        license: 'YOUR_LICENSE_KEY_HERE'
        install_path: ./

    - name: Install example service
      cybus.connectware.service:
        id: example_service
        commissioning_file: ./example-service.yml
```

{% endcode %}

### Service Module Parameters

These parameters let you uniquely identify your service and provide the service commissioning file, ensuring Connectware can correctly install and configure it.

* `id`: Unique identifier for the service (required)
* `commissioning_file`: Path to the service definition file (required)

Learn more about the service module:

```bash
ansible-doc cybus.connectware.service
```

### Deploying the Service

* Run the updated playbook:

```bash
ansible-playbook playbook.yaml
```

The output should show the service installation as `changed`. Verify the service is installed by visiting the Connectware UI at: `https://localhost/admin/#/services`.

## Step 5 - Managing Instance Lifecycle

### Stopping Connectware

* To stop the Connectware instance, add a task with the `stopped` state:

{% code lineNumbers="true" %}

```yaml
- name: Stop Connectware instance
  cybus.connectware.instance:
    state: stopped
    license: 'YOUR_LICENSE_KEY_HERE'
    install_path: ./
```

{% endcode %}

After running this playbook, Connectware will be stopped and no longer accessible.

### Available States

The instance module supports different states:

* `started` (default): Ensures Connectware is running
* `stopped`: Ensures Connectware is stopped
* `absent`: Removes the Connectware installation