HermanMartinus/bearblog: the Django source behind bearblog.dev, and why it is not a self-hostable generator

The problem Bear Blog solves, and who the repository is actually for

Most blogging stacks ask you to make decisions before you can publish: which static site generator, which theme, which deploy target, which analytics snippet. Bear Blog takes the opposite position. The README describes it as "Free, no-nonsense, super-fast blogging" with "No javascript, no stylesheets, no trackers. Just your words." Post content is written in markdown, and the platform handles rendering, hosting and feeds.

That framing tells you who the repository is for. It is not a library you add to a project, and it is not a theme you drop into an existing site. It is the application code behind a single hosted service, bearblog.dev. The README compares the product to Substack rather than to Hugo, and the distinction matters: a Substack-style product owns accounts, publishing and delivery on shared infrastructure. If you want to run your own instance, this is the wrong repository, and the README says so directly rather than leaving it implied.

The useful audiences are narrower. One is an engineer curious about how a minimal publishing platform is put together in Django, where the markdown pipeline lives, how static assets are served without a CDN-heavy setup. Another is a writer or technical evaluator deciding whether bearblog.dev is the right home for a blog, who wants to know what the platform does and does not promise before signing up.

What the repository layout reveals about the architecture

The top level is a conventional Django project: manage.py, a conf/ directory for settings, blogs/ for the application code, templates/, static/, and a Procfile for process declaration. requirements.txt pins the stack. Django 6.0.8 is the framework. mistune 3.3.3 handles markdown, with Pygments 2.20.0 available for code highlighting and latex2mathml 3.77.0 for math rendering. whitenoise 6.12.0 serves static files from the application process instead of a separate asset server. gunicorn 23.0.0 is the WSGI server, and judoscale 1.7.5 provides autoscaling hooks.

The presence of boto3 1.43.86 and Pillow 12.3.0 with pillow-heif 1.5.0 points at object storage for media and image handling that accepts HEIC input. geoip2 5.3.0, django-ip 1.0.2 and httpagentparser 1.9.2 suggest request-level analytics derived from IP and user agent rather than a client-side tracker, which is consistent with the no-JavaScript claim. feedgen 1.0.0 covers RSS generation. sentry-sdk 2.19.0 is error reporting.

Two details are worth pausing on. First, there is no JavaScript build tooling anywhere in the listed dependencies, no bundler, no frontend framework. Second, the Makefile targets are operational rather than developer-facing: migrate, makemigrations, shell, logs, 404, router. The shell, logs, 404 and router targets all invoke heroku run or heroku logs against an app named bear-blog. That is a deployment-specific Makefile, not a general-purpose one, and it is the clearest signal in the repository that this code is maintained for one running service.

Running the Django app locally: install and first request

The repository does not ship a self-hosting guide, and the README states that individual self-hosting is not possible. What it does contain is enough to bring the Django application up on a development machine, which is the realistic first use of this codebase: inspecting or experimenting with it locally.

Dependencies are pinned in requirements.txt, so install them into a virtual environment first. The .python-version file in the repository root indicates the interpreter version the project targets.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

After that, the Makefile provides the two commands you need. The dev target prints the address and starts the Django development server on port 1414 bound to all interfaces.

make migrate
make dev

The first command applies database migrations. The second prints localhost:1414 and runs the server, so you should be able to open that address in a browser and see the application respond. The Makefile also defines a caddy target that runs caddy run --config Caddyfile.dev, which is how static and media files are fronted during local development, since whitenoise is configured for the production process rather than the dev server.

If you are evaluating the platform rather than the code, the README points elsewhere: the full documentation lives at docs.bearblog.dev, and feature requests and bug reports go to Herman through the contact page linked from the README. There is no package to install and no CLI to run against bearblog.dev.

Self-hosting is out of scope, and the README is unusually direct about it

The most important limitation is stated in the README itself, under a heading that asks whether Bear Blog can be self-hosted. The answer is no. Bear was "built as a platform and not as an individual blog generator," and the README adds that it is "more like Substack than Hugo."

That is a real constraint, not a documentation gap. A Django application with accounts, object storage, GeoIP lookups and autoscaling hooks is not a single-user blog you can drop onto a small VPS without work. The Makefile assumes a Heroku app named bear-blog. The settings live in conf/ without a published configuration reference. There are no release artifacts in the repository, and no tagged releases were retrieved, so there is no versioned distribution to install. Contributions are closed as well: the README states that Bear is not currently accepting contributions and points to CONTRIBUTIONS.md for the reasoning.

The fallback the README offers is worth quoting in substance: if you want something that looks like Bear, there are Hugo themes that reuse Bear's stylesheet, findable on the Hugo theme repository. That is a different product with a different model. You get the visual result and you own the hosting, the build and the feeds yourself.

The alternatives people weigh against it, and where the approaches diverge

The comparison that matters most is the one the README makes: Substack. Both are hosted platforms where you write and the service publishes. The difference is in what the platform optimizes for. Bear's stated position is no JavaScript, no stylesheets you manage, no trackers, markdown only, and a fast page. Substack is built around newsletters, subscriptions and audience growth tooling, which is a different product with a different set of defaults.

Against WordPress, the divergence is architectural. WordPress is software you install and host, with a plugin ecosystem and a database you administer. Bear is a service you sign up for. If your requirement is control over the runtime, WordPress answers it and Bear does not. If your requirement is to never think about the runtime, the trade runs the other way.

Against static site generators such as Hugo, the split is about who owns the build. Hugo produces files you deploy anywhere, and the README's own suggestion of Hugo themes that reuse Bear's stylesheet is an admission that the visual layer can be reproduced outside the platform. What cannot be reproduced that way is the hosted account, the editor and the delivery. Choosing Hugo means owning a repository, a build step and a host. Choosing Bear means giving those up in exchange for publishing immediately.

Maintenance, licensing and what a fork would actually cost

The repository is not archived, and the last push was on 2026-09-22, one day before this writing. Dependencies are pinned to exact versions in requirements.txt, with a single exception: tzdata uses a >= constraint with a comment noting it keeps timezone data current. That pinning style means upgrades are deliberate events rather than continuous drift, which is normal for a deployed application but does mean a fork inherits the upgrade work.

The licence field is reported as NOASSERTION, and a LICENSE.md file exists at the repository root. That combination means the licence terms are not machine-classified and should be read directly in LICENSE.md before you reuse any code. Nothing in the README describes the licence, and this article cannot tell you what it permits. Treat the file as the source of truth and read it yourself; the terms govern whether a fork or a partial reuse is permissible at all.

Operationally, the Makefile shows what maintenance looks like for the maintainer: heroku logs piped through grep to separate application output from router output, and a dedicated 404 target that filters Heroku router lines for 404 responses. That is a small, specific set of operational commands rather than a general toolchain. Anyone forking would need to replace the Heroku-specific targets with equivalents for their own host, and would need to reconstruct the settings in conf/ without a published reference.

Editorial conclusion

Read this repository if you want to see how a deliberately minimal hosted blogging platform is assembled from Django, mistune, whitenoise and a Heroku Procfile, or if you are evaluating bearblog.dev as a place to publish. Do not clone it expecting a personal blog you can run on your own VPS: the README states that Bear was built as a platform, not as an individual blog generator, and points people who want the look to Hugo themes that reuse Bear's stylesheet instead. Before committing to the platform, verify the current pricing and account terms at bearblog.dev and the documentation at docs.bearblog.dev, since neither number appears in this repository.

Frequently asked questions

Official sources

1. HermanMartinus/bearblog on GitHub
2. Issues
3. README