LeoVasanko
7b1c6f6772
Production symptom: previews of all types (pdf/pyvips/onlyoffice) start hitting the 10s timeout and never recover until server restart, while the rest of the server stays healthy. Root cause (reproduced on Python 3.12): workers were spawned with stderr=PIPE that nothing drained after startup. Once the OS pipe buffer filled from accumulated worker tracebacks and library warnings, asyncio flow control stopped the parent reading it and the worker blocked forever mid-request on a stderr write. The 10s timeout then fired, but _replace_worker hung forever in proc.wait() even after kill() — the flow-control-paused pipe transport never sees EOF — permanently wedging one dispatcher per stuck worker. Once all dispatchers were stuck, every preview request timed out. Restart cleared it. Fixes: - Spawn workers with inherited stderr (stderr=None) so worker diagnostics go straight to the server log and no undrained pipe can exist. - Bound proc.wait() in worker kill() with a 5s grace timeout so a wedged transport can never hang a dispatcher; log the worker pid instead. - Guard the dispatch loop with an outer exception handler so a dispatcher can never die silently and shrink pool capacity. - Retry failed worker replacement spawns with 1s-30s backoff instead of silently shrinking the pool. - Fix latent crash: except-tuple referenced msgspec.json.DecodeError, which does not exist in the installed msgspec; any protocol failure would itself raise AttributeError. Use msgspec.DecodeError. - Worker: redirect Python-level sys.stdout to stderr in persistent mode and keep the raw buffer solely for the binary protocol, so a library print() can never corrupt the command channel again (cf. the pymupdf deprecation warning that crashed workers at startup). - Worker: close the pymupdf document explicitly in process_pdf. - Log worker pid on timeout/protocol/checksum failures, and log failed kills and replacement retries, for future production diagnostics. Add tests/test_preview_pool.py with an end-to-end regression recreating the wedged-worker setup (piped, undrained stderr) plus kill-grace, respawn-retry and dispatcher-survival tests.
Cista Web Storage
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.
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 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.
Experience Cista by visiting Cista Demo for a test run and perhaps upload something...
Getting Started
Running the Server
We recommend using UV to directly run Cista:
Try it out locally at http://localhost:8000 (serves the current directory):
uvx cista
Create an account: (otherwise the server is public for all)
uvx cista --user yourname --privileged
Serve your files at http://localhost:8000:
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.
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.
Authentication
Cista supports two authentication modes, each supporting ordinary and privileged users. Either one can be combined with the public mode.
Public Mode
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.
Built-in Password Authentication (default)
User accounts are managed directly by Cista. Create users with the --user flag:
uvx cista --user admin --privileged # Create admin user
uvx cista --user guest # Create regular user
Privileged users can manage other users and change settings via the Admin Settings menu.
Passkey Authentication and SSO
For centralized authentication, Cista can integrate with Paskia SSO server. This allows user account and permission management at the corporate level, without bothering Cista with it.
Set the PASKIA_BACKEND_URL environment variable:
PASKIA_BACKEND_URL=http://localhost:4401 uvx cista
Run the Paskia backend on the same machine (to use that default URL):
uvx paskia
In Paskia mode:
- All
/auth/*requests are proxied to the Paskia backend - Cista backend verifies access by
/auth/api/validateendpoint and shows a login dialog if needed - Users with
cista:loginpermission can access files - Users with
cista:adminpermission get privileged access (Admin Settings)
WebDAV Access
Cista supports WebDAV, so you can mount it as a network drive or browse it directly from your operating system's file manager.
Connect to https://cista.example.com/files/.
Authentication
- Standard users: Use your username and password with Basic auth.
- API tokens: For scripts, backup tools, or when your client requires NTLM (e.g. Windows File Explorer), create a token in the web interface via 🔑 API Tokens. Authenticate with username
tokenand the token secret as the password.
Supported clients
| Client | Setup |
|---|---|
| Windows File Explorer | Map Network Drive → https://cista.example.com/files/ (or Add a network location). Windows may try NTLM first; API tokens are recommended. |
| macOS Finder | Go → Connect to Server (⌘K) → https://cista.example.com/files/ |
| Linux (GNOME/KDE) | Enter davs://cista.example.com/files/ or webdavs://cista.example.com/files/ in the location bar |
| Android — Solid Explorer | Tap + → New Cloud Connection → WebDAV → enter https://cista.example.com/files/ and your credentials. |
| Android — CX File Explorer | Open the Network tab → New location → WebDAV → enter https://cista.example.com/files/ and your credentials. |
| Cyberduck, WinSCP, rclone | Standard WebDAV profile with Basic auth |
Note on Windows NTLM: Windows WebDAV clients often require NTLM authentication, which is incompatible with Cista's Argon2 password hashes. API tokens solve this — Cista uses the token secret as the NTLM password.
Internet Access
Most admins find the Caddy 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:
cista.example.com {
reverse_proxy :8000
}
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
System Deployment
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 javascript runtimes.
Create (edit) a systemd unit:
sudo systemctl edit --force --full cista@.service
Paste the following:
[Unit]
Description=Cista storage %i
[Service]
User=storage
ExecStart=uvx cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/%i
Restart=always
#Environment=PASKIA_BACKEND_URL=http://localhost:4401
[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.
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.
/etc/caddy/Caddyfile:
foo.example.com, bar.example.com {
reverse_proxy unix//srv/cista/{host}/socket
}
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.
Make sure you have git, uv and bun (or npm) installed.
Backend (Python) – setup and run:
git clone https://git.zi.fi/Vasanko/cista-storage.git
cd cista-storage
uv sync --dev
uv run cista --dev -l :8000 /path/to/files
Frontend (Vue/Vite) – run the dev server in another terminal:
cd frontend
bun install
bun run dev
Building the package for release (frontend + Python wheel/sdist):
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.