How to Deploy TrendRadar: Docker and Local Installation Guide

Deploy TrendRadar using Docker Compose with the trendradar and optional trendradar-mcp containers, or run directly via Python on your local machine.

TrendRadar is an open-source news aggregation and analysis tool that you can deploy in multiple ways depending on your environment. This guide covers the complete deployment process for both Docker-based production setups and local development configurations, referencing the actual implementation in the sansan0/TrendRadar repository.

Docker Deployment (Recommended)

The Docker approach is the recommended method for production deployments, home servers, NAS devices, and CI/CD pipelines. It isolates the runtime environment, guarantees Python 3.12 compatibility, and enables continuous operation with minimal setup.

Container Architecture

TrendRadar's Docker deployment uses two independent containers:

Container	Purpose	Source File
trendradar	News crawling, filtering, HTML report generation, and push notifications	docker/Dockerfile
trendradar-mcp (optional)	AI analysis via HTTP/MCP endpoint for tools like Cherry Studio or Cursor	docker/Dockerfile.mcp

Both containers mount shared volumes for configuration and output data:

Host ./config/  →  Container /app/config  (read-only)
Host ./output/  →  Container /app/output  (read-write, shared)

Core Docker Files

File	Role	Path
docker-compose.yml	Orchestrates services, volumes, and environment variables	docker/docker-compose.yml
Dockerfile	Builds the main trendradar image (Python 3.12 + UV package manager)	docker/Dockerfile
Dockerfile.mcp	Builds the optional MCP server image	docker/Dockerfile.mcp
.env	Stores secrets and runtime configuration (not tracked by Git)	docker/.env
entrypoint.sh	Container entrypoint that initializes the scheduled crawler	docker/entrypoint.sh

Step-by-Step Docker Deployment

# 1. Clone the repository

git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar

# 2. Create environment configuration from the template

cp docker/.env.example docker/.env

# 3. Edit docker/.env with your credentials

# Required: notification webhook URLs (Feishu, Telegram, Slack, etc.)

# Optional: AI_API_KEY for analysis, S3_* for remote storage

# 4. Start the services

docker compose up -d

# 5. Verify operation

docker compose logs -f trendradar

Common Docker Compose Commands

# Start only the main crawler (skip AI analysis)

docker compose up -d trendradar

# Stop all services

docker compose down

# View real-time logs

docker compose logs -f

# Restart after configuration changes

docker compose up -d --force-recreate

Local and Script-Based Deployment

For development, debugging, or quick testing, you can run TrendRadar directly on your host machine without containerization.

Setup Scripts

Script	Platform	Purpose
setup-mac.sh	macOS / Linux	Creates Python virtual environment, installs dependencies via UV
setup-windows.bat	Windows	Equivalent Windows setup
start-http.sh / start-http.bat	All platforms	Starts the MCP HTTP server locally

Local Installation Steps

# Run the appropriate setup script

./setup-mac.sh        # macOS/Linux

# or

setup-windows.bat     # Windows

# Activate the virtual environment

source .venv/bin/activate   # macOS/Linux

# or

.venv\Scripts\activate      # Windows

# Run the scheduler once for testing

python -m trendradar

# Run in continuous cron mode

python -m trendradar --run-mode cron

Starting the MCP Server Locally

# With virtual environment activated

uv run python -m mcp_server.server --transport http --host 0.0.0.0 --port 3333

The server exposes the MCP endpoint at http://0.0.0.0:3333/mcp, compatible with AI tools like Cherry Studio and Cursor.

Configuration and Environment Variables

TrendRadar uses a configuration hierarchy where environment variables override settings in config/config.yaml.

Key Configuration Files

File	Location	Purpose
config.yaml	config/config.yaml	Core application settings (push mode, schedule, storage, AI toggles)
frequency_words.txt	config/frequency_words.txt	Keyword list for content filtering
ai_*.txt	config/	AI prompt templates and analysis configurations

Critical Environment Variables

Variable	Affects	Example
FEISHU_WEBHOOK_URL	Feishu push notifications	https://open.feishu.cn/open-apis/bot/v2/hook/XXXX
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID	Telegram push	123456:ABC-DEF1234 / 987654321
AI_ANALYSIS_ENABLED	Toggle AI features	true
AI_API_KEY / AI_MODEL / AI_API_BASE	AI provider configuration	sk-xxxxx / openai/gpt-4o
S3_ENDPOINT_URL / S3_BUCKET_NAME / S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY	Remote storage backend	https://s3.r2.cloudflarestorage.com
CRON_SCHEDULE	Crawler frequency	*/15 * * * *
RUN_MODE	Execution mode	cron or once

Sample .env for Push-Only Deployment

# docker/.env - do NOT commit this file

TZ=Asia/Shanghai
WEBSERVER_PORT=8080

# Notification channels (use ';' to separate multiple destinations)

FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/XXXXXXXXXXXXXXXX
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=987654321

# Optional AI (can be omitted if you only need push)

AI_ANALYSIS_ENABLED=true
AI_API_KEY=sk-YourOpenAIKeyHere
AI_MODEL=openai/gpt-4o
AI_API_BASE=https://api.openai.com/v1

# Remote storage (comment out if you keep data locally)

# S3_ENDPOINT_URL=https://your-account.r2.cloudflarestorage.com

# S3_BUCKET_NAME=trendradar-data

# S3_ACCESS_KEY_ID=your_key_id

# S3_SECRET_ACCESS_KEY=your_secret

# S3_REGION=auto

Accessing Generated Reports

After deployment, TrendRadar generates an HTML report at output/index.html.

Viewing Options

Method	Command	Access URL
Direct file	Open output/index.html in browser	file:///path/to/output/index.html
Built-in server	python -m trendradar.start_http	http://localhost:8080
Docker volume	Mount output/ to host, serve with any web server	Varies

Summary

• Docker deployment is the recommended approach for production, providing isolated containers, automatic scheduling, and simple configuration via docker/.env.

• Two containers work together: trendradar (required) handles news crawling and push notifications, while trendradar-mcp (optional) provides AI analysis endpoints.

• Local deployment uses setup-mac.sh or setup-windows.bat to create a Python environment, suitable for development and testing.

• Configuration combines config/*.yaml files with environment variables in docker/.env, following an "Env > Config" precedence.

• Generated reports appear in output/index.html and can be viewed directly or served via the built-in HTTP server.

Frequently Asked Questions

What is the minimum configuration needed to deploy TrendRadar?

You need docker and docker compose installed, plus a populated docker/.env file with at least one notification webhook URL (Feishu, Telegram, or Slack). The config/config.yaml and config/frequency_words.txt files must exist in your repository clone. No AI configuration is required for basic news aggregation and push functionality.

Can I deploy TrendRadar without Docker?

Yes. Use the setup-mac.sh or setup-windows.bat scripts to install dependencies into a Python virtual environment, then run python -m trendradar for one-time execution or python -m trendradar --run-mode cron for continuous operation. The MCP server can be started locally with uv run python -m mcp_server.server --transport http.

How do I update my TrendRadar deployment?

For Docker deployments, run docker compose pull to fetch updated images, then docker compose up -d to restart with the new version. For local deployments, pull the latest code with git pull and re-run your setup script to update dependencies. Configuration files in config/ and docker/.env persist across updates.

What hardware requirements does TrendRadar need?

TrendRadar runs comfortably on minimal hardware: any system capable of running Docker or Python 3.12, with approximately 512MB RAM for the base container and additional memory if enabling AI analysis. The application stores data in SQLite databases typically under 100MB for moderate usage, though S3-compatible remote storage can be configured for larger deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}