Connected Papers (Local)

A lightweight, self-hosted web app for exploring academic paper reference graphs. Search for a paper and see an interactive graph of the papers it cites. Dot size is proportional to citation count.

Features

Search by paper title, DOI, or arXiv ID
Interactive force-directed graph (vis-network)
Node size based on citation count
Click a node to see details; double-click to re-center the graph
File-based JSON cache (survives container restarts)
Works offline for previously cached graphs
Uses OpenAlex for all paper data
Shows only outgoing references (papers the seed paper cites)
Dockerized and ready to plug into your existing Caddy reverse proxy

Data Source

OpenAlex API: https://openalex.org/

OpenAlex is free. Anonymous usage has rate limits; if you hit them often, get a free API key and set it in a .env file (see below).

Quick Start

cd /root/connected-papers

# Build and run
docker-compose up -d --build

# Open locally
# http://127.0.0.1:5000

Caddy Integration

Add a new site block to /root/caddy/Caddyfile (adjust the subdomain to your preference):

papers.ahlgrim.bzh {
    reverse_proxy connected-papers:5000
}

Then reload Caddy:

cd /root/caddy
docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile

The container is already attached to the caddy_mesh Docker network, so Caddy can reach it by the service name connected-papers.

Configuration

Edit docker-compose.yml to tune these environment variables:

Variable	Default	Description
`CACHE_TTL_DAYS`	30	Days before cached graph is refreshed
`SEARCH_LIMIT`	20	Number of search results, sorted by citation count
`REFERENCE_LIMIT`	100	Top N papers cited by the seed paper (outgoing)
`OA_API_KEY`	(none)	OpenAlex API key (higher rate limits)
`OA_EMAIL`	(none)	Email for OpenAlex polite pool (recommended)

Getting an API key (optional but recommended)

OpenAlex: https://openalex.org/rest-api

Copy .env.example to .env, add your key, and restart:

cp .env.example .env
# edit .env with your OA_API_KEY and OA_EMAIL
docker-compose up -d

Cache

Cached graphs are stored as JSON files in ./cache/. To clear the cache:

rm -f cache/*.json

You can also inspect the cache files directly — they are plain JSON.

Troubleshooting

429 / "Too Many Requests" or 503 from OpenAlex

The public IP you are running from has hit OpenAlex's rate limit. Set OA_API_KEY and OA_EMAIL for higher limits.

Offline mode

If the APIs are unreachable but a cached graph exists, the app returns the cached graph automatically.

Useful Commands

# View logs
docker-compose logs -f

# Restart
docker-compose restart

# Stop
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

2.9 KiB Raw Blame History