kite-epub-sync

Fetch several RSS feeds and combine their complete previews into one EPUB. The EPUB table of contents nests each story beneath its feed section.

Create .env:

RSS_FEEDS=https://news.kagi.com/world.xml;https://news.kagi.com/usa.xml;https://news.kagi.com/canada.xml;https://news.kagi.com/business.xml;https://news.kagi.com/tech.xml
OUTPUT=kite-news-{date}.epub
TITLE=Kite News — {date}

Then run:

go run .

Every command-line flag has an environment counterpart:

Flag	Environment variable	Default
-output	OUTPUT	kite-news.epub
-title	TITLE	Kite News — {date}
-cleanup-old	CLEANUP_OLD	false

Flags take precedence over environment or .env values. Use {date} anywhere in OUTPUT or TITLE to insert today's local date as YYYY-MM-DD. Feed order is preserved. To override a section name, prefix its URL with a label, for example Technology|https://example.com/tech.xml.

Docker

Build the image and run it with a persistent output directory:

docker build -t kite-epub-sync .
docker run -d --name kite-epub-sync \
  -v "$PWD/output:/output" \
  kite-epub-sync

An example Compose configuration is also included. Every supported environment variable is present with its default value and commented out:

docker compose -f compose.example.yml up -d --build

For non-Compose configuration, copy .env.example to .env and uncomment the values you want to override. The example files are compose.example.yml and .env.example.

Kagi News refreshes around noon UTC and may take about 30 minutes to finish. The container therefore defaults to running every day at 12:45 UTC:

CRON=45 12 * * *
TZ=UTC
RUN_ON_STARTUP=false
CLEANUP_OLD=false

Override the schedule, title, or output filename with container environment variables:

docker run -d --name kite-epub-sync \
  -e 'CRON=15 13 * * *' \
  -e 'RUN_ON_STARTUP=true' \
  -e 'CLEANUP_OLD=true' \
  -e 'TITLE=Daily Brief — {date}' \
  -e 'OUTPUT=/output/daily-{date}.epub' \
  -v "$PWD/output:/output" \
  kite-epub-sync

CRON uses the standard five-field format and is interpreted in TZ, which defaults to UTC. Set RUN_ON_STARTUP=true to create a book immediately before the cron daemon starts. Scheduled output is written to /output by default.

Set CLEANUP_OLD=true to remove older dated EPUBs after each successful export. Cleanup only considers regular files matching the configured OUTPUT template; it requires {date} exactly once in the filename, preserves today's and future files, and does not run when fetching or writing the new book fails.

Komga scan

To ask Komga to scan the library after a successful export and optional cleanup, set:

KOMGA_SYNC=true
KOMGA_URL=http://komga:25600/api/v1/libraries/YOUR_LIBRARY_ID/scan
KOMGA_API_KEY=YOUR_ADMIN_API_KEY

KOMGA_URL must be the complete Komga library scan endpoint, including the library ID. The exporter sends an authenticated POST with the API key in the X-API-Key header. No request is made when KOMGA_SYNC=false, which is the default. A failed Komga request is reported as an error but does not remove the EPUB that was already generated.

Forgejo workflows

The workflows under .forgejo/workflows provide:

• Go formatting, vet, test, binary-build, and container-build checks for pull requests targeting main.
• Publication of latest and commit-SHA image tags after those checks pass on a push to main.
• Manual publication of a SHA-tagged review image for a selected ref.
• Publication of a PR head as a SHA-tagged review image when the review-image label is added, followed by a PR comment containing the tag.

Image publishing requires repository secrets named REGISTRY_USERNAME and ACCESS_TOKEN. Create the review-image repository label with that exact name. The labeled workflow runs when the label is added; to publish a later commit from the same PR, remove and re-add the label after the PR has updated.