IPChronicle Documentation

简体中文 | English

IPChronicle is a public-IP quality and history system for individual self-hosting operators. A root Agent discovers reachable public IPv4 and IPv6 egresses on managed Linux nodes and runs complete probes. The Center manages nodes, reports, history, and notifications.

Current stable release

This documentation covers v0.1.1. Installation assets and frozen documentation for a specific version remain authoritative in its GitHub Release.

Quick Start

Install Docker Engine and Docker Compose on a Linux server, then run:

mkdir ipchronicle
cd ipchronicle
curl --proto '=https' --tlsv1.2 -fLO \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.yaml"
curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/default.env.example" \
  -o .env
docker compose up -d

Open http://server-address:8080 and sign in with admin / admin. Then:

1. Change the credentials under Account and enable TOTP if desired.
2. Open Nodes, generate an enrollment key, and copy the install command.
3. Run that command as root on a managed Linux node.
4. Confirm its discovered public IPs and start the first complete probe.

See Deploy the Center for Cloudflare Tunnel, reverse proxy, and data-directory details.

Core Capabilities

• Discover distinct public egresses reachable directly, through NAT, or through a node-scoped proxy.
• Run complete quality probes against actual public IPs and retain raw and structured reports.
• Record meaningful public-IP and probe-field changes, compare snapshots, and apply a retention policy.
• Send text or image notifications through Telegram, webhooks, or isolated JavaScript senders.
• Operate one self-hosted instance through a Chinese or English interface.

Product Boundaries

• One instance serves one administrator; there is no multi-user, tenant, or public-results mode.
• The Center is supported on Linux with Docker Compose.
• Agents connect outbound to the Center and need no inbound management port.
• The server operator manages TLS and the reverse proxy. HTTPS is recommended for external connections.
• Probe targets come from public egresses confirmed by an Agent. Arbitrary IPs cannot be entered manually.

Documentation

• Supported environments
• Deploy the Center
• Install an Agent
• Nodes and public IPs
• Complete probes and history
• Notifications
• Configuration reference
• Updates and recovery

Product source is maintained in ipchronicle/ipchronicle. Product definitions and architecture decisions are maintained in ipchronicle/workspace.