Update documentation README

README.md

@@ -1,116 +1,118 @@
-# Cista Web Storage
+# Cista Web Storage
-
+
-<img src="https://git.zi.fi/Vasanko/cista-storage/raw/branch/main/docs/cista.jpg" align=right width=250>
+<img src="https://git.zi.fi/Vasanko/cista-storage/raw/branch/main/docs/cista.webp" align=left width=250>
-
+
-Cista takes its name from the ancient cistae, metal containers used by Greeks and Egyptians to safeguard valuable items. This modern application provides a browser interface for secure and accessible file storage, echoing the trust and reliability of its historical namesake.
+Cista takes its name from the ancient *cistae*, metal containers used by Greeks and Egyptians to safeguard valuable items. This modern application provides a browser interface for secure and accessible file storage, echoing the trust and reliability of its historical namesake.
-
+
-This is a cutting-edge **file and document server** designed for speed, efficiency, and unparalleled ease of use. Experience **lightning-fast browsing**, thanks to the file list maintained directly in your browser and updated from server filesystem events, coupled with our highly optimized code. Fully **keyboard-navigable** and with a responsive layout, Cista flawlessly adapts to your devices, providing a seamless experience wherever you are. Our powerful **instant search** means you're always just a few keystrokes away from finding exactly what you need. Press **1/2/3** to switch ordering, navigate with all four arrow keys (+Shift to select). Or click your way around on **breadcrumbs that remember where you were**.
+This is a cutting-edge **file and document server** designed for speed, efficiency, and unparalleled ease of use. Experience **lightning-fast browsing**, thanks to the file list maintained directly in your browser and updated from server filesystem events, coupled with our highly optimized code. Fully **keyboard-navigable** and with a responsive layout, Cista flawlessly adapts to your devices, providing a seamless experience wherever you are. Our powerful **instant search** means you're always just a few keystrokes away from finding exactly what you need. Press **1/2/3** to switch ordering, navigate with all four arrow keys (+Shift to select). Or click your way around on **breadcrumbs that remember where you were**.
-
+
-The Cista project started as an inevitable remake of [Droppy](https://github.com/droppyjs/droppy) which we used and loved despite its numerous bugs. Cista Storage stands out in handling even the most exotic filenames, ensuring a smooth experience where others falter.
+The Cista project started as an inevitable remake of [Droppy](https://github.com/droppyjs/droppy) which we used and loved despite its numerous bugs. Cista Storage stands out in handling even the most exotic filenames, ensuring a smooth experience where others falter.
-
+
-All of this is wrapped in an intuitive interface with automatic light and dark themes, making Cista Storage the ideal choice for anyone seeking a reliable, versatile, and quick file storage solution. Quickly setup your own Cista where your files are just a click away, safe, and always accessible.
+All of this is wrapped in an intuitive interface with automatic light and dark themes, making Cista Storage the ideal choice for anyone seeking a reliable, versatile, and quick file storage solution. Quickly setup your own Cista where your files are just a click away, safe, and always accessible.
-
+
-Experience Cista by visiting [Cista Demo](https://drop.zi.fi) for a test run and perhaps upload something...
+Experience Cista by visiting [Cista Demo](https://drop.zi.fi) for a test run and perhaps upload something...
-
+
-
+
-## Getting Started
+## Getting Started
-### Installation
+### Installation
-
+
-To install the cista application, use:
+To install the cista application, use:
-
+
-```fish
+```fish
-pip install cista
+pip install cista
-```
+```
-
+
-Note: Some Linux distributions might need `--break-system-packages` to install Python packages, which are safely installed in the user's home folder. As an alternative to avoid installation, run it with command `pipx run cista`
+Note: Some Linux distributions might need `--break-system-packages` to install Python packages, which are safely installed in the user's home folder. As an alternative to avoid installation, run it with command `pipx run cista`
-
+
-### Running the Server
+### Running the Server
-
+
-Create an account: (or run a public server without authentication)
+Create an account: (or run a public server without authentication)
-```fish
+```fish
-cista --user yourname --privileged
+cista --user yourname --privileged
-```
+```
-
+
-Serve your files at http://localhost:8000:
+Serve your files at http://localhost:8000:
-```fish
+```fish
-cista -l :8000 /path/to/files
+cista -l :8000 /path/to/files
-```
+```
-
+
-The server remembers its settings in the config folder (default `~/.local/share/cista/`), including the listen port and directory, for future runs without arguments.
+The server remembers its settings in the config folder (default `~/.local/share/cista/`), including the listen port and directory, for future runs without arguments.
-
+
-### Internet Access
+### Internet Access
-
+
-To use your own TLS certificates, place them in the config folder and run:
+To use your own TLS certificates, place them in the config folder and run:
-
+
-```fish
+```fish
-cista -l cista.example.com
+cista -l cista.example.com
-```
+```
-
+
-Most admins instead find the [Caddy](https://caddyserver.com/) web server convenient for its auto TLS certificates and all. A proxy also allows running multiple web services or Cista instances on the same IP address. Caddy configuration **/etc/caddy/Caddyfile** is dead simple:
+Most admins instead find the [Caddy](https://caddyserver.com/) web server convenient for its auto TLS certificates and all. A proxy also allows running multiple web services or Cista instances on the same IP address but different (sub)domains.
-
+
-```Caddyfile
+`/etc/caddy/Caddyfile`:
-cista.example.com {
+
-    reverse_proxy :8000
+```Caddyfile
-}
+cista.example.com {
-```
+    reverse_proxy :8000
-
+}
-## Development setup
+```
-
+
-For rapid development, we use the Vite development server for the Vue frontend, while running the backend on port 8000 that Vite proxies backend requests to. Each server live reloads whenever its code or configuration are modified.
+## Development setup
-
+
-```fish
+For rapid development, we use the Vite development server for the Vue frontend, while running the backend on port 8000 that Vite proxies backend requests to. Each server live reloads whenever its code or configuration are modified.
-cd frontend
+
-npm install
+```fish
-npm run dev
+cd frontend
-```
+npm install
-
+npm run dev
-Concurrently, start the backend on another terminal:
+```
-
+
-```fish
+Concurrently, start the backend on another terminal:
-hatch shell
+
-pip install -e '.[dev]'
+```fish
-cista --dev -l :8000 /path/to/files
+hatch shell
-```
+pip install -e '.[dev]'
-
+cista --dev -l :8000 /path/to/files
-We use `hatch shell` for installing on a virtual environment, to not disturb the rest of the system with our hacking.
+```
-
+
-Vue is used to build files in `cista/wwwroot`, included prebuilt in the Python package. Running `hatch build` builds the frontend and creates a NodeJS-independent Python package.
+We use `hatch shell` for installing on a virtual environment, to avoid disturbing the rest of the system with our hacking.
-
+
-## System Deployment
+Vue is used to build files in `cista/wwwroot`, included prebuilt in the Python package. Running `hatch build` builds the frontend and creates a NodeJS-independent Python package.
-
+
-This setup allows easy addition of storages, each with its own domain, configuration, and files.
+## System Deployment
-
+
-Assuming a restricted user account **storage** for serving files and that cista is installed system-wide or on this account (check with `sudo -u storage -s`). Alternatively, use `pipx run cista` or `hatch run cista` as the ExecStart command.
+This setup allows easy addition of storages, each with its own domain, configuration, and files.
-
+
-Create **/etc/systemd/system/cista@.service**:
+Assuming a restricted user account `storage` for serving files and that cista is installed system-wide or on this account (check with `sudo -u storage -s`). Alternatively, use `pipx run cista` or `hatch run cista` as the ExecStart command.
-
+
-```ini
+Create `/etc/systemd/system/cista@.service`:
-[Unit]
+
-Description=Cista storage %i
+```ini
-
+[Unit]
-[Service]
+Description=Cista storage %i
-User=storage
+
-ExecStart=cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/@%i/
+[Service]
-Restart=always
+User=storage
-
+ExecStart=cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/%i
-[Install]
+Restart=always
-WantedBy=multi-user.target
+
-```
+[Install]
-
+WantedBy=multi-user.target
-This setup supports multiple storages, each under `/media/storage/<domain>` for files and `/srv/cista/<domain>/` for configuration. UNIX sockets are used instead of numeric ports for convenience.
+```
-
+
-```fish
+This setup supports multiple storages, each under `/media/storage/<domain>` for files and `/srv/cista/<domain>/` for configuration. UNIX sockets are used instead of numeric ports for convenience.
-systemctl daemon-reload
+
-systemctl enable --now cista@foo.example.com
+```fish
-systemctl enable --now cista@bar.example.com
+systemctl daemon-reload
-```
+systemctl enable --now cista@foo.example.com
-
+systemctl enable --now cista@bar.example.com
-Public exposure is easiest using the Caddy web server, but Nginx or others also work. Run the server with -l domain.example.com if you have TLS certificates in the config folder.
+```
-
+
-**/etc/caddy/Caddyfile**:
+Public exposure is easiest using the Caddy web server.
-
+
-```Caddyfile
+`/etc/caddy/Caddyfile`:
-foo.example.com, bar.example.com {
+
-    reverse_proxy unix//srv/cista/{host}/socket
+```Caddyfile
-}
+foo.example.com, bar.example.com {
-```
+    reverse_proxy unix//srv/cista/{host}/socket
+}
+```

frontend/README.md

@@ -2,11 +2,6 @@
 
 The frontend is a Single-Page App implemented with Vue 3. Development uses the Vite server together with the main Python backend, but in production the latter also serves the prebuilt frontend files.
 
-```fish
-npm install
-npm run dev
-```
-
 ## Recommended IDE Setup
 
 [VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
@@ -22,28 +17,30 @@ If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has a
     2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
 2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
 
-## Customize configuration
+## Hot-Reload for Development
 
-See [Vite Configuration Reference](https://vitejs.dev/config/).
+### Run the backend
 
-## Project Setup
+```fish
-
+hatch shell
-```sh
+cista --dev -l :8000
-npm install
 ```
 
-### Compile and Hot-Reload for Development
+### And the Vite server (in another terminal)
 
-```sh
+```fish
+cd frontend
+npm install
 npm run dev
 ```
+Browse to Vite, which will proxy API requests to port 8000. Both servers live reload changes.
 
-Note: you need to run the `cista --dev -l :8000` backend server, where Vite will forward the API requests, concurrently in another terminal.
 
 ### Type-Check, Compile and Minify for Production
 
-```sh
+This is also called by `hatch build` during Python packaging:
+
+```fish
 npm run build
 ```
 
-This is also called by `hatch build` during Python packaging.