How to Build TrendRadar from Source: Complete Docker Build Guide

Build TrendRadar locally using Docker Compose with a multi-stage Dockerfile that compiles Python 3.12 dependencies via uv and produces two images: wantcat/trendradar for news crawling and wantcat/trendradar-mcp for AI analysis.

TrendRadar is an open-source news aggregation and push-notification service distributed as containerized images. This guide walks through the complete TrendRadar build steps from the official repository, covering cloning, multi-stage Docker builds, architecture targeting, and deployment.

---

Prerequisites

Before building TrendRadar, ensure you have:

• Docker 20.10+ with Buildx support
• Docker Compose plugin (v2.0+)
• Git for cloning the repository

The build process uses uv (a fast Python package installer) inside the container, so no local Python installation is required.

---

Step 1: Clone the TrendRadar Repository

Retrieve the complete source tree including Docker assets, configuration templates, and the trendradar Python package:

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

The repository structure includes:

• docker/ — Build and runtime configurations
• config/ — Runtime settings and keyword filters
• trendradar/ — Core Python source code
• pyproject.toml and uv.lock — Locked dependency manifests

---

Step 2: Select the Build-Ready Compose File

TrendRadar provides two compose configurations. Switch from the runtime version (pulls pre-built images) to the build version (compiles locally):

cd docker
cp docker-compose-build.yml docker-compose.yml

The docker-compose-build.yml file defines build contexts for both services with explicit build: sections targeting docker/Dockerfile.

---

Step 3: (Optional) Set Target Architecture

Control which supercronic binary (internal job scheduler) is downloaded by setting the DOCKER_ARCH environment variable:

# For Apple Silicon, Raspberry Pi, or other ARM64 devices

export DOCKER_ARCH=arm64

# For standard x86_64 servers (default if unset)

export DOCKER_ARCH=amd64

This variable is consumed in the Dockerfile at lines 13-22, which conditionally downloads the appropriate supercronic release.

---

Step 4: Build the TrendRadar Docker Images

Execute the multi-stage build. You can build both services or target them individually:

# Build both images simultaneously

docker compose build

# Or build specific services

docker compose build trendradar
docker compose build trendradar-mcp

The multi-stage build in docker/Dockerfile performs:

1. Stage 1 — Download supercronic for the target architecture
2. Stage 2 — Copy the uv binary, install locked Python dependencies via uv sync --locked
3. Stage 3 — Copy project source code and install the trendradar package itself

The uv.lock file ensures reproducible builds with exact dependency versions.

---

Step 5: Deploy and Run the Containers

Start the services in detached mode:

# Run both crawler and AI analysis server

docker compose up -d

# Or run only the news crawler

docker compose up -d trendradar

# Or run only the MCP AI server

docker compose up -d trendradar-mcp

Service behavior:

• trendradar — Launches supercronic via docker/entrypoint.sh to run the scheduled news crawler
• trendradar-mcp — Opens an HTTP API on 127.0.0.1:3333 for AI-powered content analysis

---

Step 6: Verify and Manage the Build

Confirm successful deployment and interact with running services:

# Check container status

docker compose ps

# View crawler logs in real-time

docker logs -f trendradar

# Check service health status

docker exec -it trendradar python manage.py status

# Trigger manual crawl immediately

docker exec -it trendradar python manage.py run

The docker/manage.py script provides a CLI interface for common operational tasks without restarting containers.

---

Key Build Files Reference

File	Purpose	Location
docker/Dockerfile	Multi-stage build definition with supercronic, uv, and package installation	docker/Dockerfile
docker/docker-compose-build.yml	Compose configuration for local builds	[docker/docker-compose-build.yml](https://github.com/sansan0/TrendRadar/blob/master/docker/docker-compose-build.yml)
docker/entrypoint.sh	Container entrypoint launching supercronic	[docker/entrypoint.sh](https://github.com/sansan0/TrendRadar/blob/master/docker/entrypoint.sh)
docker/manage.py	Operational CLI for status, manual runs, and logs	[docker/manage.py](https://github.com/sansan0/TrendRadar/blob/master/docker/manage.py)
pyproject.toml / uv.lock	Locked Python dependencies for reproducible builds	[pyproject.toml](https://github.com/sansan0/TrendRadar/blob/master/pyproject.toml)

---

Summary

• Clone the repository from https://github.com/sansan0/TrendRadar.git
• Switch to the build compose file: cp docker/docker-compose-build.yml docker/docker-compose.yml
• Optionally set DOCKER_ARCH=arm64 for ARM64 builds
• Build with docker compose build (multi-stage: supercronic, uv deps, package install)
• Deploy with docker compose up -d and verify with docker logs and manage.py

The entire build process is containerized, requiring only Docker and producing reproducible images for both the news crawler and optional AI analysis server.

---

Frequently Asked Questions

What is the minimal command to build and run TrendRadar?

Clone, switch compose files, build, and start:

git clone https://github.com/sansan0/TrendRadar.git && cd TrendRadar
cd docker && cp docker-compose-build.yml docker-compose.yml
docker compose build
docker compose up -d

Can I build TrendRadar for ARM64 devices like Raspberry Pi?

Yes. Set export DOCKER_ARCH=arm64 before building. The Dockerfile automatically downloads the ARM64 version of supercronic. Omit this variable for default AMD64 builds.

How do I verify the build succeeded without running the full service?

Check image creation with docker images | grep trendradar, then inspect a single layer: docker run --rm wantcat/trendradar python -c "import trendradar; print('OK')". The container should exit cleanly with confirmation output.

What is the difference between the trendradar and trendradar-mcp images?

The trendradar image runs the scheduled news crawler and push-notification service using supercronic. The trendradar-mcp image (built from the same Dockerfile with a different target) provides an optional AI analysis server exposing an HTTP API on port 3333.

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