# How to Deploy TrendRadar: Docker and Local Installation Guide

> Deploy TrendRadar easily with Docker Compose or local Python installation. Get your TrendRadar up and running quickly with our comprehensive guide.

- Repository: [sansan/TrendRadar](https://github.com/sansan0/TrendRadar)
- Tags: how-to-guide
- Published: 2026-04-22

---

**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`](https://github.com/sansan0/TrendRadar/blob/main/docker-compose.yml) | Orchestrates services, volumes, and environment variables | [`docker/docker-compose.yml`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/entrypoint.sh) | Container entrypoint that initializes the scheduled crawler | [`docker/entrypoint.sh`](https://github.com/sansan0/TrendRadar/blob/main/docker/entrypoint.sh) |

### Step-by-Step Docker Deployment

```bash

# 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

```bash

# 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`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) | macOS / Linux | Creates Python virtual environment, installs dependencies via UV |
| `setup-windows.bat` | Windows | Equivalent Windows setup |
| [`start-http.sh`](https://github.com/sansan0/TrendRadar/blob/main/start-http.sh) / `start-http.bat` | All platforms | Starts the MCP HTTP server locally |

### Local Installation Steps

```bash

# 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

```bash

# 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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml).

### Key Configuration Files

| File | Location | Purpose |
|------|----------|---------|
| [`config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config.yaml) | [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) | Core application settings (push mode, schedule, storage, AI toggles) |
| [`frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/frequency_words.txt) | [`config/frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/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

```dotenv

# 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`](https://github.com/sansan0/TrendRadar/blob/main/output/index.html).

### Viewing Options

| Method | Command | Access URL |
|--------|---------|------------|
| Direct file | Open [`output/index.html`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) and [`config/frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/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`](https://github.com/sansan0/TrendRadar/blob/main/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.