docker-compose up will leave you with working ukeeper-readability service (both API and frontend) running on http://localhost:8080.
| Command line | Environment | Default | Description |
|---|---|---|---|
| address | UKEEPER_ADDRESS | all interfaces | web server listening address |
| port | UKEEPER_PORT | 8080 |
web server port |
| mongo-uri | MONGO_URI | none | MongoDB connection string, required |
| frontend-dir | FRONTEND_DIR | /srv/web |
directory with frontend files |
| token | UKEEPER_TOKEN | none | token for API endpoint auth |
| mongo-delay | MONGO_DELAY | 0 |
mongo initial delay |
| mongo-db | MONGO_DB | ureadability |
mongo database name |
| creds | CREDS | none | credentials for protected calls (POST, DELETE /rules) |
| cf-account-id | CF_ACCOUNT_ID | none | Cloudflare account ID for Browser Rendering API |
| cf-api-token | CF_API_TOKEN | none | Cloudflare API token with Browser Rendering Edit perm |
| openai-api-key | OPENAI_API_KEY | none | OpenAI API key; enables auto-evaluation when set |
| openai-model | OPENAI_MODEL | gpt-5.4-mini |
OpenAI model for evaluation |
| openai-max-iter | OPENAI_MAX_ITER | 3 |
max evaluation iterations per extraction |
| dbg | DEBUG | false |
debug mode |
| Command line | Environment | Default | Description |
|---|---|---|---|
| openai.api-key | OPENAI_API_KEY | none | OpenAI API key for summary generation |
| openai.model-type | OPENAI_MODEL_TYPE | gpt-4o-mini |
OpenAI model name (e.g., gpt-4o, gpt-4o-mini) |
| openai.disable-summaries | OPENAI_DISABLE_SUMMARIES | false |
disable summary generation |
| openai.summary-prompt | OPENAI_SUMMARY_PROMPT | built-in | custom prompt for summary generation |
| openai.max-content-length | OPENAI_MAX_CONTENT_LENGTH | 10000 |
maximum content length to send to OpenAI API (0 for no limit) |
| openai.requests-per-minute | OPENAI_REQUESTS_PER_MINUTE | 10 |
maximum OpenAI API requests per minute (0 for no limit) |
| openai.cleanup-interval | OPENAI_CLEANUP_INTERVAL | 24h |
interval for cleaning up expired cached summaries |
When both --cf-account-id and --cf-api-token are set, the service uses Cloudflare Browser Rendering API to fetch page content instead of direct HTTP. This renders JavaScript and handles bot-protection pages that return empty or "just a moment..." responses to standard HTTP requests.
When these flags are not set, the service uses a standard HTTP client (default).
When --openai-api-key is set, the service automatically evaluates extraction quality using OpenAI. If the extracted content looks poor (missing article body, too short, mostly boilerplate), GPT suggests a CSS selector targeting the main content. The service iterates up to --openai-max-iter times, saving the best selector as a rule for future use.
Evaluation only runs for domains without an existing extraction rule. For domains that already have rules, use the force-mode endpoint to re-evaluate:
POST /api/content-parsed-wrong?url=http://example.com/article
This protected endpoint (requires basicAuth credentials) ignores the stored rule, re-extracts with the general parser, and runs the evaluation loop to find a better selector.
When OpenAI is not configured, extraction works exactly as before — no GPT calls are made.
GET /api/content/v1/parser?token=secret&url=http://aa.com/blah - extract content (emulate Readability API parse call)
GET /api/content/v1/parser?token=secret&url=http://aa.com/blah&summary=true - extract content with AI-generated summary
POST /api/extract {url: http://aa.com/blah} - extract content
GET /api/metrics - summary generation metrics (cache hits, misses, response times)
POST /api/content-parsed-wrong?url=http://aa.com/blah - force re-extraction with AI evaluation (requires basicAuth)
Summary generation requires a valid token and an OpenAI API key. Summaries are cached in MongoDB with a 1-month expiration. Expired summaries are cleaned up automatically on the configured interval.
To run the full test suite, you need MongoDB running without authorisation on port 27017. To start such Mongo instance, check comments in docker-compose.yaml file and run Mongo according to them.
Command to run full test suite would be:
ENABLE_MONGO_TESTS=true go test ./...