Vasanko/cista-storage
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README

Browse Source
This commit is contained in:
LeoVasanko
2026-02-04 19:23:48 +00:00
parent c7727c72d9
commit 113bc56351
1 changed files with 170 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+170 -156
View File
@@ -1,156 +1,170 @@
# Cista Web Storage # Cista Web Storage
<img src="https://git.zi.fi/Vasanko/cista-storage/raw/branch/main/docs/cista.webp" align=left 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**.
**Built-in document and media previews** let you quickly view files without downloading them. Cista shows PDF and other documents, video and image thumbnails, with **HDR10 support** video previews and image formats, including HEIC and AVIF. It also has a player for music and video files. **Built-in document and media previews** let you quickly view files without downloading them. Cista shows PDF and other documents, video and image thumbnails, with **HDR10 support** video previews and image formats, including HEIC and AVIF. It also has a player for music and video files.
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 was not being developed at the time. Now they have picked up pace too, feel free to try both and compare.
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
### Running the Server ### Running the Server
We recommend using [UV](https://docs.astral.sh/uv/getting-started/installation/) to directly run Cista: We recommend using [UV](https://docs.astral.sh/uv/getting-started/installation/) to directly run Cista:
Create an account: (otherwise the server is public for all) Create an account: (otherwise the server is public for all)
```fish ```fish
uvx cista --user yourname --privileged uvx cista --user yourname --privileged
``` ```
Serve your files at http://localhost:8000: Serve your files at http://localhost:8000:
```fish ```fish
uvx cista -l :8000 /path/to/files uvx cista -l :8000 /path/to/files
``` ```
Alternatively, you can install with `pip` or `uv pip`. This enables using the `cista` command directly without `uvx` or `uv run`. Alternatively, you can install with `pip` or `uv pip`. This enables using the `cista` command directly without `uvx` or `uv run`.
```fish ```fish
pip install cista --break-system-packages pip install cista --break-system-packages
``` ```
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.
## Authentication ## Authentication
Cista supports three authentication modes: Cista supports two authenticatioon mode, each of which supporting ordinary and privileged users. Either one can be combined with the public mode.
### Built-in Authentication (default) ### Public Mode
User accounts are managed directly by Cista. Create users with the `--user` flag: In public mode, anyone can read, send and even delete files without without logging in. Users entering the service won't be asked to authenticate. Privileged users can still log in via the menu to access admin settings, from where the public mode can be toggled on or off.
```fish ### Built-in Password Authentication (default)
uvx cista --user admin --privileged # Create admin user
uvx cista --user guest # Create regular user User accounts are managed directly by Cista. Create users with the `--user` flag:
```
```fish
Privileged users can manage other users and change settings via the Admin Settings menu. uvx cista --user admin --privileged # Create admin user
uvx cista --user guest # Create regular user
### Public Mode ```
In public mode, anyone can read, send and even delete files without without logging in. Privileged users can still log in via the menu to access admin settings, from where the public mode can be toggled on or off. Privileged users can manage other users and change settings via the Admin Settings menu.
### Paskia SSO Authentication ### Passkey Authentication and SSO
For centralized authentication, Cista can integrate with [Paskia](https://git.zi.fi/LeoVasanko/paskia) SSO server. Set the `PASKIA_BACKEND_URL` environment variable: For centralized authentication, Cista can integrate with [Paskia](https://git.zi.fi/LeoVasanko/paskia) SSO server. This allows user account and permission management at the corporate level, without bothering Cista with it.
```fish Set the `PASKIA_BACKEND_URL` environment variable:
PASKIA_BACKEND_URL=http://localhost:4401 uvx cista
``` ```fish
PASKIA_BACKEND_URL=http://localhost:4401 uvx cista
In Paskia mode: ```
- All `/auth/*` requests are proxied to the Paskia backend
- Users with `cista:login` permission can access files Run the Paskia backend on the same machine (to use that default URL):
- Users with `cista:admin` permission get privileged access (Admin Settings) ```fish
- Public mode works with Paskia: unauthenticated users can browse, while the menu has option to login uvx paskia
```
### Internet Access
In Paskia mode:
Most admins 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. - All `/auth/*` requests are proxied to the Paskia backend
- Cista backend verifies access by `/auth/api/validate` endpoint and shows a login dialog if needed
`/etc/caddy/Caddyfile`: - Users with `cista:login` permission can access files
- Users with `cista:admin` permission get privileged access (Admin Settings)
```Caddyfile
cista.example.com { ### Internet Access
reverse_proxy :8000
} Most admins 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.
```
`/etc/caddy/Caddyfile`:
Nxing or other proxy may be similarly used, or alternatively you can place cert and key in cista config dir and run `cista -l cista.example.com`
```Caddyfile
## System Deployment cista.example.com {
reverse_proxy :8000
This setup allows easy addition of storages, each with its own domain, configuration, and files. }
```
Assuming a restricted user account `storage` for serving files and that UV is installed system-wide or on this account. Only UV is required: this does not use git or bun/npm.
Nxing or other proxy may be similarly used, or alternatively you can place cert and key in cista config dir and run `cista -l cista.example.com`
Create `/etc/systemd/system/cista@.service`:
## System Deployment
```ini
[Unit] This setup allows easy addition of storages, each with its own domain, configuration, and files.
Description=Cista storage %i
Assuming a restricted user account `storage` for serving files and that UV is installed system-wide or on this account. Only UV is required: this does not use git or javascript runtimes.
[Service]
User=storage Create (edit) a systemd unit:
ExecStart=uvx cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/%i
Restart=always ```fish
sudo systemctl edit --force --full cista@.service
[Install] ```
WantedBy=multi-user.target
``` Paste the following:
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. ```ini
[Unit]
```fish Description=Cista storage %i
systemctl daemon-reload
systemctl enable --now cista@foo.example.com [Service]
systemctl enable --now cista@bar.example.com User=storage
``` ExecStart=uvx cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/%i
Restart=always
Public exposure is easiest using the Caddy web server. #Environment=PASKIA_BACKEND_URL=http://localhost:4401
`/etc/caddy/Caddyfile`: [Install]
WantedBy=multi-user.target
```Caddyfile ```
foo.example.com, bar.example.com {
reverse_proxy unix//srv/cista/{host}/socket 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
systemctl daemon-reload
## Development setup systemctl enable --now cista@foo.example.com
systemctl enable --now cista@bar.example.com
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. ```
Make sure you have git, uv and bun (or npm) installed. Public exposure is easiest using the Caddy web server.
Backend (Python) – setup and run: `/etc/caddy/Caddyfile`:
```fish ```Caddyfile
git clone https://git.zi.fi/Vasanko/cista-storage.git foo.example.com, bar.example.com {
cd cista-storage reverse_proxy unix//srv/cista/{host}/socket
uv sync --dev }
uv run cista --dev -l :8000 /path/to/files ```
```
## Development setup
Frontend (Vue/Vite) – run the dev server in another terminal:
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.
```fish
cd frontend Make sure you have git, uv and bun (or npm) installed.
bun install
bun run dev Backend (Python) – setup and run:
```
```fish
Building the package for release (frontend + Python wheel/sdist): git clone https://git.zi.fi/Vasanko/cista-storage.git
cd cista-storage
```fish uv sync --dev
uv build uv run cista --dev -l :8000 /path/to/files
``` ```
Vue is used to build files in `cista/wwwroot`, included prebuilt in the Python package. `uv build` runs the project build hooks to bundle the frontend and produce a NodeJS-independent Python package. Frontend (Vue/Vite) – run the dev server in another terminal:
```fish
cd frontend
bun install
bun run dev
```
Building the package for release (frontend + Python wheel/sdist):
```fish
uv build
```
Vue is used to build files in `cista/frontend-build`, included prebuilt in the Python package. `uv build` runs the project build hooks to bundle the frontend and produce a NodeJS-independent Python package.