12 KiB
MangaCircus
A no-frills, self-hosted manga / comic / webtoon reader.
- Zero dependencies. A Node.js server (
server.js,library.js) and plain HTML/CSS/JS pages. No build step, no framework, no database server. - Reads the manga straight from a folder tree. The same folders stay readable in any normal picture viewer.
- Accounts with per-user reading progress, view settings, an opt-in Active Reading Clock, a private Reading Story and "new chapter" notifications.
- Reader with three view modes (Flow, Page, Book), a page zoom that leaves the controls alone, and tap zones for mobile.
Run it
node server.js
Open http://localhost:8080. The first account you create becomes the admin. Try it with demo content:
node tools/make-dummy.js library
To run the reader, managed scraper and Sentinel together, use npm run start:all. Admins can
then manage the persistent download queue, progress, pauses, retries, and rate limits
under Settings → Admin → Scraper. The reader continues working if the scraper is stopped.
Settings → Admin → Collections & metadata manages grouped tiles, reading order and relationships;
Settings → Admin → Service health shows recovery incidents. See collections
and resilience for the ownership and agent-maintenance contracts.
The current Windows installation uses Docker Compose; its old MangaCircus Supervisor
Scheduled Task is disabled. Do not run a native duplicate writer. See
docs/local-deployment.md for its observed layout, health
checks, restart procedure, and recovery point.
Docker
node tools/prepare-compose.js
docker compose config -q
docker compose up -d --build
Stop existing native writers before using their data in containers. docker-compose.yml
runs reader, scraper and Sentinel with explicit persistent bind mounts (library/,
data/), file-backed secrets and only a loopback reader port. No named data volume is
used. See Compose deployment for local development, VM
recommendations, cutover, image releases and backup/rollback. The local Docker stack
is verified; VM deployment is still pending.
Settings workspace
Settings has User and Admin menu groups. User sections cover Reading, Reading time & privacy, Notifications and Account. Admin sections cover Scraper, Server & library, Users & access, Collections & metadata and Service health. Scraper has local Queue, Automatic updates and Hoster settings tabs. Only admins see administration; personal settings do not poll scraper services. See settings navigation for routes and verification.
Settings (environment variables)
| Variable | Default | Meaning |
|---|---|---|
PORT |
8080 |
HTTP port |
LIBRARY |
./library |
Library folder (read-only access is enough) |
DATA |
./data |
Where db.json (users, progress, votes, notifications) and disposable library-index caches live |
SIGNUP |
closed |
open lets anyone create an account. Otherwise the admin adds users under Settings |
SCAN_INTERVAL |
10 |
Minutes between shallow library change checks (0 disables this timer) |
FULL_SCAN_INTERVAL |
1440 |
Minutes between full library reconciliations (0 disables this timer) |
COOKIE_SECURE |
– | 1 marks the login cookie Secure (use it when you serve over HTTPS) |
SCRAPER_URL |
http://127.0.0.1:8091 |
Private scraper daemon URL |
SCRAPER_TOKEN |
empty | Shared daemon token; required when it listens beyond loopback |
SCRAPER_TOKEN_FILE |
empty | Alternative secret file (used in Compose) |
SENTINEL_URL |
http://127.0.0.1:8092 |
Private observation service URL |
Serve it behind a reverse proxy with HTTPS if it is reachable from the internet. All pages use relative URLs, so a sub-path like /manga/ works.
Library format
Always three folder levels, Manga / Book / Chapter, with plain page images in the chapter folder. Page roles are tags in the file name:
library/
Moon Garden/ <- manga folder (its name is the manga's id)
manga.json cover.jpg <- optional
v01 Spring/ <- book (volume / season)
c0001 The Seed/ <- chapter
chapter.json <- recommended
0001_cover.jpg 0002.jpg 0003_double.jpg 0004_rot90.jpg 0005_extra.jpg
c0002 Roots [MangaDex]/ <- same number twice = two versions of one chapter
c0002 Roots [Official]/
c0002.5 Tea Time/ <- in-between chapter
x01 Character Sheets/ <- extra chapter, outside the numbering
x01 Specials/ <- extra book
Documentation
Unnumbered MangaDex pilots/one-shots use stable special-mangadex-<chapter-uuid>
chapter keys and human labels, not fabricated numbers. Existing numeric IDs remain
unchanged. In Settings → Admin → Scraper, Inspect & queue shows the source edition
before Confirm download. “Job finished” refers to its selected scope, not verified
whole-series completeness. See the scraper service and library format contracts below.
| Document | For |
|---|---|
| docs/library-format.md | The folder format: naming rules, page tags, metadata fields, versions, extras, what survives a rename |
| docs/import.md | How the library is scanned and indexed, caching, change detection and notifications, troubleshooting |
| docs/architecture.md | Components, data model, API, security, the reader's layout engine, deployment, design decisions |
| docs/local-deployment.md | Current local Compose deployment, Tailscale access, persistent state, checks, restart, and recovery |
| docs/settings-navigation.md | User/Admin settings sections, scraper tabs, routes and UI checks |
| docs/reading-insights-concept.md | Active-time presentation, private summaries, deletion/export controls, and the future journal design |
| docs/scraper-guide.md | Rule book (agent-readable) for scrapers and other tools that write into the library |
| scraper/AGENT_RUNBOOK.md | Conservative scraper workflow and host-specific procedures for automated agents |
Reading
| Flow | All pages below each other at the same width. Double pages keep the same height and are twice as wide, but never wider than the screen. Webtoon slices join without gaps |
| Page | One page (or one double page) at a time |
| Book | Two facing pages, in reading order (right page first for rtl). Covers and double pages stand alone. Pairing restarts after each of them, so one odd page never shifts the whole chapter. If pairs still look wrong, ⇄ Shift moves the pairs of the current section by one page (remembered per chapter) |
- Which mode opens: Settings → Open chapters in = a fixed mode or the mode I used last. With Use the fitting mode… on, content that isn't made for your choice opens in the mode that fits (webtoons always open in Flow). That automatic switch never changes your remembered mode. Only clicking a mode in the reader does.
- Page zoom: 100 % means the page fits the screen (in Flow: a normal single page fits the screen; for webtoons, the strip is as wide as the screen but never wider than its own width). Pages may end up larger than the screen, exactly fitting, or smaller. The toolbar −/+ buttons and keyboard
-/+move in 5-percentage-point steps from 20 % through 600 %;0or the percentage button returns to 100 %. Ctrl + mouse wheel, touchpad pinch and two-finger pinch remain continuous for still finer control. This zooms only the pages; zooming over the toolbar zooms the whole page as usual. When a page is larger than the screen, drag it with the mouse (hand cursor) or pan with a finger. Flow locks horizontal movement while the content fits within the viewport, then enables it automatically when zoom makes the content wider. The zoom is remembered per mode for your account. - Flow page gap: Settings → Reading lets each user keep the normal separator between Flow pages or remove it for continuous webtoon artwork and text that crosses image edges.
- Active Reading Clock: opt in under Settings → User → Reading time & privacy. No scrolling-speed limit; a visit counts at 60% viewed-page coverage and saves on exit. Pauses in the background or after 30 seconds without reader activity. Tap the clock for this visit's time, coverage, qualification and loading wait.
- Your Reading Story: private active-time summaries appear on the library and manga pages when history exists. Chapter rows show the last timed read (60%-coverage visit), rereads remain visible as lifetime time, and Settings lets each user hide, export, or delete their own history. No leaderboards or speed ranking are used.
- Tap / click zones:
- Tapping beside the pages always shows or hides the controls.
- On a page, its left and right part turn the page, following the reading direction. For
rtl, the left part goes forward. - In Flow: the bottom part of the screen goes forward, the top part goes back.
- The middle of the page also toggles the controls (useful when a zoomed page fills the screen).
- A horizontal swipe also turns pages on touch screens.
- Keys: arrows, Space / PageDown,
m= controls,f= fullscreen.
- Controls stay out of the way: they hide as soon as you turn a page or scroll, and come back only with a tap (middle of the page or beside it). Scrolling up never brings them back. The first time they hide, a short hint says so.
- Controls: the top bar has a chapter picker with every chapter of the manga, grouped by book, with ✓ for read ones. The bottom bar has the page slider, the mode switch, Shift, zoom, the version picker and previous/next chapter.
- Loading: the next pages (next 3 in Page mode, next 2 spreads in Book mode) are downloaded and decoded in advance, so page turns don't flash. A page that still isn't there shows a spinner. On phones, "Add to home screen" opens the app without browser bars, and the ⛶ button (where supported) goes fullscreen.
- Progress is saved per user and chapter version: the last page, whether the chapter is done, and book-mode shifts. The manga page offers Continue. Tap a chapter's status to mark it read/unread.
- Notifications: press Notify me on a manga. When a rescan finds new chapter numbers, they show up under the bell. Optionally, the server also POSTs a short text to a webhook URL of your choice (e.g. an ntfy.sh or Gotify topic, set in Settings).
- Finding manga: the library can search titles, alternative titles, and authors; filter by publication status; combine tags with AND matching; and sort by title, activity, or first release date. Tag links on a manga open the library with that tag selected.
- Manga overview: metadata is shown in a structured panel (with the complete raw
manga.jsonavailable for inspection). Chapters are newest-first, with multi-select volume filters; selecting no volume means all volumes.
Files
server.js HTTP server, accounts, progress, votes, notifications (JSON file storage)
library.js folder scanner + image size reader
public/ the web pages (library, manga, reader, settings, login)
tools/ demo library generator (pure Node, draws PNGs itself)