Getting Started

1 - Deployment

Install from stable release

curl -fsSL https://taranis.ai/install.sh | bash

Clone via git

git clone --depth 1  https://github.com/taranis-ai/taranis-ai
cd taranis-ai/docker/

Configuration

Copy env.sample to .env

cp env.sample .env

Open .env and change the defaults before exposing the instance on a network. More details about environment variables can be found in the docker README.

Redis and worker queues

Taranis AI uses Redis and RQ for worker queues, scheduled jobs, and frontend cache storage.

The Compose deployment wires Redis into core, frontend, collector, cron, and workers. If queued jobs are accepted but not processed, verify that Redis is reachable and at least one worker container is running.

See Background Jobs for Redis/RQ architecture, health checks, scheduled jobs, and upgrade notes.

LLM bot settings

The Compose deployment includes the optional llm-bot service for LLM-backed summaries, title generation, NER, clustering, and sentiment.

See LLM Bot Service for endpoint mapping and bot configuration.

Images and tags

Taranis AI images are tagged as follows:

• Official release version number (e.g. 1.1.7)
• Every official image release comes with an extra stable tag, in case pinning the release is not favourable (stable)
• Latest tag for tracking the latest uploaded image, there is no guarantee this is an officially released image (latest)

See Internal TLS Configuration for setting up TLS encryption and Advanced monitoring for more logging insights. For detailed information about container tags, release strategy, and deployment recommendations, see Releases and Container Tags.

Startup & Usage

Pull the configured release images before starting or upgrading:

docker compose pull

Start the application:

docker compose up -d

Verify readiness:

curl -fsS http://<url>:<TARANIS_PORT>/api/health
docker compose ps

Use the application:

http://<url>:<TARANIS_PORT>/login

Initial Setup

The default credentials are user / user and admin / admin. Change them before production use.

The passwords for these two default users can be overridden by setting the environment variables PRE_SEED_PASSWORD_ADMIN or PRE_SEED_PASSWORD_USER before first launch. Afterwards they are stored in the database in the user table.

For existing database-auth users, passwords and role assignments can be repaired with the operational CLI. See User Management.

Open http://<url>:<TARANIS_PORT>/config/sources and click load default sources to import the default sources from: default_sources.json

Or import a source export via the Import.

2 - Kubernetes deployment

Configuration

Clone via git

git clone --depth 1  https://github.com/taranis-ai/taranis-ai
cd taranis-ai/docker/

Copy env.sample to .env

cp env.sample .env

Open file .env and change defaults if needed. More details about environment variables can be found here.

See Internal TLS Configuration for setting up TLS encryption and Advanced monitoring for more logging insights. See Releases and Container Tags for information about container image versions, Internal TLS Configuration for setting up TLS encryption, and Advanced monitoring for more logging insights.

Convert via Kompose

Download and install kompose.io

# resovle variables from .env into taranis-ai/docker/compose.yml 
docker compose config > resolved-compose.yml

# convert compose file to kubernetes 
kompose --file resolved-compose.yaml convert

MultiDB SQLAlchemy

If you want to connect to a kubernetes cluster you can do something like this:

kubectl create ns db
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install pg-ha bitnami/postgresql-ha -n db \
  --set postgresql.username=app \
  --set postgresql.password=apppass \
  --set postgresql.database=appdb \
  --set pgpool.adminUsername=pgpool \
  --set pgpool.adminPassword=pgpoolpass \
  --set postgresql.replicaCount=2

kubectl -n db port-forward statefulset/pg-ha-postgresql 54321:5432 &
kubectl -n db port-forward pod/pg-ha-postgresql-1 54322:5432 &

And then connect with:

SQLALCHEMY_DATABASE_URI="postgresql+psycopg://app:apppass@/appdb?host=127.0.0.1,127.0.0.1&port=54321,54322&target_session_attrs=read-write&connect_timeout=3"

3 - Releases and Container Tags

Tags

Taranis AI publishes container images to GitHub Container Registry (ghcr.io) with different tagging strategies for core services and bots.

All images are available at GitHub Container Registry.

For Core Services (core, gui, worker, frontend)

Core Taranis AI services follow a stable and tested release process:

For Bots

Bot containers follow a similar release process, with versions decoupled from the core Taranis AI services:

4 - Requirements

For the best experience using Taranis AI, we recommend that your system meet the following requirements:

System Requirements

Note: The recommended requirements assume that all bots are active concurrently. You can estimate the requirements for running only some of the bots from this table:

You can assume the number of CPUs and RAM to be cumulative, so for running two bots concurrently, sum up the required number of CPUs and RAM. Reserve an additional 2 CPUs and 2 GB RAM for normal system operation.

Example: For running story-clustering and NER bots at the same time, your system should have 6 CPUs and 10.5 GB of RAM.

GPU Acceleration (Coming Soon)

GPU support for accelerating bot performance will be available soon. Further details and configuration options will be provided once this feature is launched.

Recommended Setup

• Display: Full HD (1920×1080) or higher
• Supported Browsers:
  • Chromium
  • Mozilla Firefox
  • Microsoft Edge

5 - Background Jobs

Taranis AI uses Redis and RQ for background work. Collection, bots, presenters, publishers, connectors, and maintenance jobs are queued by core and processed by worker containers.

Services

Queues are split by worker category: collectors, bots, presenters, publishers, connectors, and misc.

Redis settings

Set a Redis password for production and keep Redis private to the Compose or Kubernetes network.

Do not publish the Redis port unless you have a controlled operational reason.

Health checks

Core exposes:

GET /api/health

The response reports database, seed_data, broker, and workers. If Redis is up but no workers are connected, queued jobs can be accepted but will not run until a worker starts.

Example degraded response:

{
  "healthy": false,
  "services": {
    "database": "up",
    "seed_data": "up",
    "broker": "up",
    "workers": "down"
  }
}

When workers is down, check the collector, workers, and cron containers or deployments first, then inspect worker logs for bad WORKER_TYPES, invalid API keys, Redis authentication failures, or failed bot service calls.

Scheduled jobs

Collectors and bots use cron-like schedules. Core stores managed schedule definitions in Redis, and the cron service reconciles those definitions with enabled sources and bots. Changing a collector or bot schedule does not require restarting the workers.

The worker admin views show queued, active, failed, and scheduled jobs. Use them before clearing queues so you know what work will be lost.

Upgrade note

Taranis AI 1.4.0 replaced Celery/RabbitMQ with Redis/RQ. There is no queue handover from Celery to RQ. Before upgrading an older deployment, let running Celery jobs finish, stop the old workers, then deploy the Redis, collector, workers, and cron services together.

6 - LLM Bot Service

llm-bot is an optional HTTP service used by worker bots for LLM-backed analysis. The Compose deployment includes it as ghcr.io/taranis-ai/taranis-llm-bot:${TARANIS_BOT_TAG:-stable}.

It talks to an OpenAI-compatible Responses API and exposes endpoints for:

Compose configuration

Set these values in docker/.env:

Advanced optional settings:

Keep LLM_API_KEY, BOT_API_KEY, and any provider credentials out of logs and shared files. The service should stay on the private application network; do not publish it directly to the internet.

Worker integration

The Compose deployment wires these worker endpoints to llm-bot by default:

Bot endpoint parameters saved in the admin UI take precedence over worker defaults. If an upgraded instance still has old standalone bot hostnames such as http://summary_bot:8000, http://nlp_bot:8000, or http://story_bot:8000, update those bot parameters to the llm-bot endpoints or clear the override.

For title generation, set TITLE_ENDPOINT on the Summary Bot to:

http://llm-bot:8000/title

For sentiment analysis, set the Sentiment Analysis Bot BOT_ENDPOINT to:

http://llm-bot:8000/sentiment

Each bot can override the default endpoint and timeout with its own parameters. See Bots for the user-facing bot settings.

Canonical llm-bot paths are accepted with or without a trailing slash.

Validation

Check service health from inside the application network:

curl http://llm-bot:8000/health

If API_KEY is configured on the service, protected task endpoints require:

Authorization: Bearer <BOT_API_KEY>

Use /info to confirm endpoint paths and non-secret feature settings. It reports whether lookup and linking are configured without exposing API keys.

7 - Maintenance

Standard image upgrade

Use published images for deployment upgrades. Do not build application images on production hosts unless you are intentionally testing a custom build.

cd taranis-ai/docker
docker compose pull
docker compose up -d
curl -fsS http://<url>:<TARANIS_PORT>/api/health
docker compose ps

For rollback, pin TARANIS_TAG and TARANIS_BOT_TAG to the previous known-good release in .env, pull, restart, and verify /api/health again.

Redis/RQ migration

Taranis AI 1.4.0 replaced Celery/RabbitMQ with Redis/RQ. There is no queue handover from old Celery workers to the new RQ workers.

Before upgrading an older deployment:

1. Let running and queued Celery jobs finish.
2. Stop old Celery/RabbitMQ services.
3. Deploy Redis plus the collector, workers, and cron services.
4. Verify /api/health reports database, seed data, broker, and workers as up.

See Background Jobs for the current worker architecture.

PostgreSQL 14 to 17

Supported upgrade of PostgreSQL 14.x to PostgreSQL 17.x. Expect Taranis AI downtime during the database upgrade.

Prerequisites

• Installed Docker Compose V2 or podman-compose
• Running Taranis AI deployment using the docker/compose.yml file.
• Running database PostgreSQL of major version 14
• Compose file (docker/compose.yml) is setup to use the image of PostgreSQL 17 (check your POSTGRES_TAG variable in the .env file)

Steps to upgrade

1. Go to directory: taranis-ai/docker
2. Ensure the script upgrade-database.sh is executable
3. Run the script: ./upgrade-database.sh

All containers should now be up and running again. Verify /api/health and review database logs before handing the instance back to users.

8 - Advanced monitoring

Prerequisites

• Sentry instance available, either SaaS or self-hosted.
• Follow this guide to have a Sentry project (and SENTRY_DSN) ready.

What is Sentry

Sentry is a monitoring tool that enables more insights about an application. Taranis AI takes advantage of this if you enable it at the start up.

What is there to monitor

Sentry can be used to monitor insights about GUI, Core and database. In Taranis AI: Issues, Traces, Profiles and Queries can be tracked.

Health and worker queues

The core service exposes /api/health for readiness and dependency checks. It reports the database, seed data, Redis broker, and worker status when those services are available.

Worker-backed actions such as collecting an OSINT source, running a bot, gathering a word list, rendering a product, or publishing a product can be queued even when no workers are connected. In that case the frontend shows a warning that the task was queued but may not be processed until a worker starts.

If this warning appears:

1. Verify Redis with the configured REDIS_URL and REDIS_PASSWORD.
2. Verify that the collector, cron, and workers containers or Kubernetes deployments are running.
3. Check the worker logs for failed startup, invalid WORKER_TYPES, or authentication errors against core.
4. Use the admin worker and queue views to inspect queued, active, failed, and scheduled jobs.

See Background Jobs for worker services, queues, scheduler behavior, and Redis/RQ upgrade notes.

How to enable Sentry in Taranis AI

To enable Sentry, set the SENTRY_DSN variables in the .env file before start of the application. More details about environment variables can be found here.

GUI monitoring

To gain insights about GUI, use the TARANIS_GUI_SENTRY_DSN variable and set it to your Sentry DSN address.

Core and database monitoring

To gain insights about Core and database, use the TARANIS_CORE_SENTRY_DSN variable and set it to your Sentry DSN address.

9 - TLS Configuration

This guide explains how to configure TLS (Transport Layer Security) for Taranis AI using the Granian ASGI server. TLS provides encrypted communication between clients and the server, essential for secure deployments.

Key Environment Variables

The primary TLS configuration is handled through Granian environment variables:

Required TLS Variables

For a basic TLS setup, configure these environment variables:

# SSL Certificate file path
GRANIAN_SSL_CERTIFICATE=/path/to/your/certificate.pem

# SSL Private key file path  
GRANIAN_SSL_KEYFILE=/path/to/your/private_key.pem

# Turn off verification of self-signed certificates in Frontend and Worker service
SSL_VERIFICATION=False

DISABLE_SSE=True

When enabling TLS, you must also update the core URL to use HTTPS:

# Update the core API URL to use HTTPS
TARANIS_CORE_URL=https://your-domain.com/api

This variable affects multiple components:

• Frontend service: Uses TARANIS_CORE_URL to communicate with the core API
• Worker service: Uses TARANIS_CORE_URL for API communication (falls back to http://{TARANIS_CORE_HOST}{TARANIS_BASE_PATH}api if not set)
• GUI service: Configured via TARANIS_CORE_API in config.json

Optional TLS Variables

More Granian environmental variables that affect SSL are derived from the CLI options prefixed with --ssl-*.

Examples:

GRANIAN_SSL_KEYFILE_PASSWORD
GRANIAN_SSL_CA
GRANIAN_SSL_CRL
GRANIAN_SSL_CLIENT_VERIFY

Make sure, all variables are properly set in the compose file. The variable SSL_VERIFICATION can be set for the frontend and worker service.

Docker Compose Configuration

Important Configuration Notes

1. Certificate Mounting: Certificates mounted as read-only (./certs:/certs:ro)
2. SSL Verification: Self-signed certificates cause problems (SSL_VERIFICATION=False)
3. Health Checks: To work properly they need to be changed to https:// prefix. Moreover, the Certificate Authority needs to be added into the container’s trust store by mounting it under /usr/local/share/… Read more at docker.com.

Basic TLS Setup

Here’s an example Docker Compose configuration with TLS enabled:

services:
  core:
    image: ghcr.io/taranis-ai/taranis-core:latest
    environment:
      # TLS configuration (paths must match the mounted cert directory)
      - GRANIAN_SSL_CERTIFICATE=/certs/certificate.pem
      - GRANIAN_SSL_KEYFILE=/certs/private_key.pem

      - TARANIS_CORE_URL=https://your-domain.com/api
      - DB_URL=database
      - DB_DATABASE=taranis
      - DB_USER=taranis
      - DB_PASSWORD=supersecret
      - API_KEY=your-secure-api-key
      - JWT_SECRET_KEY=your-secure-jwt-secret

    volumes:
      # Mount local certificate directory into the container
      - ./certs:/certs:ro
      - core_data:/app/data

    depends_on:
      - database
      - rabbitmq

    ports:
      - "8443:8080"

    networks:
      - taranis_network

    healthcheck:
      test: ["CMD-SHELL", "curl --fail https://localhost:8080/api/health || exit 1"]
      interval: 90s
      timeout: 30s
      retries: 5
      start_period: 40s

volumes:
  core_data:

networks:
  taranis_network:
    driver: bridge

Kubernetes Configuration

For Kubernetes deployments, configure TLS using ConfigMaps and Secrets:

# TLS Secret
apiVersion: v1
kind: Secret
metadata:
  name: taranis-tls
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

---
# Core Deployment with TLS
apiVersion: apps/v1
kind: Deployment
metadata:
  name: taranis-core
spec:
  replicas: 1
  selector:
    matchLabels:
      app: taranis-core
  template:
    metadata:
      labels:
        app: taranis-core
    spec:
      containers:
      - name: core
        image: ghcr.io/taranis-ai/taranis-core:latest
        env:
        - name: GRANIAN_SSL_CERTIFICATE
          value: "/certs/tls.crt"
        - name: GRANIAN_SSL_KEYFILE
          value: "/certs/tls.key"
        - name: TARANIS_CORE_URL
          value: "https://your-domain.com/api"
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: taranis-secrets
              key: api-key
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: taranis-secrets
              key: jwt-secret
        volumeMounts:
        - name: tls-certs
          mountPath: /certs
          readOnly: true
      volumes:
      - name: tls-certs
        secret:
          secretName: taranis-tls

10 - Additional References

Create intelligence and share with MISP

Corrensponds to Taranis release 1.2.4

General workflow video