## Set up on-premises IBM Cognos Analytics access

URL: https://docs.atlan.com/apps/connectors/business-intelligence/ibm-cognos-analytics/how-tos/set-up-on-premises-ibm-cognos-analytics-access

> :::warning Who can do this? You need access to a machine that can run Docker on-premises. You also need your IBM Cognos Analytics instance details, including credentials.

:::danger **Deprecated**
This job execution mode was deprecated on June 30, 2026 and is no longer supported or maintained, including bug fixes. Existing workflows may break/be disabled without warning. For all implementations, switch to [Self-deployed runtime](https://docs.atlan.com/llms/platform/self-deployed-runtime/llms.txt).
:::

In some cases you can't expose your IBM Cognos Analytics instance for Atlan to crawl and ingest metadata. For example, this may happen when security requirements restrict access to sensitive, mission-critical data.

In such cases you may want to decouple the extraction of metadata from its ingestion in Atlan. This approach gives you full control over your resources and metadata transfer to Atlan.

## Prerequisites

To extract metadata from your on-premises IBM Cognos Analytics instance, use Atlan's `cognos-extractor` tool.

Before you begin, verify that you have:

- Access to a machine in your on-premises environment that can run Docker
- Connectivity to your IBM Cognos Analytics instance
- IBM Cognos Analytics instance details, including credentials required for authentication

Atlan uses the same `cognos-extractor` internally when connecting to IBM Cognos Analytics instances hosted in the cloud.

### Install Docker Compose

[Docker Compose](https://docs.docker.com/compose/) is a tool for defining and running applications composed of many [Docker](https://docs.docker.com/get-started/overview/) containers.

To install Docker Compose:

1. [Install Docker](https://docs.docker.com/get-docker/)
2. [Install Docker Compose](https://docs.docker.com/compose/install/)

These instructions are enough even if you are completely new to Docker and Docker Compose. However, you can also walk through the [Get started with Docker Compose](https://docs.docker.com/compose/gettingstarted/) tutorial if you want to learn Docker Compose basics first.

### Get cognos-extractor tool

To get the cognos-extractor tool:

1. [Raise a support ticket](https://docs.atlan.com/support/submit-request) to get the link to the latest version.
2. Download the image using the link provided by support.
3. Load the image to the server you'll use to crawl IBM Cognos Analytics:

 ```
 sudo docker load -i /path/to/cognos-extractor-master.tar
 ```

## Get compose file

Atlan provides you with a [Docker compose file](https://docs.docker.com/compose/compose-file/) for the cognos-extractor tool.

To get the compose file:

1. Download the [latest compose file](https://atlan-public.s3.eu-west-1.amazonaws.com/atlan/cognos-extractor/docker-compose.yaml).
2. Save the file to an empty directory on the server you'll use to access your on-premises IBM Cognos Analytics instance.
3. The file is `docker-compose.yaml`.

## Define IBM Cognos Analytics connections

The structure of the compose file includes three main sections:

- `x-templates` contains configuration fragments. Ignore this section and don't make any changes to it.
- `services` is where you define your IBM Cognos Analytics connections.
- `volumes` contains mount information. Ignore this section as well and don't make any changes to it.

### Define services

For each on-premises IBM Cognos Analytics instance, define an entry under `services` in the compose file.

Each entry has the following structure:

```
services:
 cognos-example:
 <<: *extract
 environment:
 <<: *cognos-defaults
 EXCLUDE_FILTER: '{}'
 INCLUDE_FILTER: '{}'
 volumes:
 - ./output/cognos-example:/output/process
```

- Replace `cognos-example` with the name of your connection.
- `<<: *extract` tells the cognos-extractor tool to run.
- `environment` contains all parameters for the tool.
 - `EXCLUDE_FILTER` and `INCLUDE_FILTER` - specify a regular expression to filter assets to exclude or include, respectively. For example, to exclude a folder with the ID `76471ff1e0f02c7d3349` in `team_content`, configure the `EXCLUDE_FILTER` as follows - `'{"team_content": {"76471ff1e0f02c7d3349": {}}'`.
- `volumes` specifies where to store results. In this example, the extractor stores results in the `./output/cognos-example` folder on the local file system.

You can add as many IBM Cognos Analytics connections as you want.

:::info **Did you know?** 
 [Docker's documentation](https://docs.docker.com/compose/compose-file/#services-top-level-element) describes the `services` format in more detail.

:::

## Provide credentials

To define the credentials for your IBM Cognos Analytics connections, provide an IBM Cognos Analytics configuration file.

The IBM Cognos Analytics configuration is a `.ini` file with the following format:

```
[CognosConfig]
host=http://cognos-application-host-example.us-east-2.compute.amazonaws.com
port=9300
namespace=CognosEx

# possible values are "basic_auth", "okta_auth" and "api_key"

auth_type=basic_auth

# Only required when auth_type = basic_auth

[BasicAuth]
username=user@atlan.com
password=<password>

# Only required when auth_type = okta_auth

[OKTAAuth]
username=user@atlan.com
password=<password>

# Only required when auth_type = api_key

[APIKeyAuth]
key=<yourAPIkey>
```

## Secure credentials

### Using local files

:::warning

If you decide to keep IBM Cognos Analytics credentials in plaintext files, restrict access to the directory and the compose file. For extra security, use [Docker secrets](https://docs.docker.com/engine/swarm/secrets/) to store the sensitive passwords.

:::

To specify the local files in your compose file:

```
secrets:
 cognos_config:
 file: ./cognos.ini
```

:::warning

This `secrets` section is at the same top-level as the `services` section described earlier. It's not a sub-section of the `services` section.

:::

### Using Docker secrets

To create and use Docker secrets:

1. Store the IBM Cognos Analytics configuration file:

 ```
 sudo docker secret create cognos_config path/to/cognos.ini
 ```

2. At the top of your compose file, add a [secrets](https://docs.docker.com/compose/compose-file/compose-file-v3/#secrets-configuration-reference) element to access your secret:

 ```
 secrets:
 cognos_config:
 external: true
 name: cognos_config
 ```

 - The `name` must match the value from the `docker secret create` command in the previous step.
 - Once stored as a Docker secret, you can remove the local IBM Cognos Analytics configuration file.
3. Within the `service` section of the compose file, add a new secrets element and specify the name of the secret within your service to use it.

## Example

The following example explains the configuration in detail:

```
secrets:
 cognos_config:
 external: true
 name: cognos_config

x-templates:
 # ...

services:
 cognos-example:
 <<: *extract
 environment:
 <<: *cognos-defaults
 EXCLUDE_FILTER: '{}'
 INCLUDE_FILTER: '{}'
 volumes:
 - ./output/cognos-example:/output/process
 secrets:
 - cognos_config
```

1. In this example, the secrets at the top of the file (you can also define them at the bottom) reference an external Docker secret created using the `docker secret create` command.
2. The name of this service is `cognos-example`. You can use any meaningful name you want.
3. The `<<: *cognos-defaults` sets the connection type to IBM Cognos Analytics.
4. The `EXCLUDE_FILTER` and `INCLUDE_FILTER` tells the extractor to filter folders.
5. The `./output/cognos-example:/output/process` line tells the extractor where to store results. In this example, the extractor stores results in the `./output/cognos-example` directory on the local file system. Output the extracted metadata for different connections in separate directories.
6. The `secrets` section within `services` tells the extractor which secrets to use for this service. Each of these refers to the name of a secret listed at the beginning of the compose file.

---