Docker Deployment

Docker is one of the recommended deployment methods, suited to users who have a server or NAS. This guide walks you through deploying TrendRadar with Docker, with no need to install a Python environment.

Current task · Docker

Run TrendRadar continuously on your server or NAS, with runtime data stored locally by default.

Choose another method

11 · Before runningConfigure one push channel

22 · Done whenNo log errors, and a test or first push arrives in the target app

33 · After it arrivesConfigure content and delivery

Before the first run: configure one push channel

Open Push channels from the sidebar, choose a destination, obtain its Webhook, token or credentials, then add them to docker/.env or config/config.yaml. Return here to start the container and send a test notification.

Prerequisites

Make sure Docker and Docker Compose are installed on your system. If they are not yet installed, refer to the official Docker documentation to complete the installation.

Image overview

TrendRadar provides two Docker images, each corresponding to a different functional module:

Image name	Purpose	Description
`wantcat/trendradar`	News push service	Scheduled news crawling, keyword matching, push notifications (required)
`wantcat/trendradar-mcp`	AI analysis service	AI chat analysis based on the MCP protocol (optional)

Method 1: Docker Compose deployment (recommended)

Docker Compose can start the core push service or the optional MCP service as needed. The following steps first establish a minimal working push flow.

Clone the project

Get the latest code and config files

Understand the directory structure

Get familiar with what each config file does

Edit the configuration

Modify the config files to suit your needs

Start and verify

Run the core push service first and confirm a test notification

1. Clone the project

Open a terminal and run the following command to clone the project locally:

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

2. Directory structure

After cloning, you'll see the following directory structure. For deployment, you only need to focus on the config/ and docker/ directories:

Project/
├── config/
│   ├── config.yaml                # 核心配置文件（必须编辑）
│   ├── frequency_words.txt        # 关键词配置（必须编辑）
│   ├── timeline.yaml              # 时间线调度配置
│   ├── ai_analysis_prompt.txt     # AI 分析提示词（可选）
│   ├── ai_translation_prompt.txt  # AI 翻译提示词（可选）
│   ├── ai_interests.txt           # AI 兴趣过滤（可选）
│   ├── ai_filter/                 # AI 筛选提示词目录
│   └── custom/                    # 用户自定义配置
│       ├── ai/                    # 自定义 AI 提示词
│       └── keyword/               # 自定义关键词文件
└── docker/
    ├── .env                       # Secrets and Docker settings (currently tracked by Git)
    └── docker-compose.yml         # Docker Compose service definition

3. Config file descriptions

Each config file handles a different functional module. Here is a brief overview:

File	Role	Required
`config/config.yaml`	The core config file, containing all system parameters such as platform selection, push channels, and AI settings	Required
`config/frequency_words.txt`	Keyword configuration, defining the news topics you care about and the filtering rules	Required
`config/timeline.yaml`	Timeline scheduling configuration, controlling what tasks run at what time each day	Optional
`docker/.env`	Secrets and Docker settings; this file is tracked, so never commit locally entered secret values	Required

Config file editing tip

For detailed configuration instructions on config.yaml and frequency_words.txt, refer to the configuration editing chapter in "Quick Start." This page only covers what is specific to Docker deployment.

4. Environment variable override mechanism

TrendRadar supports overriding the configuration in config.yaml via environment variables. The priority is: environment variables > the config.yaml file.

This means you can put sensitive information (such as the API Key and Webhook URL) in the docker/.env file instead of writing it into config.yaml. Docker Compose automatically reads the variables in the .env file.

Environment variable	Corresponding config	Description
`WEBSERVER_PORT`	-	Built-in report server port, default 8080
`FEISHU_WEBHOOK_URL`	notification.channels.feishu.webhook_url	Feishu bot Webhook URL
`AI_ANALYSIS_ENABLED`	ai_analysis.enabled	Whether to enable the AI analysis feature (true/false)
`AI_API_KEY`	ai.api_key	The API Key for the AI service
`AI_MODEL`	ai.model	AI model identifier (e.g. deepseek/deepseek-v4-flash)
`S3_ENDPOINT_URL`	storage.remote.endpoint_url	The Endpoint URL of the S3-compatible storage
`S3_ACCESS_KEY_ID`	storage.remote.access_key_id	The Access Key of the S3 storage
`S3_SECRET_ACCESS_KEY`	storage.remote.secret_access_key	The Secret Key of the S3 storage
`S3_BUCKET_NAME`	storage.remote.bucket_name	The S3 bucket name
`CRON_SCHEDULE`	-	Docker cron expression (default /30 * * *, runs every 30 minutes)
`RUN_MODE`	-	Run mode: cron (scheduled loop) or once (run once then exit)
`IMMEDIATE_RUN`	-	Whether to run immediately on container startup (default true)

The above lists commonly used environment variables. For the full list, refer to the docker-compose.yml file.

Security tip

Do not commit a .env file containing real keys to a Git repository. In the corresponding project version, docker/.env is already tracked by Git, so .gitignore cannot prevent later edits from being committed. Prefer injecting variables through the deployment platform; otherwise check git diff -- docker/.env before every commit.

5. Start the services

Enter the docker/ directory and choose a startup method based on your needs: for a first run, choose the push service only. MCP is an optional enhancement after the basic flow works.

Start all services (when needed)

Push service only (recommended first)

MCP service only

Start only the news push service, without the MCP analysis service:

cd docker
docker compose pull trendradar
docker compose up -d trendradar

Verify after startup

Run docker compose ps and docker logs trendradar to inspect the container and first crawl. If AI is enabled, run docker exec trendradar python -m trendradar --doctor to check the AI switch, API key, and model identifier. Finish with docker exec trendradar python -m trendradar --test-notification. A running container proves only that the process is alive, not that AI and notifications are working.

Advanced reference: run MCP with Docker Run

The command below starts only the optional MCP analysis service; it is not a complete crawler and push deployment. Use the Docker Compose flow above for a first deployment so that persistence, configuration and scheduling are not omitted.

docker run -d \
  --name trendradar-mcp \
  -p 3333:3333 \
  -v ./config:/app/config \
  wantcat/trendradar-mcp

Parameter explanation:

-d: run the container in the background
--name trendradar-mcp: give the container a name for easier management later
-p 3333:3333: map port 3333 inside the container to the host
-v ./config:/app/config: mount the local config directory into the container

The docker run method for the push service

The docker run command for the push service (trendradar) is similar to the above, but you need to additionally mount the output directory for data persistence, and pass environment variables via the -e flag. We recommend the Docker Compose method, as the configuration is clearer.

Access the built-in report server

In cron mode, TrendRadar starts a built-in server for viewing generated web reports.

Default address: http://127.0.0.1:8080

Changing the port: Set WEBSERVER_PORT in docker/.env.

Remote access: Compose binds to the server's own 127.0.0.1 by default. On a NAS or VPS, opening localhost:8080 on your laptop will not reach it. Use an SSH tunnel or an access-controlled reverse proxy; do not expose it directly to the public internet.

Common management commands

Below are the commands commonly used for the day-to-day management of TrendRadar containers. You can run these commands directly in a terminal to manage and monitor the services.

Configuration diagnostics and connectivityRun these first

Run these after changing your configuration; none of them starts a news crawl.

Environment health checkCheck configuration, AI settings, storage and output access

docker exec -it trendradar python -m trendradar --doctor

Notification testSend one real test message to every valid channel

docker exec -it trendradar python -m trendradar --test-notification

Current scheduleShow the time period and crawl, analysis and push switches

docker exec -it trendradar python -m trendradar --show-schedule

--doctor writes output/meta/doctor_report.json, but only validates the AI model, API key and model format. It does not send a real model request, so it is not an LLM connectivity test.

In-container management tool

Use the image's built-in manage.py to inspect the service or run one task manually.

Container statusCheck supercronic, configuration files and scheduled tasks

docker exec -it trendradar python manage.py status

Run one crawl nowActually runs the crawl, analysis and push flow

docker exec -it trendradar python manage.py run

Live logsContinuously read logs from inside the container

docker exec -it trendradar python manage.py logs

Current configurationShow environment settings with secrets masked

docker exec -it trendradar python manage.py config

Output filesList databases, snapshots and report files

docker exec -it trendradar python manage.py files

Report web server

Manage the static web service used to browse the output directory and historical HTML reports.

Start report serverServe static reports on the port configured by WEBSERVER_PORT

docker exec -it trendradar python manage.py start_webserver

Stop report serverStop the separate static report process

docker exec -it trendradar python manage.py stop_webserver

Check server statusShow the process, port and report URL

docker exec -it trendradar python manage.py webserver_status

Docker container operations

Use native Docker commands to inspect logs, control the container and update the image.

Follow logsPress Ctrl+C to exit without stopping the container

docker logs -f trendradar

Restart containerRestart the crawler service

docker restart trendradar

Stop containerStop the crawler service

docker stop trendradar

Remove stopped containerRemove the container itself without deleting mounted configuration or output

docker rm trendradar

Update and restartPull the latest image and recreate the service

cd docker
docker compose pull trendradar
docker compose up -d trendradar

Data persistence

TrendRadar's runtime data (crawl results, push history, HTML reports, etc.) is stored in the output/ directory inside the container.

Important note

When deploying via Docker Compose, docker-compose.yml already mounts the output/ directory to the host, so data is persisted automatically. Even if you delete and recreate the container, the data is not lost. If you deploy using the docker run method, be sure to mount the output directory via the -v flag, otherwise the data will be lost after the container is deleted.

For more about remote backup solutions using S3-compatible storage, refer to the "Storage Configuration" chapter.