---
title: Install
slug: solutions/topic-registry/install
description: Install, verify, and remove Topic Registry through Marketplace, an image archive, or Docker.
createdAt: 2024-11-05T15:27:46.100Z
---

Install Topic Registry from the Default Marketplace Catalog in Litmus Edge. If you manage images yourself, use an image archive. For Docker-based Litmus Edge instances without Applications, or for a separate Docker host, follow Run on Docker below.

Choose the installation path for your environment:

- [Marketplace](docId\:u1PVsHnqrupQW7XYqeHX0): the default path in Litmus Edge Applications.
- [Image archive](docId\:u1PVsHnqrupQW7XYqeHX0): import an image from Central into Applications.
- [Docker](docId\:u1PVsHnqrupQW7XYqeHX0): run beside Litmus Edge or on another host.

## Install from Marketplace

### Prerequisites

Use a trusted network and restrict access to operators who may view and change Litmus Edge connection settings. Topic Registry has no separate web sign-in; its API secret protects REST API requests, not access to the web interface.

- A running Litmus Edge instance with Applications available
- Permission to install and manage applications
- A Litmus Edge API token. See [Create an API token](https://docs.litmus.io/litmusedge/product-features/system/access-control/tokens/create-api-token).
- A topic that receives messages, for the live-data check

For Docker-based Litmus Edge instances without Applications, use [Run Topic Registry on Docker](docId\:u1PVsHnqrupQW7XYqeHX0).

### Launch the application

1. Open **Applications > Marketplace**.
2. Select **Default Marketplace Catalog**.
3. Find **Topic Registry** and select **Launch**.
4. Select the latest available version.
5. Give the application a unique name.
6. Enter the Litmus Edge API token and choose a secret for the Topic Registry API. Keep the secret for programmatic access.
7. Review the application port. Choose an unused port if the proposed port is occupied.
8. Launch the application.
9. Wait until its status is **Running** in **Catalog Apps**.
10. Open Topic Registry at `http://YOUR_LITMUS_EDGE_ADDRESS:YOUR_APPLICATION_PORT`.

![Select the latest available Topic Registry version](https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/sKQSJAj_3NjmxKteOtGbA-20261110-034727.png)

![Topic Registry launch form with the application port and credential fields](https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/MelUMakPpRq_zxOmifKY0-20261110-034728.png)

For installation on the same Litmus Edge instance, Topic Registry uses the Docker gateway. It needs no separate Docker host or NATS access-account token.

If you need to import an image yourself, see [Install from an image archive](docId\:u1PVsHnqrupQW7XYqeHX0).

### Configure the connection

1. Open **Settings** in Topic Registry.
2. Confirm **Litmus Edge URL** and **REST API Key**.
3. For a Marketplace installation, leave **NATS token** empty. For a Docker installation, keep the configured NATS token.
4. Select **Test Connection**. Confirm that the success message names the intended instance.
5. Select **Save Settings**.
6. Wait for component retrieval to finish. Open any failed component and resolve its reported error.

![Component retrieval in progress after saving settings](https://cdn.images.archbee.com/SSUUxKZUk9bFTEPNn_6Zo/rRpwPbUY_CXE-C15iAVN4_step-2.png?format=webp)

The Litmus Edge URL is the address the container uses to reach the API. The browser uses the application address from your installation.

### Verify

1. Open **Explore** and find a known topic.
2. Open the topic and check **Topic Context** for the expected component.
3. Select **Live Stream**.
4. Select **Start Streaming**.
5. Confirm that new values arrive while the source publishes messages.
6. Select **Stop Streaming**.

For a programmatic status check, replace the address, port, and secret with your installation values:

```bash
curl --fail-with-body -X POST \
  -H 'X_LITMUS_KEY: YOUR_TOPIC_REGISTRY_SECRET' \
  'http://YOUR_TOPIC_REGISTRY_ADDRESS:YOUR_APPLICATION_PORT/api/status'
```

A complete configuration has `success: true`, `data.validConfig: true`, and `data.fetchingStatus: "completed"`. Each component's `status` is `"completed"`. The live-stream check separately confirms that messages arrive.

![Successful retrieval results for all six Litmus Edge components](https://cdn.images.archbee.com/SSUUxKZUk9bFTEPNn_6Zo/myQAtpAW1NgpHnADzfvCD_step-3.png?format=webp)

### Remove

Removing the data volume permanently deletes Topic Registry's saved settings and cached values. It does not delete devices, tags, or flows from Litmus Edge.

1. In **Catalog Apps**, select the Topic Registry application you installed.
2. Remove the application.
3. In **Applications > Volumes**, remove the volume created for that installation.
4. In **Applications > Images**, remove its image if no other container uses it.
5. Revoke an API token created only for this installation.
6. Confirm that the application, its container, and its volume are gone. Confirm that the application address no longer serves Topic Registry.

For a Docker installation, use the removal steps in [Run Topic Registry on Docker](docId\:u1PVsHnqrupQW7XYqeHX0).

## Install from an image archive

Use an image archive when you manage the container directly. For the default installation path, see [Marketplace](docId\:u1PVsHnqrupQW7XYqeHX0).

Before you start, complete the [Marketplace prerequisites](docId\:u1PVsHnqrupQW7XYqeHX0).

### Download and import

1. Sign in to [Litmus Central](https://portal.litmus.io/accelerators/topic-registry).
2. Open **Topic Registry** and select the latest version.
3. Download the image labeled **Docker image (AMD64)** or **Docker image (ARM64)** for your Litmus Edge system.
4. In Litmus Edge, open **Applications > Images**.
5. Upload and import the archive.
6. Note the image tag shown after import. Use that exact tag in the run command.

### Run the container

1. Open **Applications > Containers** and select **Run**.
2. Replace `YOUR_EDGE_API_TOKEN`, `YOUR_TOPIC_REGISTRY_SECRET`, and `YOUR_IMPORTED_IMAGE_TAG` in the command below. Use credential values without spaces.
3. Paste the command as one line. The Run field does not interpret shell quotes or line-continuation characters.

```bash
docker run -d --name topic-registry --restart unless-stopped -p 3000:3000 -v topic-registry-data:/app/db_files -e EDGE_CONNECTION_MODE=internal -e EDGE_API_TOKEN=YOUR_EDGE_API_TOKEN -e EDGE_VERIFY_TLS=false -e X_LITMUS_KEY=YOUR_TOPIC_REGISTRY_SECRET YOUR_IMPORTED_IMAGE_TAG
```

The named volume keeps the database when you replace the container. If port `3000` is occupied, change the first port in `-p 3000:3000`.

`EDGE_VERIFY_TLS=false` accepts the Litmus Edge self-signed certificate. Use `true` when its certificate is trusted by the container.

If gateway detection fails, set `EDGE_DOCKER_GATEWAY_IP` to the actual Docker gateway for the instance.

### Configure and verify

Open `http://YOUR_LITMUS_EDGE_ADDRESS:3000`, using your chosen port. Follow **Configure the connection** and **Verify** in [Install Topic Registry](docId\:u1PVsHnqrupQW7XYqeHX0).

After restarting or replacing the container, open **Settings** and select **Save Settings**. Repeat the connection and live-data checks.

### Remove

Removing the volume permanently deletes Topic Registry's saved data.

1. In **Applications > Containers**, stop and remove `topic-registry`.
2. In **Applications > Volumes**, remove `topic-registry-data`.
3. In **Applications > Images**, remove the imported image when no other container uses it.
4. Revoke an API token created only for this installation.
5. Delete the downloaded archive if you no longer need it.
6. Confirm that the container and volume are gone and the application address no longer serves Topic Registry.

## Run on Docker

Run Topic Registry beside a Docker-based Litmus Edge instance, or on a Docker host that can reach another Litmus Edge instance. You get the same topic inventory, relationship views, and live monitoring in either location.

To run Topic Registry through Applications, use [Marketplace](docId\:u1PVsHnqrupQW7XYqeHX0).

### Prerequisites

Use a trusted network and restrict access to operators who may view and change Litmus Edge connection settings. Topic Registry has no separate web sign-in; its API secret protects REST API requests, not access to the web interface.

- Docker on the host that runs Topic Registry.
- The latest image archive for that host's `amd64` or `arm64` architecture from [Topic Registry in Central](https://portal.litmus.io/accelerators/topic-registry).
- A [Litmus Edge API token](https://docs.litmus.io/litmusedge/product-features/system/access-control/tokens/create-api-token).
- A [Litmus Edge access-account token](https://docs.litmus.io/litmusedge/product-features/system/access-control/tokens/create-api-account) with read permission for the topics you inspect.
- The [NATS proxy](https://docs.litmus.io/litmusedge/product-features/system/access-control/tokens) enabled on Litmus Edge.
- Network access from the container to the Litmus Edge API port and NATS proxy port `4222`.
- Browser access to the Topic Registry host port.

### Choose the connection address

When both containers share a Docker network, use a hostname for the Litmus Edge container that resolves on that network. Add `--network YOUR_NETWORK` to the run command. Use the API port inside the Litmus Edge container in `EDGE_URL`.

When you connect through published host ports, use an address reachable from inside the Topic Registry container. `localhost` inside Topic Registry identifies Topic Registry's own container. Use the Litmus Edge host address instead.

This deployment uses `external` connection mode even when both containers run on the same computer. Use `internal` mode only for installation through Applications. See [Configuration reference](docId:4LVzTh5VKjHMsZ1wrd31G) for both modes.

### Load the image

Load the archive for your host architecture:

```bash
docker load -i YOUR_DOWNLOADED_IMAGE.tar
```

Replace `YOUR_DOWNLOADED_IMAGE.tar` with the downloaded archive's filename. Note the image tag reported by `docker load`. Replace `YOUR_IMPORTED_IMAGE_TAG` in the following commands with that exact tag.

### Run the container

Replace the bracketed values with the Litmus Edge URL, credentials, and a secret for Topic Registry:

```bash
docker run -d --name topic-registry --restart unless-stopped \
  -p 3000:3000 \
  -v topic-registry-data:/app/db_files \
  -e EDGE_CONNECTION_MODE=external \
  -e EDGE_URL='https://<Litmus Edge hostname>:443' \
  -e EDGE_API_TOKEN='<Litmus Edge API token>' \
  -e EDGE_NATS_TOKEN='<NATS access-account token>' \
  -e EDGE_VERIFY_TLS=false \
  -e X_LITMUS_KEY='<Topic Registry API secret>' \
  YOUR_IMPORTED_IMAGE_TAG
```

Use `EDGE_VERIFY_TLS=true` when the Litmus Edge certificate is trusted by the container. Set the actual API port in `EDGE_URL`; the NATS proxy remains on `4222`.

### Use Docker Compose

Use Compose when you want to keep the run settings in a file.

1. Download the file labeled **Docker Compose file** from the **latest version** in Central. Use the downloaded filename wherever `YOUR_DOWNLOADED_COMPOSE_FILE.yaml` appears below.
2. Load the architecture-specific image as described above.
3. Choose a user-defined Docker network. To connect directly to a Docker-based Litmus Edge instance, use a network that instance already joins. Otherwise, create a network:

```bash
docker network create topic-registry-network
```

4. Create `.env` beside the Compose file with these values:

```dotenv
EDGE_URL=https://YOUR_EDGE_HOSTNAME:443
EDGE_API_TOKEN=YOUR_EDGE_API_TOKEN
EDGE_NATS_TOKEN=YOUR_NATS_TOKEN
EDGE_VERIFY_TLS=false
EDGE_DOCKER_NETWORK=YOUR_DOCKER_NETWORK
X_LITMUS_KEY=YOUR_TOPIC_REGISTRY_SECRET
TOPIC_REGISTRY_PORT=3000
```

Set `EDGE_DOCKER_NETWORK` to the chosen network name, such as `topic-registry-network`. Use a network with access to the address in `EDGE_URL`. For a shared network, use the Litmus Edge container hostname and its internal API port.

Use `EDGE_VERIFY_TLS=true` when the certificate is trusted by the image. `TOPIC_REGISTRY_PORT` changes the host port; the container still listens on `3000`.

5. Restrict access to the credentials file:

```bash
chmod 600 .env
```

6. Start the stack:

```bash
docker compose -p topic-registry -f YOUR_DOWNLOADED_COMPOSE_FILE.yaml up -d
```

The Compose file publishes the interface on `127.0.0.1` only. Open `http://127.0.0.1:3000` on that computer, or use the port you selected. The named volume keeps the database when you replace the container.

### Configure and verify

For `docker run`, open `http://<Docker host address>:3000`. For Compose, open `http://127.0.0.1:3000` on the Docker host. Follow **Configure the connection** and **Verify** in [Install Topic Registry](docId\:u1PVsHnqrupQW7XYqeHX0). Keep the configured NATS token for this Docker connection.

After restarting or replacing the container, open **Settings** and select **Save Settings**. Repeat the connection and live-data checks.

### Remove

For a Compose installation, run this command beside the Compose file and `.env`:

```bash
docker compose -p topic-registry -f YOUR_DOWNLOADED_COMPOSE_FILE.yaml down --volumes
```

For a `docker run` installation, remove the container and its named volume:

```bash
docker rm -f topic-registry
docker volume rm topic-registry-data
```

If you created `topic-registry-network` for this installation, remove it after stopping the stack:

```bash
docker network rm topic-registry-network
```

After either installation, remove the image when no other container uses it:

```bash
docker image rm YOUR_IMPORTED_IMAGE_TAG
```

Removing the volume permanently deletes Topic Registry settings and cached data. Revoke credentials created only for this installation. Delete the downloaded archive, Compose file, and `.env` when you no longer need them.

Confirm that the container, volume, and image no longer appear in Docker. The browser address must stop serving Topic Registry.