SaraView/README.md

# SaraView

A self-hosted web file previewer/editor — Obsidian's look, without the parts
you don't use, plus image and video previewing. Read-only integration with
SaraTag's per-file Book tags is included.

## Project layout

```
SaraView/
├── Backend/            FastAPI app (Core, Explorer, Preview, Editor, BookReader, Main)
├── Frontend/            React app (Vite)
├── SaraViewConf.toml    Your editable config, mounted into the container
├── Dockerfile
└── docker-compose.yml
```

## Configure before deploying

Edit `SaraViewConf.toml` at the project root:

- `[Roots]` — add one entry per top-level folder you want browsable, e.g.
  `Notes = "/data/notes"`. The path here is the path *inside the container*;
  map it to a real folder via a volume mount in `docker-compose.yml`.
- `[SaraTag]` — set `CoreModulePath` to wherever your SaraTag installation's
  `.saratag` folder ends up mounted inside the container. Set `Enabled = false`
  if you don't want the Book/tag panel at all.
- `[Storage]` — `DataDirectory` is where Settings.toml and the Themes/ folder
  live. Leave this pointing at the `saraview_data` named volume already set
  up in `docker-compose.yml` — it's intentionally not one of your `[Roots]`,
  so it's unreachable from the file browser no matter what.

Then in `docker-compose.yml`:

- Add a `volumes:` line for every root you declared, mapping your real
  ZimaOS path to the container path used in `SaraViewConf.toml`.
- Mount your SaraTag `.saratag` folder read-only the same way.
- Bind the port to your Tailscale interface's IP rather than `0.0.0.0` if you
  want it reachable only over the tailnet (same pattern as your other
  tailnet-only services).

## Running it

```bash
docker compose up --build -d
```

The backend serves the built frontend directly, so the whole app is on one
port (`8420` by default).

## Local development (without Docker)

Backend:

```bash
cd Backend
pip install -r requirements.txt
uvicorn Main:Application --reload --port 8420
```

Frontend (in a second terminal — Vite proxies `/api` to the backend):

```bash
cd Frontend
npm install
npm run dev
```

## Notes on the SaraTag integration

SaraView never writes to Book or Lexicon files — it only reads them, by
loading SaraTag's own `Core.py` directly (by file path, not as an installed
package) so tag resolution always matches what SaraTag itself would show.
Editing tags from SaraView isn't implemented yet; SaraTag's own TUI remains
the place to do that for now.

## Settings and themes

Settings (font, font size, active theme, hidden-folder visibility, breadcrumb
visibility) and themes live in `Settings.toml` and `Themes/*.toml` inside the
`saraview_data` volume — not in any of your `[Roots]`, so they're never
browsable from the app itself. Three themes ship built in: CatppuccinMocha,
Gruvbox, and Forest. Every theme is just a flat set of named color roles
(Background, Surface, Text, Red, Orange, ... Purple), so creating a custom
theme from Settings — or hand-writing a new file in `Themes/` — only needs
those same role names filled in.

This is all per-user now — each account gets its own `Settings/<Username>.toml`
inside the data volume, seeded from the same defaults the first time that
user logs in. Themes themselves are shared across everyone (there's only one
copy of each theme file), but which theme is active is a per-user choice.

## Accounts and login

On first launch, with no accounts yet, SaraView shows a one-time "create the
admin account" screen instead of a normal login — whoever sets that up first
becomes an admin. After that, it's a normal username/password login screen
for everyone.

Accounts live in `Users.toml` in the same `saraview_data` volume as Settings
and Themes (passwords are hashed with PBKDF2-SHA256, never stored in plain
text). Admins get a "Users" section inside Settings to create additional
accounts, including other admins.

Sessions are currently in-memory only — restarting the container logs
everyone out. Fine for now with a small, trusted set of tailnet users; worth
revisiting if that stops being true.

## Running on ZimaOS without building locally

The repo publishes a built image to GitHub Container Registry via
`.github/workflows/docker-publish.yml`, so ZimaOS (or any other machine) can
just pull and run it instead of building from source every time.

**One-time setup after this workflow first runs:** GHCR packages built by a
workflow's built-in token default to **private**, even on a public repo. Go
to your GitHub profile → Packages → `saraview` → Package settings → Change
visibility → Public. Until you do this, pulling the image from ZimaOS will
fail with an authentication error.

**Installing on ZimaOS:**

1. Copy `docker-compose.ghcr.yml` and `SaraViewConf.toml` to the ZimaOS box
   (or wherever you're running `docker compose` from for this).
2. Edit the volume paths in `docker-compose.ghcr.yml` the same way you would
   for local `docker-compose.yml` — real paths on the left of each `:`.
3. In ZimaOS's dashboard, use **Install a customized app** (its Docker
   Compose import option) and point it at that compose file — or just run
   `docker compose -f docker-compose.ghcr.yml up -d` directly if you'd
   rather do it from a terminal on the box.

**Updating later:** push to `main` (or tag a release like `v1.1.0`) to build
a fresh image, then on ZimaOS re-pull and recreate the container — either
through its UI's update/recreate action, or `docker compose -f
docker-compose.ghcr.yml pull && docker compose -f docker-compose.ghcr.yml up -d`.

This gets SaraView pullable as a plain image; it doesn't yet show up with its
own icon/entry in ZimaOS's app store the way bundled apps do — that would
need a CasaOS-format AppStore manifest (icon, category, metadata) submitted
separately, which is a reasonable next step if you want it to feel fully
native rather than "a compose file I pasted in."

## Groups and access control

Admin isn't a hardcoded flag — it's the built-in "Admin" group, which can't
be deleted but is otherwise just a group like any other. Manage groups
(create, delete, edit membership) from Settings → Groups (admin-only).

Setting access on a file or directory is **not** admin-only — anyone can
restrict a file or directory to specific users and/or groups, whether at
creation time (the New File/New Directory dialog includes a search-and-
checkbox picker) or afterwards via the 🔒 button next to any entry, in
either the sidebar tree or the directory-browse pane. If you can currently
see something, you're trusted to change who else can. Admins do not bypass
restrictions - Admin is a management group (creating users, managing groups,
and so on), not a way to view everyone's private directories. Only direct
access to the server's files can see everything.

Restricting is per-file-or-directory — locking a directory covers everything
inside it automatically (there's only ever one restriction record per locked
directory; reaching anything underneath still requires being permitted on
that ancestor), while locking an individual file affects only that file.

Anyone without access gets a plain 404, both for direct requests and for
that entry showing up in a directory listing — a restricted item's existence
isn't revealed to people who can't see it. Admins get a global overview of
every current restriction from Settings → Locked Directories.

## Blame privacy

Each person can turn off "Show my edits in others' blame view" in their own
Settings. When that's off, other users still see that lines were changed —
just with the identity redacted, rather than attributing it to someone who
asked not to be shown. You can always see your own attribution regardless of
this setting. There's also a per-viewer toggle for showing avatars instead
of usernames in the blame gutter, using each author's chosen colour either
way.