From 72e722c094f7cc05f1e5d8f103c44cccca9ac115 Mon Sep 17 00:00:00 2001 From: Leo Vasanko Date: Fri, 28 Aug 2026 23:23:51 +0000 Subject: [PATCH] README rewrite with positioning and run instructions; production setup guide --- README.md | 44 ++++++++++++++++++++++++- docs/setup.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/setup.md diff --git a/README.md b/README.md index 3d7b4a4..fb2d315 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,45 @@ # Pagerite -A single-user CMS/blog. FastAPI serves HTML rendered in Python with html5tagger, content is persisted in a kanta database and rendered on the fly per request. Vue is used only for the interactive editing tools, not for the public pages. +A CMS for people who are done patching WordPress. There's no PHP or Node.js to exploit — the whole editing surface sits behind your own SSO proxy, so the server the internet can talk to just renders plain pages that search engines and social media can read too. Further, the articles have rich layout and don't look boxed in like in most web publishing platforms. The software is lightweight and fast enough to serve any number of visitors you have. + +We run our own site [vasanko.com](https://vasanko.com/) on it, in case you wish to have a quick look. + +## Run it + +```sh +uvx pagerite localhost +``` + +That serves a demo site on localhost. When you take it to production, pass your domain name instead. Our [setup guide](https://git.zi.fi/LeoVasanko/pagerite/src/branch/main/docs/setup.md) walks through the whole production arrangement. + +## What it's like + +**You write, it renders.** Articles are Markdown with the extensions that matter — tables, footnotes, task lists, callouts, highlighted code, aside boxes — and raw HTML goes through untouched when Markdown runs out. Layout is yours to command from the text: float an image `{.right}`, drop a note in the `{.margin}`, let a photo or a code block go `{.wide}` across the whole viewport. Long articles reflow into a proper two-column composition on wide screens without you doing anything. + + + +**Editing happens on the page.** Click the pen next to a heading and an editor docks beside the live article, previewing server-side as you type. Site name, theme, fonts, banner, custom CSS — changed in a panel, applied immediately. New pages grow from a ➕ in the structure tree; drag or rename rows to reorder your whole navigational hierarchy. Entirely custom or premade top banner designs per category or page are available. + +Full scripting and styling is available for editors who wish to implement more complex functionality on their articles. This also means you should only let trusted users write on your site: this is by no means a public blog platform. + +The worst case scenario when a hacker gains access to your admin accounts: they can take over the entire site and run scripts on user's browsers, but the damage is limited to same domain. All your articles can be restored to the state prior to that hack or that one user's edits undone, and no data is irrecoverably lost. This is much better than other platforms that also let hackers run code on your server (WordPress). + + + +**Theming is one CSS file.** Themes, banner designs and page transitions are plain CSS (plus a bit of SVG) read straight from disk — pick one from the site editor or copy a folder and make it yours. Fonts are self-hosted; your site never phones a third party for anything. + + + +**Search engines and social cards come free.** Every page gets a proper description, canonical link and Open Graph/Twitter card metadata derived from the article — including a share image picked from your own figures — without a single "SEO plugin". + +**You can see your readers.** Built-in analytics need no cookies and no third-party tracker: visits, referers, reading time and a live map of how people move between your pages, plus separate ledgers for crawlers and the scanners probing for `/.env` — who are, of course, wasting their time here. + + + +## Keeping the doors locked + +Pagerite has no accounts of its own. Pair it with [Paskia](https://git.zi.fi/leovasanko/paskia), a small SSO server that gates the editing API behind your reverse proxy — the : systemd service, Caddy (or your proxy of choice), and forward-auth. On your own machine, with no proxy, editing is simply open. + +## More + +The details — architecture, content model, theming, analytics — live in the [documentation](docs/overview.md). diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..70fb07d --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,91 @@ +# Production setup + +From a local demo to a real site: run Pagerite as a systemd service behind +a reverse proxy that terminates HTTPS, with Paskia guarding the editing API. + +The moving parts: + +- **Pagerite** — serves the public site on `localhost:8100` and the editing + API under `/_api`. +- **Paskia** — the SSO server; owns `/auth/` and answers forward-auth + subrequests. +- **A reverse proxy** — Caddy below, but nginx or anything with + forward-auth support works the same way. + +## Pagerite as a systemd service + +Install [uv](https://docs.astral.sh/uv/getting-started/installation/) on the +system, create a user, and add a template unit: + +```sh +sudo useradd --system --home-dir /srv/pagerite --create-home pagerite +curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin sh +sudo systemctl edit --force --full pagerite.service +``` + +```ini +[Unit] +Description=Pagerite CMS + +[Service] +Type=simple +User=pagerite +SyslogIdentifier=pagerite +WorkingDirectory=/srv/pagerite +ExecStart=uvx pagerite example.com --dbip + +[Install] +WantedBy=multi-user.target +``` + +Replace `example.com` with your actual domain name. `--dbip` keeps the local GeoIP database up to date: leave out if you don't want DBIP data for analytics. + +```sh +sudo systemctl enable --now pagerite +sudo journalctl -ocat -fu pagerite +``` + +## Running it on internet + +We recommend Caddy for making your site publicly visible on the Internet. Presumably you already have some proxy, perhaps Nginx, but our setup is not much different of any other service you might already be running. ChatGPT and the likes can also help with the configuration because online documentation is limited. Note that Paskia also has extensive documentation on [running on various proxy servers](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/proxy/index.md) + +Install [Caddy](https://caddyserver.com/) and follow the [Paskia setup guide](https://git.zi.fi/LeoVasanko/paskia) to get the SSO server running and its `auth` snippets copied to `/etc/caddy/auth` — that guide covers Paskia's own configuration and admin registration in detail. + +Then the site config. Only the editing API needs gating; the site itself is public: + +```caddyfile +example.com { + import auth/setup + + reverse_proxy /auth/* localhost:4401 + + @api path /_api/* + handle @api { + import auth/require perm=pagerite:admin + reverse_proxy localhost:8100 + } + + handle { + reverse_proxy localhost:8100 + } +} +``` + +Reload Caddy, then create a permission with scope `pagerite:admin` in the +Paskia admin panel (`/auth/admin/`) and assign it to yourself, as the Paskia +guide describes. Anonymous visitors now get 401 from `/_api`, logged-in +users without the permission get 403, and admins get the editing pens. + +## nginx or another proxy + +The shape is identical everywhere: + +- `/auth/` proxies to Paskia (`localhost:4401`). +- `/_api` requires a forward-auth subrequest against Paskia — on nginx that + is `auth_request` against Paskia's verify endpoint — before proxying to + Pagerite (`localhost:8100`). +- Everything else proxies straight to Pagerite. + +Paskia ships per-proxy forward-auth guides covering +[Caddy, nginx and others](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/proxy/index.md); +adapt the matcher to `/auth/` and `/_api` as above and leave the rest public.