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."