Changelog¶
v1.3.1 — 2026-11-11¶
Fixes for full-article feeds, XPath recipes, the visual selector and first starts, and a documentation site. Articles that always fail no longer use up every refresh's article requests, Convert to XPath converts the article selector and cleanup rules too, CSS left in an XPath selector is pointed out, pages pasted from Word open in the visual selector, startup says what to fix when it cannot write to the data directory, and the dashboard and /metrics answer while Chromium starts. The database stays at schema 6 and there is no new setting, so going back to v1.3.0 is an image swap.
Upgrading from v1.3.0¶
- The database is unchanged. This version keeps schema 6 and opens a v1.3.0 database as it is: SQLite saves no pre-upgrade copy and PostgreSQL logs no migration. To roll back, set
RSS_IMAGE=ghcr.io/ldogg123/rss-workshop:v1.3.0-browser, orghcr.io/ldogg123/rss-workshop:v1.3.0-staticwithcompose.static.yaml, or the image digest you saved, or start the v1.3.0 executable again; nothing needs restoring. From v1.2.0 or older, also follow Upgrading from v1.2.0. - No configuration changes. There is no new setting, and the Compose files,
.envsettings andscripts/backup.pyare as v1.3.0 shipped them, so a v1.3.0 checkout runs the new images. Update it for the corrected guides or to build from source. - Recipe files and backups work in both versions. Recipes gain no field: v1.3.0 imports every file this version exports, and this version imports every file v1.3.0 exports. A backup taken with either version restores into either.
- Upgrading changes no feed. No published byte, GUID, date,
Last-Modifiedor ETag moves, so readers keep receiving 304. A full-content feed still changes, as it always has, when a story gets its article, which now includes stories that were stuck behind failing ones. - With SQLite, a data directory the app cannot write to now stops startup. v1.3.0 could still start from such a directory in one case: when
rss.db,rss.db-walandrss.db-shmwere all there and writable, which happens when the directory's owner or mode was changed while the app was running. If this version stops withcannot write to the data directory, give the directory back to the app's user and start again; with Docker Compose that issudo chown 65532:65532 <your RSS_DATA_DIR>. The refusal changes no data. The check creates and removes an empty file named.write-check; in a directory that does not allow files to be removed (append-only, or a network share without the delete right) the app starts as before, that one file stays, and a warning says so at each start. See deployment. - Check full-content feeds you converted to XPath before this version. This release does not rewrite saved recipes. A feed that was converted with Convert to XPath in v1.3.0 or earlier and uses Full article content may still hold a CSS article selector under the XPath selector type. The signs are article bodies that contain the whole page, or the Diagnostics warning
article selector matched nothing on the item pagefor each article a refresh tries. Such articles now wait before another try, as described below, and a refresh then shows only the lineArticles waiting to be tried again after failing or coming back empty: N; Preview items in the editor tries the first 3 articles at once and shows either sign. Open the feed's editor, rewrite Article body as XPath (for example//div[@class='entry-content']) and save. Saving discards the stored article bodies; later refreshes fetch them again for the stories still on the list page, and older stories keep their list-page description. Feeds that were never converted are unaffected. - CSS left in an XPath selector now shows a warning, and new saves refuse it. A feed saved earlier with one, for example a Description of
.summaryunder the XPath selector type, keeps refreshing and publishing exactly as before. It now shows a warning naming that selector in Preview items and in the Diagnostics of each refresh that reads the page; a refresh the source answers with304 Not Modifiedrecords none, so check with Preview items. Saving a new feed, a duplicate, or an edit that changes such a selector or switches the type to XPath is refused with the same explanation, which also applies to scripts that save feeds through the API (POST /api/feedsandPUT /api/feeds/{id}). Recipe imports are not affected. - Failed articles wait before they are tried again. v1.3.0 tried a story's failed article again at every refresh. Now, once the story is an hour old, it waits an hour after a failure of its own page (an HTTP error status, a selector that matches nothing, an empty article), then twice as long after each further one, up to 24 hours. An article that the site publishes or repairs later can therefore take up to a day to be picked up; Refresh on the feed's card ends the wait. One case is slower than v1.3.0 even without a wait: stories whose article has not been tried go first, so a story whose article failed once is tried again only after the rest of the list has had its first try, which on a long list is some refreshes later. Sources receive fewer repeated requests for pages that fail. See Fixes below.
- Scripts that switch a feed's source get
400. APUT /api/feeds/{id}that changes a saved feed'srecipe.typeto or fromfeedis now refused and leaves the feed unchanged. Create a new feed with the other source instead (POST /api/feeds, or Duplicate in the library). - Go 1.27.4, and the same Chromium. The executables and both images are built with Go 1.27.4. The browser image keeps Chromium 156.0.8078.79, the newest version Debian offers today; a release with the next Chromium follows when Debian publishes it.
New¶
- Read the guides as a searchable documentation site, built from the same Markdown as the files in
docs/. It follows themainbranch, so it can be ahead of the latest release. It also publishes the demo newspaper and copies of the example recipes that use its address, so a first feed can be tried without serving the demo or anALLOW_CIDRSexception; see examples. The site loads no fonts, scripts or images from other origins.
Changes¶
- Update Go to 1.27.4, which has security fixes to the toolchain and
net/http.govulncheckreports no vulnerability the app reaches, before or after. make docs-testchecks every link and anchor in the guides and is part ofmake check;make docsbuilds the site andmake docs-servepreviews it. Building the site needs Python 3.11.5 or newer; the checks need only 3.11. See contributing.make browser-testnow renders real 404 and 500 pages, pages whose embedded frame answers differently from the page, and a 404 served over HTTPS and HTTP/2, and requires Chromium mode to report the page's own HTTP status. Chromium reports that status only through a DevTools event, so a Chromium update the app's DevTools library cannot fully decode could otherwise turn failing source pages into successful renders unnoticed. If you build the browser image with anotherCHROMIUM_VERSION, run it; the browser guide says what a pass does not prove, and now also how rendered HTTP errors are reported.
Fixes¶
- Stop articles that always fail from using up the article requests of every refresh. A refresh fetches at most 10 article pages and took the listed stories without an article in list order, so stories whose article always failed, such as paywalled or removed pages or a template the selector does not match, headed the queue every time: with ten of them, no story behind them ever got its article, and the source received the same ten failing requests at each refresh. A rendered article page that never loaded likewise used up the rest of each refresh's deadline, and an article that came back empty was fetched again at every refresh without a warning. Stories whose article has not been tried now go first. After a failure of its own page (an HTTP error status, an article that could not be extracted, or an empty article) a story waits an hour before it is tried again, doubling up to 24 hours, except in its first hour, when it is still tried at each refresh. A failed connection, the refresh's deadline, or Chromium or FlareSolverr being unavailable never makes a story wait. On a list page longer than
MAX_ITEMS, the stories that retention removes as soon as their article is fetched are fetched again as before, but after the failed articles that are due. Diagnostics counts the waiting stories in the first warning of each run, Refresh and resuming a feed end the wait, and saving the feed or restarting the app tries every story again. Nothing is stored and no setting is added. See full article content. - Convert the article selector and cleanup rules with the rest of the recipe. Convert to XPath in the visual selector rewrote the repeated-item and field selectors and set the feed's selector type to XPath, but left Full article content's article body selector and the Content cleanup rules in CSS. Read as XPath, an article selector such as
.entry-contentselects the whole page, so every new story's article was the entire page, navigation included, with no error; one such asdiv.entry-contentmatched nothing, so every article failed and kept its list-page description; and a CSS cleanup rule made the save fail withXPath cleanup rule 1 must start with ./. Conversion now rewrites the article selector as an absolute path and each rule as a path relative to its block, and writes both into the editor. Element and attribute names are written in lowercase, because XPath compares them exactly. If either setting has no XPath form the conversion supports, such as a:containsOwn()rule, the message names it and every selector stays CSS. That includes an article selector that lists alternatives (.entry-content, article): only its first match is published, and XPath could take a different one, so write it by hand as the guide shows. Saving a converted feed changes its article selector, so its stored article bodies are discarded and fetched again for the stories still listed, as with any edit of that selector. See visual selection. - Catch CSS left in an XPath selector. The XPath library reads only the first complete expression of a selector and ignores the rest, so a CSS class selector left after changing Selector type by hand, such as
.summary, ran as.: the description became the whole card, an article body selector.entry-contentthe whole article page, and a repeated-item selector.postone item spanning the page, while the visual selector called the same text invalid. Preview items and the import review now show a warning that names the selector without quoting it, each refresh that reads the page records it in Diagnostics, and saving refuses such a selector when the save introduces it: in a new feed or a duplicate, when its text changed, or when the feed's type has just become XPath. Feeds already saved with one keep publishing what they did, and recipe files holding one still import. This covers the repeated-item selector, the five fields and the article body selector; cleanup rules already had to start with./. CSS that is also a valid XPath name, such asarticle.card, is not detected and matches nothing. The article body field's placeholder and hint now follow the selector type. See limits. - Open pages with prefixed or unusual element names in the visual selector. A page containing an element such as Word's
<o:p>or<st1:City>, a widget's<fb:like>, or an address written as<editor@example.com>was refused withpage contains unsupported element names, which ruled out most text pasted from Word. Such an element is now kept as a hidden placeholder: it holds its place among its siblings, so the positional CSS and XPath the picker suggests for the elements around it, and:nth-childtyped by hand, match in the preview as they do in extraction, while its name, attributes and contents are not sent to the browser. Its own text is missing from the preview and nothing inside it can be picked. An element of this kind that the page never closes, such as<fb:like ... />, holds everything up to the end of its parent, so the preview can show only part of such a page or none of it; the picker's status then says that part of the page cannot be shown, and the selectors for that part have to be typed by hand and checked with Preview items. Extraction, saved feeds and published output are unchanged. See limits. - Say what to fix when the data directory or the sign-in address is refused. With SQLite, a data directory the app may not write to, such as a host directory still owned by root on a first Docker start, stopped startup with
unable to open database file (14), orattempt to write a readonly database (1544)when a database was already there. Startup now checks the directory before opening the database and names it, the user the app runs as and the fix:sudo chown 65532:65532 <your RSS_DATA_DIR>with Docker Compose, or mounting it read-write when the file system is read-only. A directory copied or restored as another user also holds database files the app may not write; startup names the file and the recursivesudo chown -R 65532:65532 <your RSS_DATA_DIR>. PostgreSQL deployments are not checked. A sign-in or save from an address other than the configured one is now refused withcross-origin request rejected; open the app at the address set in PUBLIC_BASE_URLin place ofopen the app using its configured address; the message names the setting and never its value, and which addresses are accepted is unchanged. See deployment. - The dashboard and
/metricsno longer wait while Chromium starts. Reading the pool's status waited for each launch to finish: the first one, the relaunch after a crash and the routine relaunch after every 100 renders. That is normally a moment, but when Chromium hung while starting, each render attempt held the library listing that the dashboard polls every 10 seconds, and/metrics, for 10 seconds and at most 15. A Prometheus scrape with the default 10-second timeout then failed, which read as the app being down. Both now answer at once. During a launchrss_workshop_browser_readyis0, and the render waiting for it counts inrss_workshop_browser_activeonly once Chromium is running. See metrics. - Refuse switching a saved feed between a web page and a feed source on the server. A web page's stories are identified by their link and a feed source's by their
guid, so a switch stores every story the source still lists again under a new GUID, and readers see them twice. Only the editor's locked Source control prevented it: aPUT /api/feeds/{id}from a script was saved. Such a save is now answered with400and a message that points to Duplicate, and changes nothing. Changing a page between CSS and XPath, editing a feed source, new feeds and imports are unaffected. - Leave
htmlUrlout of the OPML export for feed sources. The export gave every feed's source address ashtmlUrl, and for a feed source that address is the upstream RSS or Atom document, so the export listed raw XML as the feed's website. Such entries now carry nohtmlUrl; theirxmlUrlis unchanged, entries for web pages are byte for byte what they were, and no published RSS or Atom feed changes. A reader that already imported the old link keeps it until the subscription is edited or added again. - Say beside the editor's Remove already-saved stories that do not match these filters option what it judges. Each story is matched by its description as saved, which cleanup rules changed in the same edit have not cleaned, so adding a cleanup rule and a filter that depends on it in one edit could remove stories the next refresh would have kept. The hint now says so, as do the output and feed source guides. Save the change to Content cleanup, let a refresh run, then remove saved stories, as story filters describes. Pruning itself is unchanged.
v1.3.0 — 2026-11-07¶
Existing RSS and Atom feeds as sources, cleanup rules that take share bars and other clutter out of descriptions and articles, an Accept-Language you can set for one feed, and a Quiet badge that now means no new story, after a time each feed can choose. Full-article feeds whose source answers 304 finish fetching their articles, and Chromium feeds that fall due together no longer fail. The database moves to schema 6, so going back to v1.2.0 means restoring a backup.
Upgrading from v1.2.0¶
- Update your checkout first (
git pull). The v1.2.0scripts/backup.pyrefuses schema 6, so only the current one can back up an upgraded database; either one restores the schema 5 copy described below. There is no new setting, and the Compose files are unchanged. From v1.1.1 or older, also follow Upgrading from v1.1.1 and the notes of each release in between, which say which feeds change once. - The database moves to schema 6, in one transaction, the first time this version starts. Databases from v1.1.0, v1.1.1 and v1.2.0 are at schema 5; older ones take every step in the same transaction. Each feed gains the time it last saved a new story, which Quiet now measures from, starting at the time it first saw the most recently added of its saved stories. The upgrade changes no published byte, GUID, publication date,
Last-Modifiedor ETag, so readers keep receiving 304. Schema 6 also keeps older releases, which would ignore settings such as cleanup rules, from opening the database. - SQLite takes a copy for you. Before upgrading, the app saves a verified copy to
backups/pre-upgrade-schema-5-<time>in the data directory and names it in the log. It needs free space about the size of the database, which stored article bodies can make large; without that space, startup stops before changing anything. The copy sits on the same disk and is never deleted automatically, so keep an off-host backup too, and remove the copy once this version has been working.UPGRADE_BACKUP=falseskips it. See automatic copy. - PostgreSQL gets no automatic copy. Take a
pg_dumpbefore upgrading; the app logs a warning when it migrates. See PostgreSQL backups. The upgrade reads the whole stories table once, which on slow storage that has not cached it can take minutes, so a PostgreSQL schema upgrade now has up to 10 minutes, apart from the 10 seconds startup allows for connecting. The log saysPostgreSQL schema upgrade startedandPostgreSQL schema upgrade finished, with how long it took. Until then the app answers no request, and its health check, and sodocker compose up --wait, can report the container unhealthy while the upgrade goes on. An upgrade that runs out of time, or that a stop signal interrupts, rolls back on the server before the app exits, leaving the database at schema 5, and startup stops withcannot migrate PostgreSQL database from schema version 5 to 6: the upgrade did not finish within 10 minutes; the database is unchanged, orstartup was interruptedin place of the time limit. See schema upgrade time. - Rolling back is a restore, not an image swap. v1.2.0 and v1.1.x refuse a schema 6 database, so re-pinning the older image, as v1.2.0's notes describe, no longer works on its own. Going back loses the changes made since the upgrade: new feeds, edits, reset reader links, and stories, which are fetched again while their sources still list them. To keep feeds added since, export their recipes first and import them afterwards, without the new settings below; imported feeds get new reader links. If the migration itself failed, nothing changed, and v1.2.0 opens the database as it is. Otherwise stop the app and restore the
pre-upgrade-schema-5-*copy or a backup taken before upgrading into new storage, orpg_restorethe dump into a new database:- With Compose, restore the copy or backup with
sudo python3 scripts/backup.py restore(see restore into a new host directory). PointRSS_DATA_DIRorDATABASE_URLat the result, setRSS_IMAGEtoghcr.io/ldogg123/rss-workshop:v1.2.0-browser,ghcr.io/ldogg123/rss-workshop:v1.2.0-staticwithcompose.static.yaml, or the image digest you saved, and start the app. - With a native executable, the copy belongs to the user that runs the app, and
scripts/backup.py restorewould give the files to UID/GID 65532, the container's user, so the app could not open them. Instead, as the user that runs the app, copyrss.dbfrom the copy, or every file of your backup, into a new directory created withinstall -d -m 700. PointDATA_DIRorDATABASE_URLat the result and start the v1.2.0 executable from its release archive. See downgrades.
- With Compose, restore the copy or backup with
- Quiet now means "no new story". v1.2.0 marked a feed Quiet when its published output had not changed for 14 days, or 10 refresh intervals if that is longer. Now it is marked when no refresh has saved a new story for that long: one the feed did not have saved and that
MAX_ITEMSretention kept. Changed descriptions, images and article bodies no longer count, nor do stories retention removes. So:- Feeds whose descriptions change at every refresh, for example with a relative age or a comment count, could never turn Quiet before and may turn Quiet right after upgrading.
- Editing a feed's title, address or refresh interval no longer restarts the count once the feed has saved a story; for a feed that has never saved one, it still does.
rss_workshop_feeds_quiet, the Quiet status filter and the card follow the new rule, so review alerts built on the metric. The per-feed alert example in metrics now uses the newrss_workshop_feed_last_new_story_timestamp_secondswith a threshold of its own, so unlikerss_workshop_feeds_quietit ignores Mark as Quiet after.rss_workshop_feed_last_changed_timestamp_secondskeeps its meaning, so alerts built on it work as before.- For a site that publishes rarely, set the new Mark as Quiet after in its editor to a longer time or to Never, and leave such a feed out of a per-feed alert by its
idlabel.
- Full-article feeds send more full requests while articles are missing. So that a source answering
304 Not Modifiedno longer stops a full-content feed at the articles it has (see Fixes below), such a feed in Static HTTP or Auto requests its list page withoutETagandLast-Modifiedonce after each start, and again after each refresh that leaves stories without an article while adding more; conditional requests resume once the backlog drains or stops growing. Sources see these extra full requests, after every restart too. Chromium and FlareSolverr never sent validators and are unchanged. A feed changes only as articles are stored, except where its page lists more stories without a date thanMAX_ITEMSkeeps: each full request saves again, under a new first-seen time, the ones retention removed, as every refresh of a source without validators already does. See full article content. - Chromium refreshes wait for a free slot. A refresh in Chromium mode, or one that renders its article pages in Chromium, in any mode but FlareSolverr, now starts only while one of the
BROWSER_SLOTSis free. The rest stay due, without an error, a backoff or a notification, and start oldest first. A feed that renders its article pages now renders them one at a time instead of four, so a large backlog may take another refresh to fill in, and its preview fetches its three sample articles one at a time. An Auto feed that renders its article pages waits for a slot before its static list fetch too; other Auto feeds start as before, and their fallback render still waits for a slot inside the feed's deadline. Preview items and Choose elements visually are never refused for want of a Chromium slot, but may wait for one. A render that waits out its deadline for a slot now says so: its error starts withno free Chromium slot before the deadlineinstead of being a barecontext deadline exceeded. Nothing published changes. See Chromium capacity. - Recipe files that use the new settings need this version. v1.2.0 and older refuse a recipe file in which any feed sets
accept_language,removeorquiet_days(json: unknown field "remove", for example) or is a feed source (selector type must be css or xpath), and import none of its feeds. To import such a file there, remove those fields and leave feed sources out. Recipes that use none of them export byte for byte as before. See recipe export and import.
New¶
- Read an existing RSS or Atom feed as a source. Choose Source → RSS or Atom feed in the editor to read an RSS 0.9x or 2.0, RSS 1.0 (RDF) or Atom feed instead of selecting a page's cards, then filter its stories, use library filters, clean out clutter, fetch full articles and publish it behind its own private RSS and Atom links. The feed supplies each story's title, link, description, image and date, so a feed source has no selectors; it is fetched as Static HTTP, and its article selector and cleanup rules are CSS. Stories are identified by their
guid, Atomidorrdf:about, then their link, then their title. Untitled posts, as Mastodon publishes them, take the start of their text as a title, a post that is only a video embed publishes the entry's summary, and images an entry declares come before any image in its text, skipping images that declare a 0- or 1-pixel size, as tracking images do. The first 1,000 entries of a feed of up to 4 MiB are read; one malformed entry fails that refresh, and saved stories are kept. A saved feed cannot be switched between a web page and a feed source, because the two identify stories differently: Duplicate it and choose the other source in the copy. The demo site now ships its ownfeed.xml, read by the newdemo-feed-recipe.json. JSON Feed, feed autodiscovery and OPML subscription import are not supported. See feed sources. - Remove clutter from descriptions and articles. A feed can list selectors, one per line in the editor's new Content cleanup section, for parts to leave out of each description and article body, such as share bars, newsletter boxes or "Related" lists that the sanitizer keeps. Rules use the feed's selector type, CSS for a feed source, and match only inside the selected block, which is never removed; XPath rules start with
./. A feed has at most 20 rules, each on one line of at most 1,000 characters. They run before sanitizing, skip a description or article read from an attribute, and do not change a web page's story image. Story filters match the cleaned description, while removing nonmatching saved stories judges the descriptions as stored. A description the rules empty is dropped with the warningcleanup removed the whole description; an article they empty keeps its list-page description and reportsarticle body is empty after cleanup. Changing a full-content feed's rules discards, in the same save, the article bodies of the stories its latest stored refresh listed, unless the feed names an Article attribute, and later refreshes fetch them again, 10 at a time, even from a source that answers 304; other stories keep their description and article as they were. On a feed without full article content, or one with an Article attribute, a change publishes nothing until the next refresh. Recipes without rules extract, store and export exactly the same bytes as before. Preview, Duplicate, recipe export and import, and the import review carry the rules, stored in the recipe asremove. See content cleanup. - Set an Accept-Language for one feed under Request settings in its editor, such as
enorde-CH, de;q=0.9, en;q=0.5, at most 10 language ranges in 128 characters. A site that offers English may then send English dates, which RSS Workshop recognizes, and some sites that refuse requests stating no language accept them. It is sent with the same requests as the feed's own User-Agent: its list page in Static HTTP mode and in Auto before any render, article pages fetched as plain HTML, previews, and the visual selector's Static HTML page. Pages that Chromium renders or FlareSolverr loads keep their browser's language preferences. There is no server-wide setting, so existing feeds still send none. Saving a value publishes nothing by itself, but a source that then answers in another language changes the feed's stories at the next refresh. On a site whose story links contain the language, such as/de/…and/en/…, or in a recipe without a link selector whose titles the source translates, every story appears once more under a new GUID, and the copies in the old language stay untilMAX_ITEMSretention removes them. Stored article bodies keep the language they were fetched in. Recipe exports carry it asrecipe.accept_language, the import review shows it, and Duplicate copies it. See browser rendering. - Choose for each feed when it turns Quiet. Mark as Quiet after in the feed's editor replaces the automatic threshold with 7, 30, 90 or 365 days without a new story, or Never, which also leaves the feed out of
rss_workshop_feeds_quiet. A chosen time ignores the 10-interval rule but always lasts at least one refresh interval and an hour, so a weekly feed set to 7 days is not marked Quiet before its next refresh has had the chance to find a story. It is stored in the recipe asquiet_daysand left out for Automatic, so existing recipes, exports and the example recipes are unchanged; Duplicate, export and import carry it, and the import review shows it. Any other value is refused when saving, previewing or importing. Saving a change publishes nothing, but like any edit it drops the source's conditional-request validators, so the next refresh fetches the whole page once. See quiet feeds.
Changes¶
- Measure Quiet from the last new story instead of the last output change; Upgrading from v1.2.0 says what that changes. A refresh records the time when it saves a story its feed did not have saved and that retention keeps: a changed story, a story that retention removes in the same refresh, and edits do not move it, while a story that retention or history pruning removed counts as new again if a later refresh saves it again. The card reads "No new story for N days". A feed that has never saved a story, for example because its filters exclude everything, counts from its last output change instead: the latest change to its title, address or refresh interval, or, without one, its first successful refresh.
GET /api/feedsreports the time aslast_newbesidelast_changed, and saves accept and ignore both. Metrics add the per-feedrss_workshop_feed_last_new_story_timestamp_seconds, within the existing 1,000-feed bound. Reader output never reads the time, so no published byte, GUID, date,Last-Modifiedor ETag changes. See quiet feeds for what counts as new: a story whose link changes at every visit always does, and so does a story saved again after retention removed it, which happens at every full refresh of a page that lists more stories without a date thanMAX_ITEMSkeeps.
Fixes¶
- Finish fetching full articles from sources that answer 304. A refresh fetches at most 10 article pages, and only for the stories its list page returned. A source answering
304 Not Modifiedreturns none, so a full-content feed listing more stories than that stopped at its first 10 bodies until the page changed. Now, while a refresh leaves stories without an article, because of that limit or its deadline, and leaves more of the listed stories with an article than before, the next refresh requests the list page withoutETagandLast-Modified. Conditional requests resume after a refresh that reaches every listed story still without an article, even if some of those articles fail, or after one that adds none. Stories whose articles failed are tried again when the list page changes or after a restart. See full article content. - Stop failing Chromium feeds that fall due together. After a restart, an outage or an import, every due Chromium feed started at once, waited for one of the
BROWSER_SLOTSinside its ownFETCH_TIMEOUT, and the later ones failed withcontext deadline exceededand backed off, while holding refresh slots that static feeds needed. Such feeds now wait for a free Chromium slot without failing, as FlareSolverr feeds have since v1.2.0, and other feeds are not held back; the upgrade note above says which feeds wait. A Chromium-mode feed gives its slot back once its list page is rendered, unless it renders its article pages, which it then renders one at a time in the same slot. See Chromium capacity.
v1.2.0 — 2026-11-07¶
Notifications to ntfy or a JSON webhook when a feed keeps failing or the database fails, a library you can search, filter and sort, which points out feeds that have gone quiet, a Duplicate action, and a User-Agent you can set for the server or for one feed. Story dates are read in the zone they name and with English month names, static mode reads pages in legacy encodings, FlareSolverr feeds that fall due together no longer fail, nor do refreshes cut short by stopping the app, and Pause and Resume no longer reset a feed. Sources see a new User-Agent, and some feeds change once.
Upgrading from v1.1.1¶
- The database is unchanged. This version keeps schema 5 and opens a v1.1.0 or v1.1.1 database as it is: SQLite saves no pre-upgrade copy and PostgreSQL logs no migration. To roll back, set
RSS_IMAGE=ghcr.io/ldogg123/rss-workshop:v1.1.1-browser, orghcr.io/ldogg123/rss-workshop:v1.1.1-staticwithcompose.static.yaml, or the image digest you saved; nothing needs restoring, but see the last item below for what v1.1.x does not keep. From v1.1.0, also follow Upgrading from v1.1.0, and from v1.0.0 Upgrading from v1.0.0 as well. - Update your checkout (
git pull) before recreating the container. Only the currentcompose.yamlpasses the newFETCH_USER_AGENTand the notification settingsNOTIFY_URL,NOTIFY_FORMAT,NOTIFY_TOKENandNOTIFY_AFTER_FAILURESinto the container; with an older one, Docker ignores them even when.envsets them. The Compose overrides andscripts/backup.pyare unchanged. - Notifications stay off until you set
NOTIFY_URL. The newNOTIFY_URL,NOTIFY_FORMAT,NOTIFY_TOKENandNOTIFY_AFTER_FAILURESare optional and default to off, the JSON format and 3 failures in a row, so upgrading sends nothing and adds no table. A feed that has already failedNOTIFY_AFTER_FAILUREStimes or more in a row when you turn them on is not reported as failing, since that alert goes out only as the count reaches the number, but its recovery is, so look for Needs attention in the library once they are on. Even whileNOTIFY_URLis blank, startup refuses aNOTIFY_FORMATother thanjsonorntfy, aNOTIFY_AFTER_FAILURESoutside 1–100, or aNOTIFY_TOKENwithout a URL. To turn them on with Compose, update your checkout as above, set them in.envand recreate the container withdocker compose up -d; a native executable needs them exported. TreatNOTIFY_URLandNOTIFY_TOKENas passwords, because a topic on a public ntfy server works as one and webhook URLs often embed a token. The app keeps both out of its logs, errors, metrics and dashboard, and they never reach the database or its backups, butdocker compose configprints them. See notifications. - Sources see a new User-Agent. Static requests, for list pages, article pages and the visual selector, now send
RSS-Workshop (+https://github.com/Ldogg123/rss-workshop)instead ofGoRSS/0.1 (+self-hosted feed builder). If a source starts refusing requests or serving different pages, setFETCH_USER_AGENT=GoRSS/0.1 (+self-hosted feed builder)in.envand recreate the container, or, for a native executable, which does not read.env, runexport FETCH_USER_AGENT='GoRSS/0.1 (+self-hosted feed builder)'and start it again. A single feed can instead set its own User-Agent. Pages that Chromium renders or FlareSolverr loads are unaffected, but the article pages of those feeds are fetched as static HTML unless the feed renders them, so they send the new name. A source that varies its pages by User-Agent may answer the first conditional request with a full page instead of 304; feeds change only if their stories did. See identifying requests. - Some feeds change once. A story still on its source's list page changes if its description already showed the story's image, which is no longer added above it a second time, or if its source is read in static mode, declares an encoding other than UTF-8, such as windows-1252 or Shift_JIS, and the story has non-ASCII text, which was saved as
�and is now correct. Those feeds change their bytes andLast-Modifiedonce, so readers download them once; older stored stories keep what they have. On those non-UTF-8 sites:- Stories whose identity has non-ASCII text get a new one once, and so appear in readers a second time: the title, for a recipe without a Link selector, or a link with unencoded non-ASCII characters, which is now encoded differently.
- A feed with Full article content keeps the article bodies it already fetched,
�included, because a body is fetched once and then kept. The same holds on such sites for feeds in Chromium or FlareSolverr mode, or Auto when it renders, that do not render their article pages, which is the default: those pages were fetched as plain HTML and read as UTF-8 too, though their list pages and story identities are unaffected. To fetch them again, save the feed once with its article selector cleared, then again with it restored; later refreshes fetch 10 per refresh for stories still on the list page, and stories no longer listed show their list-page description. See full article content. - Keyword filters with non-ASCII keywords start matching the text, so a feed can include a story it used to leave out, or the reverse. Saved stories stay unless you save the feed with the option to remove nonmatching stories.
- Stories first saved after upgrading may be dated differently. A date that names its zone, such as
Thu, 05 Nov 2026 10:00:00 EST, now uses that zone instead of UTC, and a date with an English month name, such asNov 6, 2026, gives the site's date instead of the time the story was first seen. A zone name that neither the recipe's time zone nor RFC 5322 defines, such asCETwith a blank time zone, or an hour written as a name that the recipe's time zone does not use, such as+03or+00, now leaves the date unrecognized, with adate not recognizedwarning and the first-seen time; v1.1.1 read all of these as UTC, which was right only for+00. Set Date settings → Time zone to the site's zone, such asEurope/Paris, to have it read, or, for an hour such as+00, a Go date layout that reads it as an offset, such asMon, 02 Jan 2006 15:04:05 -07. Stories already saved keep their dates and identities, so this changes no published feed. See time zones. - Pause and Resume keep a feed's state. They now change only whether the feed refreshes: a failing feed keeps its error, failure count and the source's conditional-request validators, so after Resume it still shows Needs attention until a refresh succeeds, and a renewed failure continues its backoff instead of restarting at 2 minutes. For the same reason, pausing a failing feed no longer silences an alert on it: the feed stays counted in
rss_workshop_feeds_failingand keeps itsrss_workshop_feed_failureswhile paused. To leave paused feeds out of a per-feed alert, addand on (id) rss_workshop_feed_enabled == 1; for the library total, alert oncount(rss_workshop_feed_failures > 0 and on (id) rss_workshop_feed_enabled == 1)instead. Saving the feed in the editor still clears its error, failure count and validators, as any edit does. See pausing and resuming. - Refresh releases a feed waiting after a failed database write. Once the database accepts writes again, Refresh, an editor save or Resume tries such a feed at once instead of leaving it to wait out its hold of up to about 17 hours. See waiting to retry after a failed save.
- FlareSolverr messages change. Feed errors, Diagnostics and log lines for FlareSolverr failures use new messages from the next failed refresh, so update any alert that matches the old
FlareSolverr request failed,FlareSolverr service returned HTTP n; check its service logs,FlareSolverr returned an invalid JSON response,could not read the FlareSolverr responseorFlareSolverr is unavailable, which now readsFlareSolverr is not configured on this server. On a FlareSolverr feed,context deadline exceededis replaced by messages that say what timed out: the wait for a free slot, the connection or FlareSolverr's reply. FlareSolverr troubleshooting lists the new messages. WithFLARESOLVERR_SLOTSabove 1, a feed that renders its article pages through FlareSolverr now fetches them one at a time, so a long backlog may take more refreshes to fill in. - Expect some Quiet badges at first. Feeds of sites that publish less often than every two weeks are marked Quiet once their output has been unchanged that long. Lengthen their refresh interval to raise the threshold.
- Going back to v1.1.x. v1.1.0 and v1.1.1 refuse a recipe file in which any feed has its own User-Agent (
json: unknown field "user_agent") and import none of its feeds, so clear the field before exporting recipes for an older server. After a rollback they ignore a stored one and send their own User-Agent for that feed, and saving the feed in their editor, or pausing or resuming it from its card, removes it. Feeds left alone keep it for the next upgrade. Rolling back also undoes this release's output fixes for stories still on their source's list page, from the first refresh that reads the page. A description that shows the story's image gets it a second time, and on non-UTF-8 sites read in static mode the text of a story whose identity this release kept shows�again. Those feeds change their bytes andLast-Modifiedonce more, and again after the next upgrade. Stories first saved after the rollback are dated by v1.1.x's rules.
New¶
- Search, filter and sort the feed library. A toolbar above the cards finds feeds by name or website, shows only the feeds with one status (Active, Quiet, Needs attention, Waiting to retry, Pending or Paused), and sorts them by name, next refresh, last success, last change or failures in a row. It works on the library the page already loads, so it adds no requests. The 10-second reload keeps the search, the selections and the keyboard focus, and the browser remembers the status and sort for the next visit. Cards also show when the feed's output last changed and how many refreshes in a row have failed. See the library dashboard.
- Point out feeds that have gone quiet. A refresh that finds nothing new succeeds, so a feed could stop delivering stories without ever showing a problem. A feed that keeps refreshing successfully but whose published output has not changed for 14 days, or 10 refresh intervals if that is longer, now shows a Quiet badge saying how long it has been unchanged. Any change to a story counts, so this is not the same as "no new stories", and a longer refresh interval raises the threshold for a site that publishes rarely.
GET /api/feedsreports each feed'slast_changedtime andquietflag, and saves accept and ignore both. Metrics addrss_workshop_feeds_quietand the per-feedrss_workshop_feed_last_changed_timestamp_seconds, within the existing 1,000-feed bound. See quiet feeds. - Duplicate a feed from its card. The editor opens a copy with every setting, its own story filters and the same library filters, linked rather than copied, named
Copy ofand the original name shortened to fit. Nothing is saved until you save it, and the copy starts paused, with its own RSS and Atom links and no saved stories. Before, the only way was to export and import a recipe, which also turned library filters into private copies. - Set a User-Agent for one feed under Request settings in its editor. It replaces
FETCH_USER_AGENTand the built-in name for that feed's static requests: its list page in Static HTTP mode and in Auto before any render, article pages fetched as plain HTML, previews, and the visual selector's Static HTML page. Surrounding spaces are trimmed, and a value longer than 256 characters or with anything but printable ASCII is refused when saving, previewing, loading the visual selector's page or importing. Blank uses the server's default, and recipes without one are stored and exported byte for byte as before. Changing it drops the source's conditional-request validators like any recipe edit, and changes no published feed. See browser rendering and recipe export and import. - Recognize English dates with a month name in element text and explicitly selected values, without a Go date layout:
5 November 2026,Nov 6, 2026,May. 5, 2026,Thursday, 5th November 2026 at 3:04 pmor5 Nov 2026 10:00 EST. The whole value must be the date, the year must have four digits, and a weekday must match the date. A date without a time is local midnight in the recipe's time zone. Automatically detecteddatetimeattributes still use only the standard formats, so they keep precedence over the element's text as before. See month names. - Get a message when something breaks, without Prometheus. Set
NOTIFY_URLto an ntfy topic withNOTIFY_FORMAT=ntfy, or to any webhook that accepts a JSONPOSTwith the defaultNOTIFY_FORMAT=json; an optionalNOTIFY_TOKENis sent as a bearer token. A feed is reported when its refreshes have failedNOTIFY_AFTER_FAILUREStimes in a row, and again when it recovers. Both follow the failure count stored with each feed, so a restart neither repeats an alert nor misses a recovery; a feed repaired in the editor, whose save resets that count, still reports its recovery unless the app has restarted since the alert. The database is reported when it refuses a refresh's results or the library cannot be read, at most once an hour while that lasts, and once more when the library can be read again. Events are collected for 60 seconds into one message that lists at most 20 of them, database events first, and counts the rest, so an outage that fails every feed at once sends one notification. The dashboard's status line says which format is on and, while one is, offers Send test notification. Messages carry feed titles, failure counts, the error a card shows with URLs removed,PUBLIC_BASE_URLas the link to the library and, in JSON, feed IDs, but never source URLs, reader links or story text. The address is trusted configuration likeFLARESOLVERR_URL, so it may be on your own network, where behind Gluetun it needs a firewall exception; environment proxies are ignored and a redirect counts as a failure./metricsaddsrss_workshop_notifications_totalandrss_workshop_notification_events_dropped_total. See notifications.
Changes¶
- Name the project in the static fetcher's User-Agent:
RSS-Workshop (+https://github.com/Ldogg123/rss-workshop), replacing the prototype'sGoRSS/0.1 (+self-hosted feed builder). It carries no version, so later upgrades never change what sources see, and it does not reveal which release an instance runs. The new optionalFETCH_USER_AGENTreplaces it for list pages, article pages and the visual selector's static snapshot; startup refuses a value longer than 256 characters or containing anything but printable ASCII, such as a line break, and the startup log reports only whether one is set. Chromium and FlareSolverr keep their own User-Agents for the pages they load. See identifying requests. make release-test, and somake checkand CI, now fails when the dependency table ordocs/licenses/falls out of step with the Go modules the app links: a linked module without a row, a row pinning a version the module graph no longer selects, a missing, misnamed or leftover notice, or a copied notice that differs from its upstream file. Release source collection takes each Debian source version still listed by the current suites from Debian's regular archive, checked against the suite'sSourcesindex, and falls back to Snapshot for older versions and files the archive cannot serve, so a Snapshot outage no longer blocks a release whose packages are current.
Fixes¶
- Pause and Resume on a feed card no longer send the card's whole copy of the feed. A card drawn before an edit in another tab could undo that edit; if the edit corrected an article selector, the article bodies fetched with the corrected selector were deleted, and a reverted title or interval rewrote the published feed. Every pause and resume also threw away a refresh in progress. They now use their own request,
POST /api/feeds/{id}/enabled, which changes nothing readers see. Older clients and scripts that pause by saving the feed, including ones that send back a feed object fromGET /api/feeds, keep working. - An editor left open no longer re-enables a feed paused from its card. A save keeps the feed's current setting unless Refresh automatically was changed.
- Refresh, saving a feed in the editor, and resuming it now retry a feed held after the database refused a refresh, for example on a full disk. Such a feed used to wait out its hold, up to about 17 hours, while Refresh reported it as queued and the dashboard showed it as due and healthy. A retry that fails again waits twice as long as the last one. The card now says Waiting to retry, feed listings report
"held": true, and the newrss_workshop_feeds_heldmetric counts these feeds;rss_workshop_feeds_duekeeps its meaning and still includes them. - A refresh thrown away because its feed was edited while it ran is now logged as
refresh discardedat info level, instead ofrefresh finishedwith an item count orrefresh failedwith a failure count, although nothing from it was stored. A feed deleted during its refresh is logged the same way and is no longer held; before, it was logged at error level as if the database had refused the write. - A refresh cut short by stopping or restarting the app is no longer stored as a failure. A restart that cut a refresh short before its stories were extracted gave a healthy feed an error such as
context canceledon its card, a failure in a row and a backoff. Such a refresh is now discarded, logged asrefresh discardedwithreason="server stopping", and leaves no run in Diagnostics, so the feed is still due and refreshes when the app starts again. A refresh that runs out of its own time still counts as a failure, and one that had already succeeded is still stored. - Refresh answers 500 when the database cannot be read, and Reset feed links when it cannot be written, instead of 404 as if the feed did not exist.
- Read the time zone a date names. An RFC 1123 date such as
Thu, 05 Nov 2026 10:00:00 ESTwas stored as 10:00 UTC, five hours early, because a zone name the recipe's time zone does not define was given a zero offset: with a blank time zone every US zone name was hours off, any made-up name was accepted as UTC, andGMT+3was read as UTC. A zone name now takes the meaning the recipe's time zone gives it, soCSTstays China Standard Time underAsia/Shanghai, and otherwise the meaning RFC 5322 gives it (UT,GMT,EST,EDT,CST,CDT,MST,MDT,PST,PDT).GMT+3is read as +03:00 andGMT+0as UTC, and any other name leaves the date unrecognized rather than guessing. The same rules apply to a Go date layout containingMST. RFC 1123 dates may also have a one-digit day and leave out the seconds. See time zones. - Decode pages in static mode the way browsers do. A site served in windows-1252, ISO-8859-x, Shift_JIS, EUC-KR, windows-1251, UTF-16 or another encoding browsers support was read as UTF-8, so static mode, and Auto when it did not render, published its accented and CJK characters as
�, while Chromium mode showed its list pages correctly. The encoding now comes from a byte order mark, theContent-Typecharset or a<meta>charset in the first 1,024 bytes, for list pages, article pages and the visual selector's static snapshot alike. A page that declares nothing or an encoding browsers do not support is read as UTF-8 as before, and so is a page that declares a legacy encoding but whose text is mostly valid UTF-8, the usual sign of a site that moved to UTF-8 and kept its old declaration. The 4 MiB page limit now also applies after decoding, as it already did in Chromium mode, so a page close to that size in an encoding whose characters take more bytes in UTF-8, such as Shift_JIS, can now be refused. See fetch modes. - Stop showing a story's image twice when its list-page description already shows it, as happens when the Description selector covers the whole card. The image is now left out when the description has an image with exactly that address; a link to the image, as lightboxes use, or a different size of it still gets the image shown above. RSS
media:contentand the Atom enclosure are unchanged. - Stop failing FlareSolverr feeds that fall due together. The scheduler started every due feed at once, up to
STATIC_WORKERS, against FlareSolverr's single default slot, and each refresh waited for that slot inside its own deadline, so after a restart, an outage or an import the later feeds failed withcontext deadline exceededand backed off. RSS Workshop now starts only as many FlareSolverr refreshes as there are free slots, counting slots still held after an interrupted request. The rest stay due and start oldest first as slots free up, with no failure recorded, and feeds in other fetch modes are not held back. A refresh hands its slot on once its list page is solved, unless it renders its article pages through FlareSolverr, which it then fetches one by one. A FlareSolverr preview or visual-selector page load that finds every slot in use answersFlareSolverr is busyat once instead of waiting out its deadline. It has no claim on the next free slot: while FlareSolverr feeds are due, as after a restart, an outage or an import, each freed slot goes to them first, so previews and page loads can stay busy until those feeds have refreshed. See FlareSolverr capacity. - Name what failed when FlareSolverr cannot be reached. Every connection problem used to read
FlareSolverr request failed; check the service address, connection, and timeout, and any other service's reply onlyFlareSolverr service returned HTTP n. Previews, the visual selector, feed cards, Diagnostics and the log now name the step: a DNS lookup, a refused or timed-out connection, no network route, a connection that failed before the request was sent (usually TLS), an address that is not the FlareSolverr/v1API, a reply from something other than FlareSolverr, a dropped connection, no reply before the deadline, or a wait for a free slot. The messages are fixed text and never include the service address, the source URL or the reply. A request that never connected now frees its slot at once instead of holding it for the whole solver timeout. FlareSolverr troubleshooting says what to check for each message. - Point the editor's "FlareSolverr is not configured" hints to the setup guide. The advice now holds for Docker Compose, where the container must be recreated with
docker compose up -dbecausedocker compose restartkeeps its old environment, for native executables, which do not read.env, and for installs sharing Gluetun's network, where127.0.0.1is the right address. - Stop a feed refreshing twice in a row when its refresh ended while the scheduler was reading the feed list. That list still showed the feed due, so it started again at once, which with FlareSolverr spent a solve ahead of feeds waiting their turn.
v1.1.1 — 2026-11-05¶
Security updates for the Go runtime, its modules and the browser image, a WebRTC leak closed in browser mode, a selector failure that could stop the server, and more story images found. PostgreSQL users should check DATABASE_URL before upgrading.
Upgrading from v1.1.0¶
- PostgreSQL: check
DATABASE_URLfirst. The newer driver reads it the way PostgreSQL's own client library does, so the first@ends the credentials. Percent-encode an@in the user name or password as%40, or startup stops withpercent-encode @ in the user name or password as %40. Inside a query value, encode=,&,%and spaces, as inoptions=-c%20search_path%3Drss, and write every parameter askey=valuewith no empty ones such as&&, or startup stops withinvalid PostgreSQL connection configuration. A+in a query value is now a literal plus rather than a space, a parameter given twice takes its last value, and in a URL with several hosts each host needs its own port. v1.1.0 reads an encoded URL the same way, so change it before upgrading. URLs written as PostgreSQL setup describes, including its generated hexadecimal password, need no change. - The database is unchanged. This version keeps schema 5 and opens a v1.1.0 database as it is: SQLite saves no pre-upgrade copy and PostgreSQL logs no migration. To roll back, set
RSS_IMAGE=ghcr.io/ldogg123/rss-workshop:v1.1.0-browser, orghcr.io/ldogg123/rss-workshop:v1.1.0-staticwithcompose.static.yaml, or the image digest you saved; nothing needs restoring. From v1.0.0, also follow Upgrading from v1.0.0. - No configuration changes. The Compose files,
.envsettings andscripts/backup.pyare as v1.1.0 shipped them, so a v1.1.0 checkout runs the new images. Update it for the corrected guides or to build from source. - Some feeds change once. A story still on its source's list page changes if it gains a lazy-loaded image or a corrected
srcsetimage, and a full article changes if it showed its image twice. Those feeds' bytes change once, so readers download them once. Story identities and publication dates do not change, so no reader sees a story twice.
Security¶
- Update Go to 1.27.3 and the Go modules the app uses, fixing 15 reachable vulnerabilities reported by
govulncheck: in the standard library's HTTP/1, HTTP/2, TLS, certificate, MIME andhtml/templatecode, and in HTML parsing and rendering ingolang.org/x/net. - Update the browser image to Chromium 156 and a current Debian base. Debian had removed the previously pinned Chromium, so that image could no longer be built from source.
- Stop pages that Chromium renders, in browser mode, Auto's fallback or rendered articles, from sending WebRTC UDP past the proxy. The switch meant to disable it is not in Chromium's regular build, which ignores switches it does not know, so a rendered page could send STUN packets carrying text of its choosing to any routable address and port, including ones the outbound policy rejects. The switch Chromium reads is now set as well.
- Correct the browser guide, which said WebSocket URLs were blocked through DevTools. They never were: a rendered page can open a WebSocket, and it is confined by the proxy's rule of validated destinations on port 443 and its limits, which held throughout. The patterns that had no effect are removed.
Fixes¶
- A page that the XPath library cannot evaluate no longer stops the server. On the bundled antchfx/xpath, comparing a non-number with a number, such as
//article[@data-score > 1]on a page withdata-score="n/a", or asubstring()range past the end of a short value, panics. During a refresh or an article fetch, including the editor's article preview, that panic stopped the whole process and every other feed with it. Such a refresh now fails like any other: the feed keeps its saved stories, backs off, and showsselector evaluation failedwith the field's name. A failed article keeps its list-page description. A list preview reports the same error instead of dropping the connection. The log records the field and a short stack, but not the page value or the selector, since either can hold a URL. In v1.1.0 the crash could write that value to the container log, so check older logs before sharing them. See the visual selector limits for selectors that avoid the failure. - Find a story's lazy-loaded image when a lazy-loading script keeps its real address in an attribute of its own. When
srcholds only a placeholder, such as an inlinedata:image, and the usual attributes give no address, detection now tries a fixed list of attributes used by common lazy-loading scripts and CDNs, such asdata-originalanddata-webp, listed in the visual selector guide. Images that already resolve keep their address. A feed that gains an image changes its published bytes once, so subscribers refetch it. - Read
srcsetthe way browsers do, except that addresses joined by a bare comma still separate where an address visibly starts or an image file ends at the comma. Commas inside a candidate, as in a CDN address containingw_400,h_300or an inlinedata:image, were treated as separators and could publish a broken address; stories still on the source's list page get the correct image at the next refresh, and older stored stories keep the address they have. Asrcsetcandidate too long to publish now counts as unusable, so it no longer fails the page and is left out of descriptions and articles. - Stop full-article feeds from showing a story's image twice when its address contains
&or', as CDN addresses with a query such as?w=640&q=75do. The check for an image the article already shows compared the address with the article's markup, where those characters are escaped, so it never matched; the image detection above made this happen to some lazy-loaded thumbnails too. Affected feeds change their bytes and ETag at the first request after upgrading. TheirLast-Modifiedand Atomupdatedtimes stay as they were, so a reader that sends onlyIf-Modified-Sincekeeps its copy until the feed next changes.
v1.1.0 — 2026-09-16¶
Reusable filters, safer upgrades, and feeds that stop changing when nothing in them has. See upgrades before installing over an existing deployment.
Upgrading from v1.0.0¶
- Update your checkout first (
git pull). The currentcompose.yamlpasses the newUPGRADE_BACKUPsetting into the container, and the currentscripts/backup.pyreads schema 5 and leaves the automatic copies out of its backups; the v1.0.0 versions do neither. - The database moves to schema 5, in one transaction, the first time this version starts. v1.0.0 cannot open the result, so rolling back means restoring a copy taken before the upgrade.
- SQLite takes that copy for you. Before upgrading, the app saves a verified copy to
backups/pre-upgrade-schema-4-<time>in the data directory and names it in the log. It needs free space about the size of the database, or startup stops before upgrading; the copies are never deleted automatically. To roll back, stop the app,sudo python3 scripts/backup.py restorethe copy into a new directory, pointRSS_DATA_DIRat it and pinRSS_IMAGEto v1.0.0. The copy sits on the same disk, so keep an off-host backup too. See automatic copy. - PostgreSQL gets no automatic copy. Take a
pg_dumpbefore upgrading; the app logs a warning when it migrates. - RSS readers refetch once. The RSS
generatorno longer carries a version, so each RSS feed's bytes change once with this upgrade and not again because of later version bumps. Atom feeds are byte-for-byte unchanged by the upgrade.
Filter library¶
- Add a Filter library: save story filters once and select them in any feed. Feeds use library filters by reference, so editing one updates every feed using it, with the same optional cleanup of saved stories as a feed edit. A feed's own rules and its library filters combine, and the existing filter limits apply to the combination. Recipe exports copy the combined rules so files stay importable anywhere. This adds database schema 5; take a backup before upgrading, because v1.0.0 cannot open the upgraded database.
Upgrades you can undo¶
- Save a verified copy of an SQLite database in
backups/inside the data directory before upgrading its schema, because an older release cannot open the upgraded database. The copy uses the backup utility's format, soscripts/backup.py verifyandrestoreaccept it. If it cannot be saved, the app stops before upgrading the database;UPGRADE_BACKUP=falseskips the copy. A restart after a failed upgrade reuses an identical copy instead of saving another. PostgreSQL upgrades log a warning instead, since the app cannot runpg_dump. scripts/backup.py backupnow keeps only the database and its write-ahead log from the stopped container, instead of copying all of/datainto temporary space.
Fewer full downloads for readers¶
- Stop rewriting every feed on every refresh. Published dates and
Last-Modifiedcame from the time of the last refresh, so a refresh that changed nothing, even one where the source answered 304, gave each feed new bytes and a new ETag, and a reader polling at the advertisedttlalmost never received a 304. Feeds and stories now record when their published output last changed, which moves only when a story, the feed's title, URL or interval, or its saved history actually changes, including edits to a paused feed. Upgrading keeps every published date as it was. The RSSgeneratorno longer includes the version, so RSS subscribers download each feed once after this upgrade and not again on later ones; Atom subscribers are unaffected.
Fixes¶
- Fix SQLite foreign keys switching off after an interrupted read. The settings were applied once, and a reader disconnecting mid-response could leave the app on a replacement connection without them; deleting a feed then left its stories, runs and filter links behind. Settings now apply to every connection, and startup removes rows left by feeds that were already deleted, which otherwise make the backup utility and the pre-upgrade copy refuse the database.
v1.0.0 — 2026-09-12¶
First stable release. RSS Workshop turns pages that publish no feed into RSS and Atom feeds you keep, and 1.0 is the point at which its upgrade path, configuration surface and reader URLs become commitments rather than implementation details. See upgrades before installing over an existing deployment.
Upgrading from v0.2.0¶
- Take a backup first. Starting this version migrates the database to schema 4 in a single transaction. Every released schema upgrades directly, but an older release cannot open a newer database, so rolling back needs a backup taken before the upgrade. See backup and restore.
- Readers refetch once. Published feeds carry more than they did, so every feed's bytes change once and subscribed readers fetch a full copy on their next poll. Stories keep their identities and publication dates, so nobody sees a duplicate.
- Container logs now rotate, at three 10 MiB files per service.
docker compose logsreaches back only as far as the retained files.
Feeds readers actually want¶
- Full article content. Follow each story's own link, extract the article body, and publish that instead of the list page's one-line teaser. Off by default and configured per feed. Article pages are fetched with the same guarded fetcher as list pages, at most 10 per refresh so a long feed fills in over several cycles, and an article that cannot be fetched keeps its teaser rather than dropping the story or failing the refresh.
- Better published feeds. RSS keeps the article in
descriptionand repeats it incontent:encoded; Atom carries the list-page description assummaryand the article ascontent. The extracted image is published asmedia:contentand as an Atom enclosure, where readers look for a thumbnail, and is no longer repeated when the article body already contains it. The RSS channel gainsatom:link rel="self",ttl,lastBuildDateandgenerator. - Conditional requests. Reader responses honour
If-Modified-Sincealongside the existing ETag, so a reader polling from several devices costs validators rather than full copies. - OPML export. Download a subscription list of every feed and import it into your reader in one step. It contains every private reader link, so it requires an admin session and is never cached.
Knowing when something breaks¶
- Log levels.
LOG_LEVELselectsdebug,info,warnorerror, andLOG_FORMATswitches to JSON for a log collector. The startup line summarizes the running deployment, failed refreshes report their reason and feed, rejected sign-ins are reported with their remote address, and shutdown is logged. - Prometheus metrics. Setting
METRICS_TOKENenables/metrics, scraped with that token as a bearer credential; blank leaves the endpoint returning 404. Per-feed series carry item counts, consecutive failures and last-success timestamps, so an alert can name the feed that broke. - A failed database write no longer hammers the source. Such a refresh rolls back the feed's schedule along with everything else, so the source was refetched on every scheduler tick for as long as writing failed, while the log reported success. The feed now backs off, and the failure reports its reason.
- Retention is visible.
MAX_ITEMSapplies to stories already saved, so lowering it permanently deletes the excess at each feed's next refresh. That now appears in the log and is documented as destructive.
Running it¶
- Reverse proxy support.
compose.proxy.yamland a guide for a proxy running in Docker, which cannot reach the default loopback publication. - Container log rotation, configurable through
LOG_MAX_SIZEandLOG_MAX_FILES. - Stable image aliases.
latestandlatest-browserinclude Chromium;latest-staticselects the lightweight runtime. Compose follows these aliases, with version and digest pins still available. - Direct upgrades from every released schema, with frozen per-backend fixtures and tests comparing all saved feed, item and run data across upgrade and reopening. Backups support schemas 1 through 4.
Editor and examples¶
- Full article content is inspectable and repairable. Previews show the fetched body, so a selector matching the wrong block is visible before saving, and changing or clearing the selector discards the stored bodies so later refreshes fetch them again.
- New example recipes. The previous examples targeted five real news sites that all publish their own feeds, extracted only a title and link, and two relied on generated class names that change whenever those sites deploy. They are replaced by a demo site included in the repository, with recipes covering every field, CSS and XPath, and filtering with full article content. A test imports each example and extracts from that site.
- Reorganized documentation. The README follows install, first feed, and diagnosing a broken one, with installation variants collected below;
.env.exampleis grouped by purpose. Screenshots are refreshed and now include full article content and per-feed diagnostics.
Internal¶
- Security headers applied to every response are pinned by a test; the content policy is the second layer behind sanitization for extracted markup and previously had no coverage of its own.
- A refresh no longer loads every stored article body to decide which article pages to fetch.
v0.2.0 — 2026-09-08¶
- Add optional title, description, and link filters with nested All/Any include/exclude rules, case-insensitive literal phrases, and bulk lists of up to 500 keywords. Previews show included/filtered counts and excluded examples; intentionally empty filtered results succeed without browser fallback.
- Make applying filters to saved history an explicit editor option. Preserve existing stories by default and keep filtering settings in recipe exports/imports.
- Advance both databases to schema 3 so older app versions cannot silently ignore stored filters. Preserve diagnostics and support backups of schemas 1, 2, and 3.
- Add screenshots of the dashboard, visual editor, and filtering controls to the README.
- Run CI once per pull-request update, skip documentation-only changes, and cancel superseded automatic runs while keeping release validation separate.
v0.1.2 — 2026-09-08¶
- Make Compose use published images by default, including the browser and static runtimes. Move local builds into explicit development overrides and simplify installation commands.
- Show match counts and per-item rejection reasons when a feed preview fails, so missing titles and links can be diagnosed in the editor.
- Add per-feed diagnostic history and detailed preview traces with fetch mode, HTTP status, timing, match counts, and rejection reasons. Include expected field values and short samples of unexpected text, including invalid dates and temporarily missing images.
- Upgrade SQLite and PostgreSQL databases transactionally from schema 1 to 2 to retain diagnostics with the last 50 runs per feed. Keep legacy run summaries and support backups of both schemas; downgrading requires a pre-upgrade backup.
v0.1.1 — 2026-09-08¶
- Remove the admin password length policy. Short passwords and long or Unicode passphrases work through
ADMIN_PASSWORD; existing externally generated bcrypt hashes remain supported. - Default the documented Docker installation to published images, and provide native Linux executable downloads with checksums and setup instructions.
v0.1.0 — 2026-09-07¶
- Self-hosted RSS and Atom feeds with a single-admin web interface, scheduled refreshes, SQLite persistence, stable item identities/dates, and revocable reader links.
- Optional PostgreSQL storage through
DATABASE_URL, existing-server and dedicated Compose setups, and PostgreSQL backup/restore guidance; SQLite remains the default. - Visual card and field selection with live CSS/XPath tuning, field tips, and light/dark themes.
- Automatic relative publication dates, exact timestamp preference, and estimated-date previews.
- Static HTTP, sandboxed Chromium/Auto, and optional external FlareSolverr fetch modes.
- Recipe export/import as paused copies and verified database backup/restore tooling.
- Lightweight static and browser images, version metadata, CI, and a manual GHCR release workflow.
- Prebuilt native Linux AMD64 and ARM64 executable archives, with license notices, SHA-256 checksums, and a separate manual release workflow.
- Optional Compose networking through an existing Gluetun container, with port-conflict, database, and remote-solver guidance.
- Configurable host directories for SQLite and PostgreSQL persistence, with verified SQLite directory restore and migration from existing Docker volumes.
- Browser-enabled default Compose installation, with an explicit lightweight static override and local-folder quickstart examples for SQLite and PostgreSQL.
See release preparation for validation, matching source archives, and publication steps.