Initial commit: connected-papers / linked-papers app

2026-07-09 12:13:48 +00:00
commit 7d76059d0e
12 changed files with 926 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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
+
+```bash
+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):
+
+```caddy
+papers.ahlgrim.bzh {
+    reverse_proxy connected-papers:5000
+}
+```
+
+Then reload Caddy:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+# View logs
+docker-compose logs -f
+
+# Restart
+docker-compose restart
+
+# Stop
+docker-compose down
+
+# Rebuild after code changes
+docker-compose up -d --build
+```