### Install Java SDK (Shell)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This command installs the Java Development Kit (version 1.7.0 openjdk-devel) required by Cygnus, which is based on Apache Flume. This is necessary for Cygnus to function correctly.

```shell
$ sudo yum install java-1.7.0-openjdk-devel
```

--------------------------------

### Execute Notification Example Script

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Makes the 'notification-example.sh' script executable and then runs it. This script simulates an NGSI-LD notification to be processed by Cygnus.

```bash
chmod 775 notification-example.sh
sh ./notification-example.sh
```

--------------------------------

### Install Cygnus Package (Shell)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This command installs the latest version of the Cygnus-ngsi package using the YUM package manager on CentOS/RedHat systems. Ensure the FIWARE release repository is configured prior to execution.

```shell
sudo yum install cygnus-ngsi
```

--------------------------------

### Configure FIWARE Release Repository (Shell)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This command downloads the FIWARE release repository configuration file to the system's package manager configuration directory. It is a prerequisite for installing Cygnus using the package manager.

```shell
sudo wget -P /etc/yum.repos.d/ https://nexus.lab.fiware.org/repository/raw/public/repositories/el/7/x86_64/fiware-release.repo
```

--------------------------------

### Run cygnus-ngsi Agent

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Starts the cygnus-ngsi agent using Apache Flume. This command requires specifying paths to configuration files and agent details. It also sets up logging and monitoring.

```bash
$ /opt/apache-flume-1.11.0/bin/cygnus-flume-ng agent --conf {{PATH-TO-CONF-FOLDER}} -f {{PATH-TO-AGENT-NGSI-CONF}} -n {{AGENT-NAME}} -p 5080 -Dflume.root.logger=INFO,LOGFILE -Duser.timezone=UTC -Dfile.encoding=UTF-8 -Dflume.monitoring.type= -Dflume.monitoring.port=41414

```

--------------------------------

### Start Cygnus-LD Services with Docker Compose

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Starts the Orion-LD, Cygnus, and PostgreSQL services using docker-compose. This command assumes a docker-compose.yml file is present in the current directory.

```bash
sudo docker-compose up
```

--------------------------------

### Access PostgreSQL Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Connects to the PostgreSQL container using Docker exec to access the database. This command requires `docker` to be installed and the container to be running.

```shell
sudo docker exec -it postgres-db psql -U postgres

```

--------------------------------

### Start Cygnus-NGSI-LD Docker Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

This command initiates a Cygnus-NGSI-LD agent container. The agent is responsible for receiving NGSI-like notifications and can be configured to persist data to various storage backends. Ensure Docker is installed and accessible.

```bash
$ docker run cygnus-ngsi-ld

```

--------------------------------

### Start Cygnus Test Agent (Command Line)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This command starts the Cygnus agent using the specified configuration file. It directs Flume's root logger to output INFO level logs to the console, allowing monitoring of the agent's activity.

```bash
$ /usr/cygnus/bin/cygnus-flume-ng agent --conf /usr/cygnus/conf/ -f /usr/cygnus/conf/agent_test.conf -n cygnus-ngsi -Dflume.root.logger=INFO,console

```

--------------------------------

### Starting FIWARE Services

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Command to start the Orion service within the configured Docker Compose environment. This command assumes the Docker Compose file is in the current directory.

```bash
./services orion

```

--------------------------------

### Setup Cygnus Agent Configuration Files

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Copies necessary configuration files for the Cygnus agent, including the Flume script, log4j properties, and name mappings. It also creates a log directory and assigns ownership to the 'cygnus' user.

```bash
$ cp fiware-cygnus/cygnus-common/target/classes/cygnus-flume-ng /opt/apache-flume-1.11.0/bin/
$ chmod +x /opt/apache-flume-1.11.0/bin/cygnus-flume-ng
$ cp fiware-cygnus/cygnus-common/conf/log4j2.properties.template /opt/apache-flume-1.11.0/conf/log4j2.properties
$ cp fiware-cygnus/cygnus-ngsi/conf/name_mappings.conf.template /opt/apache-flume-1.11.0/conf/name_mappings.conf
$ mkdir -p /var/log/cygnus
$ chown -R cygnus:cygnus /var/log/cygnus

```

--------------------------------

### Run cygnus-common Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Instructions for running the cygnus-common Docker image and observing its logs.

```APIDOC
## Run cygnus-common Container

### Description
Starts a cygnus-common container, which logs messages at the INFO level.

### Method
Docker Run Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
$ docker run cygnus-common
```

### Response
#### Success Response
Logs will be visible in the terminal, indicating the Cygnus agent is starting and a Jetty server is listening on port 5080.

#### Response Example
```
... time=2016-05-17T06:36:25.046UTC | lvl=INFO | ... | msg=com.telefonica.iot.cygnus.nodes.CygnusApplication[286] : Starting a Jetty server listening on port 5080 (Management Interface)
```
```

--------------------------------

### Simplest Cygnus Agent Configuration

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/configuration_examples

Configuration for the simplest Cygnus agent setup, involving a single HTTP source, a single channel, and a single sink. This example demonstrates the basic structure of the agent configuration file.

```properties
# declarations
cygnus-ngsi.sources = src
cygnus-ngsi.sinks = sink
cygnus-ngsi.channels = ch

# sources
cygnus-ngsi.sources.src.type = http
cygnus-ngsi.sources.src.channels = ch
cygnus-ngsi.sources.src.port = 5050
cygnus-ngsi.sources.src...

# sinks
cygnus-ngsi.sinks.sink.type = ...
cygnus-ngsi.sinks.sink.channel = ch
cygnus-ngsi.sinks.sink...

# channels
cygnus-ngsi.channels.ch.type = ...
cygnus-ngsi.channels.ch...

```

--------------------------------

### Run Cygnus Container with Volume and Environment Variable

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

This command demonstrates starting a Cygnus container with both a mapped configuration file via a volume and an environment variable to override the log level. This provides a way to customize container behavior externally.

```docker
docker run -v /absolute/path/to/local/agent.conf:/opt/apache-flume/conf/agent.conf -e LOG_LEVEL='DEBUG' cygnus-ngsi-ld
```

--------------------------------

### Install Certbot using Snap

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Installs Certbot, a tool for automatically issuing and renewing SSL certificates from Let's Encrypt. It ensures the necessary snapd components are present and updates the core snap.

```bash
sudo apt install snapd
sudo snap install core; sudo snap refresh core
sudo apt remove certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
```

--------------------------------

### Cygnus Twitter Agent Full Configuration Example

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-twitter/installation_and_administration_guide/configuration

A comprehensive example of a cygnus-twitter agent configuration file, demonstrating the setup of sources, sinks, and channels, including Twitter source parameters and HDFS sink channel association.

```properties
#=============================================
# To be put in APACHE_FLUME_HOME/conf/cygnus.conf
#
# General configuration template explaining how to setup a sink of each of HDFS.

#=============================================
# The next tree fields set the sources, sinks and channels used by Cygnus-twitter. You could use different names than the
# ones suggested below, but in that case make sure you keep coherence in properties names along the configuration file.
# Regarding sinks, you can use multiple types at the same time; the only requirement is to provide a channel for each
# one of them (this example shows how to configure 1 sink type). Even, you can define more than one
# sink of the same type and sharing the channel in order to improve the performance (this is like having
# multi-threading).
cygnus-twitter.sources = twitter-source
cygnus-twitter.sinks = hdfs-sink
cygnus-twitter.channels = hdfs-channel
#=============================================
# source configuration
# channel name where to write the notification events
cygnus-twitter.sources.twitter-source.channels = hdfs-channel
# source class, must not be changed
cygnus-twitter.sources.http-source.type = org.telefonica.iot.cygnus.sources.TwitterSource
# keywords
# cygnus-twitter.sources.twitter-source.keywords = keyword1, keyword2, keyword3
# Coordinates for filter query
cygnus-twitter.sources.twitter-source.south_west_latitude = 39.4247692
cygnus-twitter.sources.twitter-source.south_west_longitude = -0.4315448
cygnus-twitter.sources.twitter-source.north_east_latitude = 39.5038788
cygnus-twitter.sources.twitter-source.north_east_longitude = -0.3124204
cygnus-twitter.sources.twitter-source.consumerKey = xxxxxxxx
cygnus-twitter.sources.twitter-source.consumerSecret = xxxxxxxx
cygnus-twitter.sources.twitter-source.accessToken = xxxxxxxx
cygnus-twitter.sources.twitter-source.accessTokenSecret = xxxxxxxx

# ============================================
# NGSIHDFSSink configuration
# channel name from where to read notification events
cygnus-twitter.sinks.hdfs-sink.channel = hdfs-channel
```

--------------------------------

### Export JAVA_HOME Environment Variable (Shell)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This command sets the JAVA_HOME environment variable to the installation path of the Java SDK. This is crucial for applications like Cygnus that depend on a correctly configured Java environment. For permanent changes, edit system or user profile files.

```shell
$ export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk.x86_64
```

--------------------------------

### Configure Java Home and Path

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Sets the JAVA_HOME environment variable and adds the Java binary directory to the system's PATH. This allows the system to locate and use the installed Java Development Kit.

```bash
$ nano .bashrc
$ export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
$ export PATH=$PATH:$JAVA_HOME

```

--------------------------------

### Build and Install cygnus-common

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Compiles, packages, and installs the cygnus-common module. It also copies the generated JAR file to the Flume plugin directory and registers it with Maven.

```bash
$ cd fiware-cygnus/cygnus-common
$ mvn -B -T8 clean compile exec:exec assembly:single
$ cp target/cygnus-common-3.6.0-SNAPSHOT-jar-with-dependencies.jar /opt/apache-flume-1.11.0/plugins.d/cygnus/libext/
$ mvn install:install-file -Dfile=/opt/apache-flume-1.11.0/plugins.d/cygnus/libext/cygnus-common-3.6.0-SNAPSHOT-jar-with-dependencies.jar -DgroupId=com.telefonica.iot -DartifactId=cygnus-common -Dversion=3.6.0-SNAPSHOT -Dpackaging=jar -DgeneratePom=false

```

--------------------------------

### Clone fiware-cygnus repository with Git

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

This command clones the fiware-cygnus project from GitHub. It requires Git to be installed and configured on the user's system. The output is the project files in the current directory.

```bash
git clone https://github.com/telefonicaid/fiware-cygnus.git

```

--------------------------------

### List Schemas in PostgreSQL

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

A PostgreSQL command to list all available schemas in the database. This helps in identifying the schema where data is stored.

```sql
\dn
```

--------------------------------

### Clone and Checkout fiware-cygnus Repository

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Clones the fiware-cygnus project from GitHub and checks out a specific branch. It's important to select a stable release branch for production environments.

```bash
$ git clone https://github.com/telefonicaid/fiware-cygnus.git
$ cd fiware-cygnus
$ git checkout <branch>

```

--------------------------------

### List PostgreSQL Schemas

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Lists all schemas within the PostgreSQL database. This is a psql command executed after connecting to the database.

```sql
\dn

```

--------------------------------

### GET /v1/version

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Retrieves the version of the Cygnus agent running in the container.

```APIDOC
## GET /v1/version

### Description
Retrieves the version information of the Cygnus agent.

### Method
GET

### Endpoint
`/v1/version`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
$ curl "http://172.17.0.8:5080/v1/version"
```

### Response
#### Success Response (200)
- **success** (string) - Indicates if the request was successful.
- **version** (string) - The version of the Cygnus agent.

#### Response Example
```json
{
  "success": "true",
  "version": "1.0.0_SNAPSHOT.d7cfee4455a59a1854cc53f37e16ff4866b26010"
}
```
```

--------------------------------

### Clone FIWARE LD Subscriptions Tutorial Repository

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Clones the Git repository for the FIWARE LD Subscriptions and Registrations tutorial. This is the initial step to obtain the necessary configuration files.

```shell
git clone https://github.com/FIWARE/tutorials.LD-Subscriptions-Registrations.git
cd tutorials.LD-Subscriptions-Registrations/docker-compose

```

--------------------------------

### Clone Cygnus Repository

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Clones the fiware-cygnus repository from GitHub to the local machine. This is the first step to obtain the necessary project files for setting up Cygnus-LD.

```bash
git clone https://github.com/ging/fiware-cygnus.git
```

--------------------------------

### Cygnus Instance Configuration File Example

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/configuration_examples

This snippet shows the content of the main configuration file for a Cygnus instance, specifying user, configuration paths, agent name, and logging details.

```bash
$ cat /usr/cygnus/conf/cygnus_instance_all.conf
CYGNUS_USER=cygnus
CONFIG_FOLDER=/usr/cygnus/conf
CONFIG_FILE=/usr/cygnus/conf/agent_all.conf
AGENT_NAME=cygnus-ngsi
LOGFILE_NAME=cygnus.log
ADMIN_PORT=5080
POLLING_INTERVAL=30
```

--------------------------------

### Example Response: Valid Instance Configuration

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

A sample JSON response indicating a successful retrieval of all parameters for a Cygnus instance. It details various configuration settings.

```JSON
{
  "success": "true",
  "result": {
    "instance": {
      "CONFIG_FILE": "\/usr\/cygnus\/conf\/agent.conf",
      "AGENT_NAME": "cygnus-common",
      "ADMIN_PORT": "5080",
      "CONFIG_FOLDER": "\/usr\/cygnus\/conf",
      "LOGFILE_NAME": "cygnus.log",
      "CYGNUS_USER": "cygnus",
      "POLLING_INTERVAL": "30"
    }
  }
}
```

--------------------------------

### Run Cygnus Common Docker Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Starts a Docker container using the cygnus-common image. This command initiates the Cygnus agent, which by default runs a logger-sink to log messages at the INFO level. The output will show the agent starting up and logging traces.

```shell
$ docker run cygnus-common

```

--------------------------------

### View Running Docker Containers

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_with_docker

Lists all currently running Docker containers. This command is useful to verify that the cygnus-ngsi container has started successfully and to obtain its container ID.

```bash
$ docker ps
```

--------------------------------

### Run cygnus-ngsi Docker Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_with_docker

Starts a cygnus-ngsi Docker container. This container is responsible for receiving NGSI-like notifications and persisting them. It can be configured to work with various storage backends.

```bash
$ docker run cygnus-ngsi
```

--------------------------------

### Check Created NGSI-LD Subscriptions

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Uses curl to send a GET request to retrieve all existing NGSI-LD subscriptions configured in the context broker. This is useful for verifying that subscriptions have been created successfully.

```bash
curl -L -X GET 'http://localhost:1026/ngsi-ld/v1/subscriptions/'

```

--------------------------------

### Basic Cygnus Configuration with Single Source, Sink, and Channel

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/performance_tips

Illustrates a fundamental Cygnus setup with a single source, a single channel, and a single sink. This serves as a baseline for understanding more complex parallel configurations.

```properties
cygnus-ngsi.sources = mysource
cygnus-ngsi.sinks = mysink
cygnus-ngsi.channels = mychannel

cygnus-ngsi.sources.mysource.type = ...
cygnus-ngsi.sources.mysource.channels = mychannel
... other source configurations...

cygnus-ngsi.channels.mychannel.type = ...
... other channel configurations...

cygnus-ngsi.sinks.mysink.type = ...
cygnus-ngsi.sinks.mysink.channel = mychannel
... other sink configurations...
```

--------------------------------

### Docker Run Example with PostgreSQL Password Secret

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

Demonstrates how to run a Fiware Cygnus container, mounting a Docker secret for the PostgreSQL password. This method is preferred for handling sensitive credentials securely.

```bash
docker run --name some-cygnus -e CYGNUS_POSTGRESQL_PASS_FILE=/run/secrets/postgresql-root -d fiware/cygnus-ngsi-ld:tag
```

--------------------------------

### Example Response: Instance Configuration File Not Found

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

A sample JSON response indicating that the instance configuration file could not be found at the specified path.

```JSON
{
  "success": "false",
  "result": {
    "File not found in the path received"
  }
}
```

--------------------------------

### Sample Cygnus Instance Configuration File

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

This is a sample configuration file for a Cygnus instance, illustrating various parameters like the configuration file path, agent name, administration port, log file settings, and polling interval. This file serves as a reference for understanding the structure and content of Cygnus configurations.

```INI
#####
# Copyright 2016 Telefonica Investigación y Desarrollo, S.A.U
#
# This file is part of fiware-cygnus (FI-WARE project).
#
# fiware-cygnus is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General
# Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any
# later version.
# fiware-cygnus is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
# details.
#
# You should have received a copy of the GNU Affero General Public License along with fiware-cygnus. If not, see
# http://www.gnu.org/licenses/.
#
# For those usages not covered by the GNU Affero General Public License please contact with iot_support at tid dot es

# Which is the config file
CONFIG_FILE=/usr/cygnus/conf/agent.conf

# Name of the agent. The name of the agent is not trivial, since it is the base for the Flume parameters
# naming conventions, e.g. it appears in .sources.http-source.channels=...
AGENT_NAME=cygnus-common

# Administration port. Must be unique per instance
ADMIN_PORT=5080

# Where is the config folder
CONFIG_FOLDER=/usr/cygnus/conf

OLD_CONFIG=true

# Name of the logfile located at /var/log/cygnus. It is important to putthe extension '.log' in order to the log rotation works properly
LOGFILE_NAME=cygnus.log

# Who to run cygnus as. Note that you may need to use root if you want
# to run cygnus in a privileged port (<1024)
CYGNUS_USER=cygnus

# Polling interval (seconds) for the configuration reloading
POLLING_INTERVAL=30

```

--------------------------------

### Pull fiware/cygnus-ngsi Docker Image from Docker Hub

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_with_docker

This command downloads the latest 'cygnus-ngsi' image from the Docker Hub registry. This is an alternative to building the image from sources, allowing for quicker setup.

```shell
docker pull fiware/cygnus-ngsi
```

--------------------------------

### View Running Docker Containers

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Lists all currently running Docker containers. This command is useful to verify that the cygnus-common container has started successfully and to obtain its CONTAINER ID and NAME for subsequent operations.

```shell
$ docker ps

```

--------------------------------

### Docker Compose Configuration for FIWARE Services

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Defines the services, networks, and volumes for a FIWARE environment, including Orion LD, MongoDB, PostgreSQL, and a tutorial application. This configuration is managed by Docker Compose.

```yaml
version: "3.5"
services:
  # Orion LD is the context broker
  orion:
    image: fiware/orion-ld:${ORION_LD_VERSION}
    hostname: orion
    container_name: fiware-orion-ld
    depends_on:
      - mongo-db
    networks:
      - default
    ports:
      - "${ORION_LD_PORT}:${ORION_LD_PORT}" # localhost:1026
    command: -dbhost mongo-db -logLevel DEBUG -t 255
    healthcheck:
      test: curl --fail -s http://orion:${ORION_LD_PORT}/version || exit 1


  # Databases
  mongo-db:
    image: mongo:${MONGO_DB_VERSION}
    hostname: mongo-db
    container_name: db-mongo
    expose:
      - "${MONGO_DB_PORT}"
    ports:
      - "${MONGO_DB_PORT}:${MONGO_DB_PORT}" # localhost:27017
    networks:
      - default
    command: --nojournal
    volumes:
      - mongo-db:/data

  postgres-db:
       hostname: postgres-db
       container_name: postgres-db
       image: postgres
       restart: always
       ports:
         - "5432:5432"
       environment:
         POSTGRES_PASSWORD: example

  cygnus-ld:
       hostname: cygnus-ld
       container_name: cygnus-ld
       image: anmunozx/cygnus-ld
       environment:
         CYGNUS_POSTGRESQL_HOST: postgres-db
         CYGNUS_POSTGRESQL_PASS: example
         CYGNUS_POSTGRESQL_USER: postgres
         CYGNUS_POSTGRESQL_DATA_MODEL: dm-by-entity
       ports: 
         - "5050:5050"


  # Tutorial displays a web app to manipulate the context directly
  tutorial:
    image: fiware/tutorials.context-provider
    hostname: tutorial
    container_name: fiware-tutorial
    depends_on:
      - orion
    networks:
      default:
        aliases:
          - iot-sensors
          - context-provider
    expose:
      - "${TUTORIAL_APP_PORT}" # localhost:3000
      - "${TUTORIAL_DUMMY_DEVICE_PORT}" # localhost:3001
    ports:
      - "${TUTORIAL_APP_PORT}:${TUTORIAL_APP_PORT}" # localhost:3000
      - "${TUTORIAL_DUMMY_DEVICE_PORT}:${TUTORIAL_DUMMY_DEVICE_PORT}" # localhost:3001
    environment:
      - "DEBUG=tutorial:*"
      - "WEB_APP_PORT=${TUTORIAL_APP_PORT}" # Port used by the content provider proxy and web-app for viewing data
      - "NGSI_VERSION=ngsi-ld"
      - "CONTEXT_BROKER=http://orion:${ORION_LD_PORT}/ngsi-ld/v1" # URL of the context broker to update context
      - "DEVICE_BROKER=http://devices:${ORION_EDGE_PORT}/v2" # URL of the device's context broker to update context
      - "NGSI_LD_PREFIX=urn:ngsi-ld:"

      - "IOTA_HTTP_HOST=iot-agent"
      - "IOTA_HTTP_PORT=${IOTA_SOUTH_PORT}"
      - "DUMMY_DEVICES_PORT=${TUTORIAL_DUMMY_DEVICE_PORT}" # Port used by the dummy IOT devices to receive commands
      - "DUMMY_DEVICES_TRANSPORT=HTTP" # Default transport used by dummy Io devices

      - "OPENWEATHERMAP_KEY_ID=<ADD_YOUR_KEY_ID>"
      - "TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>"
      - "TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>"
    healthcheck:
      test: curl --fail -s http://tutorial:${TUTORIAL_APP_PORT}/version || exit 1

networks:
  default: ~

volumes:
  mongo-db: ~

```

--------------------------------

### Execute Notification Script (Bash)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

These commands provide execution permissions for the `notification.sh` script and then run it, passing the Cygnus HTTP source URL as an argument. This action triggers the sending of the simulated Orion notification.

```bash
$ chmod a+x notification.sh
$ ./notification.sh http://localhost:5050/notify

```

--------------------------------

### Run Cygnus Container with Volume Mapping

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

This command starts a Cygnus container, mapping a local agent configuration file to the container's configuration directory using a Docker volume. This allows for external configuration management.

```docker
docker run -v /absolute/path/to/local/agent.conf:/opt/apache-flume/conf/agent.conf cygnus-ngsi-ld
```

--------------------------------

### Docker Run Example for PostgreSQL User and Password

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

Illustrates how to configure custom PostgreSQL user and password for the Cygnus sink by setting CYGNUS_POSTGRESQL_USER and CYGNUS_POSTGRESQL_PASS environment variables during container execution. This is useful when the default credentials are not applicable.

```bash
docker run -e CYGNUS_POSTGRESQL_USER='myuser' -e CYGNUS_POSTGRESQL_PASS='mypass' cygnus-ngsi-ld
```

--------------------------------

### Docker Run Example to Change Log Level

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

Shows how to override the default log4j logging level by setting the CYGNUS_LOG_LEVEL environment variable when running the Cygnus Docker container. This allows for dynamic adjustment of logging verbosity.

```bash
docker run -e CYGNUS_LOG_LEVEL='DEBUG' cygnus-ngsi-ld
```

--------------------------------

### Clone fiware-cygnus Repository

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_with_docker

This command clones the fiware-cygnus repository from GitHub to your local machine. This is the first step in building the Docker image from sources.

```shell
git clone https://github.com/telefonicaid/fiware-cygnus.git
```

--------------------------------

### HttpBackend Constructor

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/backends_catalogue/http_backend

Initializes the HttpBackend with connection and security configurations. It requires host, port, SSL/Kerberos settings, Kerberos credentials and configuration files, and connection pool sizes.

```java
public HttpBackend(String host, String port, boolean ssl, boolean krb5, String krb5User, String krb5Password, String krb5LoginConfFile, String krb5ConfFile, int maxConns, int maxConnsPerRoute)
```

--------------------------------

### Set Environment Variable in Docker

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Demonstrates how to set environment variables for a Docker container using the '-e' flag. This is useful for configuring application parameters such as logging levels. The example shows setting the LOG_LEVEL to 'DEBUG' for the 'cygnus-common' container.

```shell
docker run -e LOG_LEVEL='DEBUG' cygnus-common
```

--------------------------------

### Cygnus Component Initialization Log

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/sanity_checks

These log entries show the creation and startup of Cygnus components, specifically an HTTP source and its associated handler. This is part of the process where Cygnus configures its data ingestion mechanisms.

```log
time=2016-05-09T09:50:33.511CEST | lvl=INFO | corr= | trans= | svc= | subsvc= | function=create | comp=cygnus-ngsi | msg=org.apache.flume.source.DefaultSourceFactory[39] : Creating instance of source http-source, type org.apache.flume.source.http.HTTPSource
time=2016-05-09T09:50:33.727CEST | lvl=INFO | corr= | trans= | svc= | subsvc= | function=configure | comp=cygnus-ngsi | msg=com.telefonica.iot.cygnus.handlers.NGSIRestHandler[145] : Startup completed

```

--------------------------------

### Get Docker Container IP Address

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Retrieves detailed information about a specific Docker container, identified by its CONTAINER ID. The output is filtered to show only the IP address assigned to the container, which is necessary for accessing the container's services.

```shell
$ docker inspect c88bc1b66cdc | grep "IPAddress"

```

--------------------------------

### NGSIDynamoDBSink start Method

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/flume_extensions_catalogue/ngsi_dynamodb_sink

The `start` method is responsible for initializing the `DynamoDBBackend` implementation. This method is called after the constructor and `configure` method, ensuring that the backend is ready before data processing begins.

```java
public void start();
```

--------------------------------

### Query Cygnus Agent Version via API

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_with_docker

Sends an HTTP GET request to the Cygnus agent's management interface to retrieve its version information. Requires the container's IP address and the management port (default 5080).

```bash
$ curl "http://172.17.0.13:5080/v1/version"
```

--------------------------------

### Example Response: Parameter Not Found

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

A sample JSON response indicating that the requested parameter was not found within the instance configuration file.

```JSON
{
  "success": "false",
  "result": {
    "Param 'CONFIG_FOLDER_FILE' not found in the instance"
  }
}
```

--------------------------------

### Install Maven Build Tool

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Installs the Apache Maven build automation tool on Debian-based systems. Maven is required for compiling and packaging the Cygnus project components.

```bash
$ sudo apt-get -y install maven

```

--------------------------------

### Download and Install Apache Maven

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_from_sources

Downloads, extracts, and installs Apache Maven. The installation directory should be referenced by the APACHE_MAVEN_HOME environment variable. This step is crucial for building Java projects like cygnus-common.

```shell
$ wget https://archive.apache.org/dist/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.tar.gz
$ tar xzvf apache-maven-3.6.3-bin.tar.gz
$ mv apache-maven-3.6.3 APACHE_MAVEN_HOME
```

--------------------------------

### Install Java JDK 17 on Debian

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Installs the OpenJDK 17 Java Development Kit and Runtime Environment on Debian-based systems. This is a prerequisite for compiling and running Cygnus.

```bash
$ sudo apt-get -y install openjdk-17-jdk openjdk-17-jdk-headless openjdk-17-jre openjdk-17-jre-headless

```

--------------------------------

### Build Cygnus-twitter Fat JAR with Maven

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-twitter/quick_start_guide

This command builds a fat Java JAR file for Cygnus-twitter, including all third-party dependencies. It's recommended for deployment and places the JAR into the Flume plugins directory.

```bash
cd cygnus-twitter
APACHE_MAVEN_HOME/bin/mvn clean compile exec:exec assembly:single
cp target/cygnus-twitter-<x.y.z>-jar-with-dependencies.jar APACHE_FLUME_HOME/plugins.d/cygnus/lib
```

--------------------------------

### POST /admin/configuration/instance

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

Posts a single configuration parameter to a Cygnus instance. The path to the configuration file, parameter name, and value are required.

```APIDOC
## POST /admin/configuration/instance

### Description
Posts a single parameter if it doesn't exist in the instance given the path to the configuration file as the URI within the URL and the name and the value of the parameter as a query parameters. The path to the instance must be with `/usr/cygnus/conf`.

### Method
POST

### Endpoint
`http://<cygnus_host>:<management_port>/admin/configuration/instance/usr/cygnus/conf/cygnus_instance.conf?param=<param_name>&value=<param_value>`

### Query Parameters
- **param** (string) - Required - The name of the parameter to set.
- **value** (string) - Required - The value to set for the parameter.

### Request Body
None

### Request Example
```
POST "http://<cygnus_host>:<management_port>/admin/configuration/instance/usr/cygnus/conf/cygnus_instance.conf?param=<param_name>&value=<param_value>"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **result** (object) - Contains the updated instance configuration if successful.

#### Response Example
```json
{
  "success": "true",
  "result": {
    "instance": {
      "CONFIG_FILE": "\/usr\/cygnus\/conf\/agent.conf",
      "AGENT_NAME": "cygnus-common",
      "ADMIN_PORT": "5080",
      "CONFIG_FOLDER": "\/usr\/cygnus\/conf",
      "ADMIN_PORT_2": "5081",
      "LOGFILE_NAME": "cygnus.log",
      "CYGNUS_USER": "cygnus",
      "POLLING_INTERVAL": "30"
    }
  }
}
```

#### Error Responses
- **400 Bad Request**: Invalid path for an instance configuration file.
- **409 Conflict**: Existing value in the instance configuration file.
- **404 Not Found**: Instance configuration file not found.
```

--------------------------------

### Access PostgreSQL and Verify Data

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Executes the PostgreSQL client inside the running postgres-db container. This allows for direct interaction with the database to verify schema and data.

```bash
sudo docker exec -it postgres-db psql -U postgres
```

--------------------------------

### Query Cygnus Common Version via API

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Sends an HTTP GET request to the Cygnus common container's management interface to retrieve its version information. This requires the container's IP address and uses `curl` to interact with the `/v1/version` endpoint.

```shell
$ curl "http://172.17.0.8:5080/v1/version"

```

--------------------------------

### Configure Cygnus-LD Docker Service

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/quick_start_guide

Defines a Docker service for Cygnus-LD within a docker-compose file. It includes essential environment variables for connecting to PostgreSQL and setting the data model.

```yaml
  cygnus-ld:
     hostname: cygnus-ld
     container_name: cygnus-ld
     image: anmunozx/cygnus-ld
     environment:
       CYGNUS_POSTGRESQL_HOST: postgres-db
       CYGNUS_POSTGRESQL_PASS: example
       CYGNUS_POSTGRESQL_USER: postgres
       CYGNUS_POSTGRESQL_DATA_MODEL: dm-by-entity
     ports: 
       - "5050:5050"

```

--------------------------------

### Build Cygnus-twitter Thin JAR with Maven

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-twitter/quick_start_guide

This command builds a thin Java JAR file for Cygnus-twitter. It requires external dependencies to be managed separately and places the JAR into the Flume plugins directory.

```bash
cd cygnus-twitter
APACHE_MAVEN_HOME/bin/mvn exec:exec package
cp target/cygnus-<x.y.z>.jar APACHE_FLUME_HOME/plugins.d/cygnus/lib
```

--------------------------------

### SQLBackend Interface Methods

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/backends_catalogue/sql_backend

This section defines the methods that any SQL backend implementation must expose. It includes methods for creating databases and tables, and for inserting context data into tables.

```java
void createDatabase(String destination) throws Exception;
```

```java
void createTable(String destination, String tableName, String fieldNames) throws Exception;
```

```java
insertContextData(String destination, String tableName, String fieldNames, String fieldValues) throws Exception;
```

--------------------------------

### Combine Volumes and Environment Variables in Docker

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Shows how to combine Docker volume mapping with environment variable overwriting in a single 'docker run' command. This allows for simultaneous configuration through file mapping and direct parameter setting. The example maps a local configuration file and sets the LOG_LEVEL.

```shell
docker run -v /absolute/path/to/local/agent.conf:/opt/apache-flume/conf/agent.conf -e LOG_LEVEL='DEBUG' cygnus-common
```

--------------------------------

### Build and Install cygnus-ngsi

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/installation_and_administration_guide/install_from_sources

Compiles and packages the cygnus-ngsi module, then copies the resulting JAR file into the Flume plugins directory. This makes the ngsi functionality available to Flume.

```bash
$ cd fiware-cygnus/cygnus-ngsi
$ mvn -B -T8 clean compile exec:exec assembly:single
$ cp target/cygnus-ngsi-3.6.0-SNAPSHOT-jar-with-dependencies.jar /opt/apache-flume-1.11.0/plugins.d/cygnus/lib/

```

--------------------------------

### Configure Cygnus Test Agent (Flume Conf)

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi/quick_start_guide

This configuration file defines the components of a Cygnus test agent, including an HTTP source to listen for Orion notifications, a memory channel to buffer events, and a test sink to log received data. It specifies ports, handlers, and other essential parameters.

```flume
cygnus-ngsi.sources = http-source
cygnus-ngsi.sinks = test-sink
cygnus-ngsi.channels = test-channel

cygnus-ngsi.sources.http-source.channels = test-channel
cygnus-ngsi.sources.http-source.type = org.apache.flume.source.http.HTTPSource
cygnus-ngsi.sources.http-source.port = 5050
cygnus-ngsi.sources.http-source.handler = com.telefonica.iot.cygnus.handlers.NGSIRestHandler
cygnus-ngsi.sources.http-source.handler.notification_target = /notify
cygnus-ngsi.sources.http-source.handler.default_service = def_serv
cygnus-ngsi.sources.http-source.handler.default_service_path = /def_servpath
cygnus-ngsi.sources.http-source.handler.events_ttl = 2
cygnus-ngsi.sources.http-source.interceptors = ts
cygnus-ngsi.sources.http-source.interceptors.ts.type = timestamp

cygnus-ngsi.channels.test-channel.type = memory
cygnus-ngsi.channels.test-channel.capacity = 1000
cygnus-ngsi.channels.test-channel.transactionCapacity = 100

cygnus-ngsi.sinks.test-sink.channel = test-channel
cygnus-ngsi.sinks.test-sink.type = com.telefonica.iot.cygnus.sinks.NGSITestSink
cygnus-ngsi.sinks.test-sink.batch_size = 1
cygnus-ngsi.sinks.test_sink.batch_timeout = 10

```

--------------------------------

### Query Cygnus Agent Version via API

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-ngsi-ld/installation_and_administration_guide/install_with_docker

This command uses `curl` to send an HTTP GET request to the Cygnus agent's management interface to retrieve its version information. The agent's IP address and port 5080 are used to establish the connection. This is a way to programmatically check the agent's status and version.

```bash
$ curl "http://172.17.0.13:5080/v1/version"

```

--------------------------------

### Example Response: Invalid Instance Path

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/management_interface

A sample JSON response indicating an error due to an invalid path provided for the instance configuration file.

```JSON
{
  "success": "false",
  "result": {
    "Invalid path for a instance configuration file"
  }
}
```

--------------------------------

### Map Local Volume to Docker Container

Source: https://fiware-cygnus.readthedocs.io/en/latest/cygnus-common/installation_and_administration_guide/install_with_docker

Illustrates how to use Docker volumes to map a local file to a file within the container using the '-v' flag. This allows for external configuration management of the container's settings, such as the agent configuration file. The example maps a local 'agent.conf' to the container's Flume configuration directory.

```shell
docker run -v /absolute/path/to/local/agent.conf:/opt/apache-flume/conf/agent.conf cygnus-common-1
```