dev: public ready

dev: Readme, COC, others dev: xml-template
2025-11-19 13:16:25 -05:00 · 2025-11-19 13:16:25 -05:00 · 1cf5119f46
commit 1cf5119f46
parent 5db584830b
12 changed files with 3716 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,170 @@
+# Gopherbook – Self-Hosted Comic Library & CBZ Reader
+
+Gopherbook is a lightweight, single-binary, self-hosted web comic reader and library manager written in Go.  
+It is designed for people who want full control over their digital comic collection (CBZ files), including support for password-protected/encrypted archives, per-user libraries, tagging, automatic organization, and a clean modern reader.
+
+## License
+
+[![Custom badge](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fshare.jester-designs.com%2Fview%2Fpil.json)](LICENSE)
+
+## Features
+
+- Upload & read `.cbz` (ZIP-based) comics directly in the browser
+- Full support for password-protected/encrypted CBZ files (AES-256 via yeka/zip)
+- Automatically tries all previously successful passwords when opening a new encrypted comic
+- Persists discovered passwords securely (AES-encrypted on disk, key derived from your login password)
+- Extracts ComicInfo.xml metadata (title, series, number, writer, inker, tags, story arc, etc.)
+- Automatic folder organization: `Library/Artist/StoryArc/Comic.cbz`
+- Manual reorganization via UI if needed
+- Powerful tagging system with custom colors and counts
+- Filter comics by any combination of tags
+- Responsive grid view with cached JPEG covers
+- Full-screen web reader with:
+  - Page pre-loading
+  - Zoom / pan
+  - Fit-to-width/height/page
+  - Keyboard navigation (←→, A/D, +/-, Esc)
+- Multi-user support:
+  - Each user has their own completely isolated library and password vault
+  - First registered user becomes admin
+  - Admin can disable new registrations
+  - Admin can delete any comic
+- No external database – everything stored in simple JSON files
+- Single static Go binary + file storage – easy to deploy
+
+## Installation / Running
+
+### Prerequisites
+[![Go](https://img.shields.io/badge/go-%2300ADD8.svg?style=for-the-badge&logo=go&logoColor=white)](https://golang.org/dl/)
+- Go 1.25.2+ (only needed to build)
+- Or just download a pre-built binary from Releases (when available)
+
+### Quick start (from source)
+
+```bash
+git clone https://codeberg.org/riomoo/gopherbook.git
+cd gopherbook
+go build -o gopherbook app/gopherbook/main.go
+./gopherbook
+```
+
+Then open http://localhost:8080 in your browser.
+
+## If you want to use this with podman:
+
+```bash
+git clone https://codeberg.org/riomoo/gopherbook.git
+cd gopherbook
+./bash-scripts/run.sh
+```
+
+Then open http://localhost:12010 in your browser.
+
+### First launch
+1. On first run there are no users → registration is open
+2. Create the first account → this user automatically becomes admin
+3. Log in → start uploading CBZ files
+
+## Directory layout after first login
+
+```
+./library/username/                ← your comics (organized or Unorganized/)
+./library/username/comics.json     ← metadata index
+./library/username/tags.json       ← tag definitions & counts
+./library/username/passwords.json  ← encrypted password vault (AES)
+./cache/covers/username/           ← generated cover thumbnails
+./etc/users.json                   ← user accounts (bcrypt hashes)
+./etc/admin.json                   ← admin settings (registration toggle)
+```
+
+## How encrypted/password-protected comics work
+
+- When you upload or scan an encrypted CBZ that has no known password yet, the server marks it as Encrypted = true.
+- The first time you open it in the reader, a password prompt appears.
+- If the password is correct, Gopherbook:
+  - Stores the password (encrypted with a key derived from your login password)
+  - Extracts ComicInfo.xml metadata
+  - Auto-organizes the file into Artist/StoryArc folders
+  - Updates tags and cover cache
+- From then on the comic opens instantly, and that password is automatically tried on every future encrypted comic you upload (so whole collections that share one password "just work").
+
+## Security notes
+
+- Passwords are stored encrypted on disk using AES-256-CFB with a key derived from your login password via SHA-256.
+- Session cookie is HttpOnly, expires after 24 h.
+- No external dependencies that phone home.
+- Still: treat this as a personal/private server – do not expose it publicly without HTTPS/reverse-proxy auth.
+
+## Config for NGINX to use as a website:
+```
+upstream gopherbook {
+        server 127.0.0.1:8080;
+        #server 127.0.0.1:12010; #For Podman instead
+        server [::1]:8080;
+        #server [::1]:12010; #For Podman instead
+}
+server {
+        listen 80;
+        listen [::1]:80;
+        server_name gopherbook.example.com;
+        location / {
+                proxy_pass http://gopherbook;
+                proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+                proxy_set_header X-Forwarded-Proto $scheme;
+                # 1. Allow very large uploads (e.g. 500 MB – adjust as needed)
+                client_max_body_size 500M;          # 0 = unlimited, but never do that on a public server
+
+                # 2. Give the upload enough time (important for slow connections)
+                client_body_timeout 5m;             # time to read the entire request body (default 60s)
+                proxy_read_timeout 5m;              # if you're proxying to your Go app
+                proxy_send_timeout 5m;
+
+                # 3. Increase buffer sizes so Nginx doesn't spill everything to disk
+                client_body_buffer_size 512k;       # default 8k/16k – too small for big uploads
+                proxy_buffers 8 512k;
+                proxy_buffer_size 256k;
+
+                # 4. Recommended: put uploads in a temporary directory with plenty of space
+                client_body_temp_path /var/lib/nginx/body 1 2;   # make sure this directory exists and is writable by nginx
+        }
+}
+```
+
+## Contributing
+
+Pull requests are welcome! Especially:
+- Better mobile reader experience
+- Bulk tag editing
+- Search box
+- OPDS catalog endpoint
+- More metadata sources (ComicVine, etc.)
+
+Please open an issue first for bigger changes.
+
+## Thanks / Credits
+
+- yeka/zip – password-protected ZIP support in pure Go
+- The ComicRack ComicInfo.xml standard
+- Everyone who hoards comics ❤️
+
+Enjoy your library!  
+— Happy reading with Gopherbook
+
+<div align="center">
+
+## Software Used but not included
+
+![Arch](https://img.shields.io/badge/Arch%20Linux-1793D1?logo=arch-linux&logoColor=fff&style=for-the-badge)
+![Gimp Gnu Image Manipulation Program](https://img.shields.io/badge/Gimp-657D8B?style=for-the-badge&logo=gimp&logoColor=FFFFFF)
+![Vim](https://img.shields.io/badge/VIM-%2311AB00.svg?style=for-the-badge&logo=vim&logoColor=white)
+![Git](https://img.shields.io/badge/git-%23F05033.svg?style=for-the-badge&logo=git&logoColor=white)
+![Forgejo](https://img.shields.io/badge/forgejo-%23FB923C.svg?style=for-the-badge&logo=forgejo&logoColor=white)
+
+</div>
+
+## Creator:
+- [Codeberg Riomoo](https://codeberg.org/riomoo)
+- [GitGud Riomoo](https://gitgud.io/riomoo)
+- [Github Riomoo](https://github.com/riomoo)