Maashkinoozhe/MangaCircus
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare the repository for a public release

Browse Source 
- docs/deployment.md: step-by-step Docker deployment for anyone (setup,
  configuration, LAN/HTTPS/VPN access, adding manga, operation, prebuilt
  images, backups, peering, troubleshooting, rules for agents).
- deploy/circus.sh: host helper without Node (status, up/down with queue
  pause, logs, pause/resume, update, rescan, restore-test); deploy/compose.https.yml
  + Caddyfile for automatic HTTPS.
- README rewritten for public readers (Docker first, sources/copyright note,
  docs index); AGENTS.md + CLAUDE.md for contributors and coding agents.
- Removed notes about one particular installation (Windows host, handoffs,
  audits of a private library, benchmarks with local paths, wishlist, reading
  map) and the unused ops/proxmox templates; generalized remaining mentions of
  hosts, VPN and Windows-only commands.
- Defaults: TZ and reading time zone UTC; .gitattributes keeps shell/YAML LF.
- Personal agent coordination files are git-ignored (CLAUDE.local.md,
  .claude/skills/manga-org/).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MaashkinoozheandClaude Opus 5.5 committed 2026-10-24 11:09:00 +02:00
1 parent 7b52da2f9c
commit f53b92a7dc
24 files changed
+556 -122
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+64 -55
View File
@@ -8,59 +8,53 @@ A no-frills, self-hosted manga / comic / webtoon reader.
- Reader with three view modes (**Flow**, **Page**, **Book**), a page zoom that leaves the controls alone, and tap zones for mobile.
- A separate **Greatest of All Time** manga-history dashboard, with five-year periods, per-user wish ratings, community ranking, and local-library badges. Its curated titles do not enter the download queue.
## Run it
## Run it with Docker
The supported way to run MangaCircus is Docker Compose on a Linux host: one image, a **reader**
service (the web app) and a **scraper** service (the managed download queue). Short version:
```bash
node server.js
git clone <repository-url> mangacircus && cd mangacircus
mkdir -p library data/scraper data/peering data/peering-usage backup .secrets
openssl rand -hex 32 > .secrets/scraper_token && chmod 600 .secrets/scraper_token
cp .env.example .env # set LIBRARY_PATH etc.; see the guide
sudo chown -R 1000:1000 library data backup
docker compose build
bash deploy/circus.sh up # reader first, then the scraper
```
Open http://localhost:8080. The first account you create becomes the admin. Try it with demo content:
Open http://127.0.0.1:8080. The first account you create becomes the admin. The full guide covers
configuration, LAN and HTTPS access (a ready Caddy setup is included), adding manga, updates, backups,
peering and troubleshooting: **[docs/deployment.md](docs/deployment.md)**.
## Try it without Docker
Needs Node.js 18 or newer, nothing else:
```bash
node tools/make-dummy.js library
node tools/make-dummy.js library # five demo manga
npm run start:all # reader on :8080 and the scraper daemon on 127.0.0.1:8091
```
To run the reader and managed scraper 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](docs/collections.md)
and [resilience](docs/resilience.md) 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](docs/local-deployment.md) for its observed layout, health
checks, restart procedure, and recovery point.
Deployment-controlled reading hours and the optional progress-aware quiz are
documented in [reading limiter](docs/reading-limiter.md). They are disabled
unless configured on the reader container.
See [Greatest of All Time](docs/greatest.md) for catalog ownership, voting, and metadata refresh.
### Docker
```bash
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 and scraper 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](docs/compose-deployment.md) for local development, VM
recommendations, cutover, image releases and backup/rollback. The local Docker stack
is verified; VM deployment is still pending.
`npm start` runs the reader alone. Admins manage the persistent download queue, pauses, retries and rate
limits under **Settings → Admin → Scraper**. The reader keeps working when the scraper is stopped.
**Settings → Admin → Collections & metadata** manages grouped tiles, reading order and relationships, and
**Settings → Admin → Service health** shows recovery incidents and backups ([collections](docs/collections.md),
[resilience](docs/resilience.md)). Deployment-controlled reading hours and the optional progress-aware quiz
are described in [reading limiter](docs/reading-limiter.md); they are off unless configured.
See [Greatest of All Time](docs/greatest.md) for that dashboard's catalog and voting.
### 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](docs/settings-navigation.md) for routes and verification.
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. Only admins see administration ([settings navigation](docs/settings-navigation.md)).
### Settings (environment variables)
These configure the reader process. In Docker most are set for you by `docker-compose.yml`; the variables
you put in `.env` are listed in [docs/deployment.md](docs/deployment.md#4-configure-env).
| Variable | Default | Meaning |
|-----------------|-------------|---------|
| `PORT` | `8080` | HTTP port |
@@ -76,7 +70,15 @@ see administration; personal settings do not poll scraper services. See
| `SCRAPER_TOKEN_FILE` | empty | Alternative secret file (used in Compose) |
| `BACKUP` | – | Existing folder for built-in backups of `DATA`; unset = off. Compose: set `BACKUP_PATH`. Schedule and retention under Settings → Service health ([backup](docs/backup.md)) |
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.
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.
### Sources and copyright
The scraper can download from WeebCentral, MangaDex and MangaPill, and peering can copy chapters between
servers. You are responsible for only downloading and sharing what you are allowed to copy where you live,
and for respecting each site's terms. The scraper is deliberately slow and stops on access errors; it never
bypasses CAPTCHAs, logins or other access controls ([scraper/AGENT_RUNBOOK.md](scraper/AGENT_RUNBOOK.md)).
---
@@ -101,23 +103,27 @@ library/
## 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](docs/library-format.md) | The folder format: naming rules, page tags, metadata fields, versions, extras, what survives a rename |
| [docs/import.md](docs/import.md) | How the library is scanned and indexed, caching, change detection and notifications, troubleshooting |
| [docs/architecture.md](docs/architecture.md) | Components, data model, API, security, the reader's layout engine, deployment, design decisions |
| [docs/local-deployment.md](docs/local-deployment.md) | Current local Compose deployment, Tailscale access, persistent state, checks, restart, and recovery |
| [docs/settings-navigation.md](docs/settings-navigation.md) | User/Admin settings sections, scraper tabs, routes and UI checks |
| [docs/backup.md](docs/backup.md) | Built-in scheduled backup of `data/`, what it contains, retention and the restore procedure |
| [docs/reading-insights-concept.md](docs/reading-insights-concept.md) | Active-time presentation, private summaries, deletion/export controls, and the future journal design |
| [docs/deployment.md](docs/deployment.md) | Docker deployment: setup, configuration, HTTPS, operation (`deploy/circus.sh`), updates, backups, troubleshooting |
| [docs/library-format.md](docs/library-format.md) | The folder format: naming rules, page tags, metadata fields, chapter dates, versions, extras, what survives a rename |
| [docs/import.md](docs/import.md) | How the library is scanned and indexed, caching, change detection and notifications |
| [docs/architecture.md](docs/architecture.md) | Components, data model, API, security, the reader's layout engine, design decisions |
| [docs/scraper-service.md](docs/scraper-service.md) | The managed download queue, private API and adapter contract |
| [docs/scraper-guide.md](docs/scraper-guide.md) | Rule book (agent-readable) for scrapers and other tools that write into the library |
| [scraper/AGENT_RUNBOOK.md](scraper/AGENT_RUNBOOK.md) | Conservative scraper workflow and host-specific procedures for automated agents |
| [scraper/AGENT_RUNBOOK.md](scraper/AGENT_RUNBOOK.md) | Conservative scraper workflow, rate limits and stop conditions for automated agents |
| [docs/source-modules.md](docs/source-modules.md) | Adding a new source to the scraper |
| [docs/peering.md](docs/peering.md) | Optional server-to-server sharing over mutual TLS |
| [docs/backup.md](docs/backup.md) | Built-in scheduled backup of `data/`, what it contains, retention and restore |
| [docs/settings-navigation.md](docs/settings-navigation.md) | User/Admin settings sections, scraper tabs and routes |
| [docs/reading-insights-concept.md](docs/reading-insights-concept.md) | Active-time presentation, private summaries, export and deletion |
| [docs/resilience.md](docs/resilience.md) | Supervisors, automatic recovery limits and incidents |
| [AGENTS.md](AGENTS.md) | Working on the code: layout, tests, rules for contributors and coding agents |
Unnumbered MangaDex pilots and one-shots use stable `special-mangadex-<chapter-uuid>` chapter keys and
human labels, not invented numbers. 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.
---
@@ -156,5 +162,8 @@ whole-series completeness. See the scraper service and library format contracts
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)
scraper/ download queue daemon, source adapters, publisher
peering/ optional server-to-server sharing
deploy/ Docker operations helper (circus.sh) and HTTPS with Caddy
tools/ demo library generator, maintenance and test tools
```