NewsBlur's self-hosting story starts at make and a self-signed certificate
NewsBlur is a personal news reader that brings people together to talk about the world. A new sound of an old instrument.
At a glance
- What is it?
- A Django and Backbone news reader you can run with Docker and Docker Compose, over four datastores, with a worktree mode that gives each feature its own ports. The command surface is deliberately small, and the first thing you see in a browser is a certificate warning you are told to bypass by typing a word.
- Who is it for?
- NewsBlur fits a reader who wants their subscription data under their own control, is comfortable running four datastores in containers, and wants the training feature that learns from what you hide. It does not fit a low-maintenance deployment, since the stack is large.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 7, 2026, and from our analysis. They are not legal advice.
Star history
- samuelclay/NewsBlur7,682 ★ · +55
| Repository | 2026-09-22 | 2026-11-07 |
|---|---|---|
| samuelclay/NewsBlur | 7.6k | 7.7k |
55 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
make is the interface, and the certificate warning is expected
Self-hosting takes two prerequisites and three commands. The prerequisites are Docker and Docker Compose, and then:
git clone https://github.com/samuelclay/NewsBlur.git
cd NewsBlur
makeAfter that you visit the local address, and the readme tells you to type a specific word to get past the self-signed certificate warning. That instruction is the honest summary of the developer experience: you are running a local HTTPS endpoint with a certificate nothing trusts, and the tool tells you how to dismiss it rather than pretending it is not there.
The command surface is deliberately short. make starts or updates the instance and applies migrations, and it is the command to run after every git pull. make log shows web and node logs, make logall shows all container logs, make shell gives a Django shell with models auto-imported, make bash drops into the web container, make test runs the tests, make lint formats with isort, black and flake8, and make down stops the containers.
Four datastores, and the one you can leave out
The technology section lists what each store is for.
PostgreSQL holds relational data: feeds, subscriptions and accounts. MongoDB holds stories and read states, which is the pair that decides whether a story is unread. Redis does story assembly and caching. Celery handles background tasks, specifically feed fetching. Node.js services exist for text extraction and image processing, which is the part that turns a truncated feed entry into a readable story.
Elasticsearch is marked optional, and it is the one for search. Full text search is listed as a feature, so the honest reading is that search needs it and everything else does not.
The compose file confirms the shape: the web service depends on Mongo, Postgres, Redis and Elasticsearch together, while the node service depends on all but Elasticsearch, since text extraction does not need an index.
Worktrees get their own ports and share the databases
The worktree section exists for people working on more than one feature at once, and the readme says it is ideal when working with AI coding assistants. The flow is a normal git worktree plus a make target:
git worktree add .worktree/feature-name
cd .worktree/feature-name
make worktreeEach worktree automatically gets unique ports derived from its directory name, so the main repository is on the default local address and a worktree is on a local address with a different port. Running make worktree again prints the URLs, make worktree-log follows that worktree's logs, and make worktree-close stops the containers and removes the worktree if there are no uncommitted changes.
The design decision worth noting is that all worktrees share the same database services. So a second worktree is a second application process against the same data, not a second copy of the data, which is what makes testing parallel features cheap.
Retention defaults differ between free and premium
Story retention is a pair of settings rather than one, and the defaults are worth knowing because they are not equal. DAYS_OF_UNREAD is the retention window in days for premium users and defaults to 30. DAYS_OF_UNREAD_FREE is the equivalent for free users and defaults to 14.
So a self-hosted instance that nobody reconfigures will quietly keep half as much history for accounts that are not premium, which is a detail that shows up as stories disappearing rather than as an error.
The rest of the settings skew toward running a private instance rather than a public service. AUTO_PREMIUM gives new users premium features and defaults to true, AUTO_ENABLE_NEW_USERS auto-activates new accounts and also defaults to true, and ENFORCE_SIGNUP_CAPTCHA defaults to false. NEWSBLUR_URL sets your domain and is also used for the Archive browser extension OAuth flow. HOMEPAGE_USERNAME decides which user's blurblog appears to unauthenticated visitors and defaults to popular.
The uncommon settings are the ones the hosted service uses: email delivery, Stripe and PayPal credentials, S3 buckets for backups, icons and avatars, and social API keys.
The MCP server needs a premium subscription
NewsBlur ships a Model Context Protocol server, and the requirement is stated in the same sentence as the feature: a premium subscription is required.
That is a sharper statement than most integrations make, because it tells you the agent-facing surface is tied to the paid tier rather than to self-hosting. On a self-hosted instance, AUTO_PREMIUM gives new users premium features by default.
The clients named are Claude Desktop, Claude Code, Cursor, and any MCP-compatible client, and the Claude Code connection is an add over HTTP transport pointing at the hosted endpoint. There is a newsblur_mcp directory in the repository alongside an .mcp.json file at the root, so the server is implemented in this repository rather than being a wrapper around something else.
Releases are tagged per client, not per server
The release history is not a single version line. The three most recent tags are NewsBlur CLI v0.2.2 from August 2026, NewsBlur CLI v0.1.0 from March 2026, and Android v13.12.3 from the same month.
So the server has no version of its own in these tags, the CLI is still pre-1.0, and the Android client is on its own 13.x numbering. The mobile numbering is probably historical, but the effect is the same: there is no single number to quote when someone asks which version of NewsBlur you are running.
The last push to main is dated 2 November 2026, so all three of those lines are behind the tip of the branch. For a self-hosted instance the repository root is the artefact you deploy, which makes the compose file and the Makefile the parts that actually need reading.
The dependency pins are older than the Python version implies
The readme describes NewsBlur as a Django application requiring Python 3.7 or newer. The root requirements.txt only points to config/requirements.txt, so that file is where the actual pins live.
The Makefile colourises its own output
One detail in the Makefile is worth pointing out because it explains a lot about how this project is worked on. There is a shell function named log whose comment says it matches NewsBlur's logging system in utils/log.py, and it expands short markers into ANSI escape codes.
Each marker maps to a colour: FR for red, FG for green, FY for yellow, FB for blue, and the remaining foreground colours, a set of background variants, plus style markers: ~SB for bold, ~SN for normal intensity, ~SK for blink, ~SU for underline and ~ST to reset. Every substitution runs through sed at make invocation time.
So build and test output is coloured to match what the application prints. It is a small thing, but it is the kind of detail that only exists in a repository where the person running make is the person who wrote the log format, which is also consistent with the worktree mode and the AI assistant integration being first-class.
Editorial conclusion
NewsBlur fits a reader who wants their subscription data under their own control, is comfortable running four datastores in containers, and wants the training feature that learns from what you hide. It does not fit a low-maintenance deployment, since the stack is large. Before deploying, read the retention settings because free and premium accounts default to different windows, decide whether you need Elasticsearch for search, and plan for the worktree mode if you will work on more than one feature at a time.
Frequently asked questions
How do I use NewsBlur?
To self-host, install Docker and Docker Compose, clone the repository, and run make, then visit the local address and type the bypass word the readme gives for the self-signed certificate. From there, add feeds, hide the stories you do not want so training learns, and share stories on a blurblog if you want to.
Is NewsBlur free?
The software is MIT licensed and free to self-host. The hosted service is free up to 64 sites with premium plans available, and the MCP server that lets AI agents reach your feeds, stories and classifiers requires a premium subscription; on a self-hosted instance AUTO_PREMIUM gives new users premium features by default.
What are the alternatives to NewsBlur?
The readme's feature list highlights showing the original site rather than a stripped feed, training that hides and highlights stories based on what you dislike, full text search across subscriptions, story tagging, saved searches as their own feeds, change tracking on stories, and email newsletters read in the reader.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/samuelclay-newsblur)Star history chart for your README
[](https://hysenlabs.com/projects/samuelclay-newsblur)Was this useful?