Deploy the Center

简体中文 | English

The Center runs on Linux with Docker Engine and Docker Compose. The official image supports linux/amd64 and linux/arm64. Release validation runs the Center with a 512 MiB memory limit.

Standard Deployment

This option publishes port 8080 on the host for direct access or an existing host-level reverse proxy.

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. The default login is admin / admin. The username and password can be changed under Account.

Example compose.yaml:

services:
  center:
    image: ghcr.io/ipchronicle/ipchronicle-center:latest
    restart: unless-stopped
    environment:
      IPCHRONICLE_ADMIN_USERNAME: ${IPCHRONICLE_ADMIN_USERNAME:-admin}
      IPCHRONICLE_ADMIN_PASSWORD: ${IPCHRONICLE_ADMIN_PASSWORD:-admin}
    ports:
      - "${IPCHRONICLE_HTTP_PORT:-8080}:8080"
    volumes:
      - ./data/config:/var/lib/ipchronicle/config
      - ./data/history:/var/lib/ipchronicle/history
      - ./data/logs:/var/lib/ipchronicle/logs

Example .env:

IPCHRONICLE_HTTP_PORT=8080
IPCHRONICLE_ADMIN_USERNAME=admin
IPCHRONICLE_ADMIN_PASSWORD=admin
CLOUDFLARE_TUNNEL_TOKEN=

Bootstrap credentials apply only while config.db has no administrator account.

Cloudflare Tunnel

Create a Tunnel in Cloudflare Zero Trust and set its Public Hostname service to http://center:8080. Download the Tunnel Compose file and set the token in .env:

mkdir ipchronicle
cd ipchronicle
curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.cloudflare-tunnel.yaml" \
  -o 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

CLOUDFLARE_TUNNEL_TOKEN=your_Tunnel_token

Example Tunnel compose.yaml:

services:
  center:
    image: ghcr.io/ipchronicle/ipchronicle-center:latest
    restart: unless-stopped
    environment:
      IPCHRONICLE_ADMIN_USERNAME: ${IPCHRONICLE_ADMIN_USERNAME:-admin}
      IPCHRONICLE_ADMIN_PASSWORD: ${IPCHRONICLE_ADMIN_PASSWORD:-admin}
    volumes:
      - ./data/config:/var/lib/ipchronicle/config
      - ./data/history:/var/lib/ipchronicle/history
      - ./data/logs:/var/lib/ipchronicle/logs
    networks:
      - ipchronicle_network

  cftunnel:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    environment:
      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN:?CLOUDFLARE_TUNNEL_TOKEN is required}
    command:
      - tunnel
      - --no-autoupdate
      - run
    networks:
      - ipchronicle_network

networks:
  ipchronicle_network:
    name: ipchronicle_network

This creates the explicit Docker network ipchronicle_network. The Center does not publish a host port in this deployment.

Data Directories

Both deployment options store persistent data under the installation directory:

• ./data/config: config.db and master.key;
• ./data/history: history.db;
• ./data/logs: independent operational logs in logs.db, managed by the log retention policy.

The master.key decrypts proxy and notification credentials. Preserve it with its matching config.db.

Reverse Proxy and TLS

IPChronicle does not issue TLS certificates or modify a reverse proxy. The standard deployment can sit behind Nginx, Caddy, or another reverse proxy. Forward the original host, client address, and protocol, and allow WebSocket Upgrade under /api/v1/agent/sync/.

Minimal Nginx configuration:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Manage the external origin under Settings > System. Automatic mode uses the current browser origin. A custom value is used in Agent installation commands and notification links. HTTP remains usable and displays a security warning.

Source examples

The main branch contains compose.yaml, compose.cloudflare-tunnel.yaml, and .env.example. The main branch may change ahead of the next stable release. The deployment commands above download files from the current Latest Release.