Zipline

Zipline is a lightweight, self‑hosted file‑transfer service built to replace legacy tools like ShareX. At its core, it exposes a RESTful API and a web UI that allow users to upload any file type with optional folder hierarchy, tagging, password protection, and partial uploads. Internally the service writes metadata to a PostgreSQL database while persisting file blobs on the local filesystem or any mounted volume, making it trivial to scale storage independently of compute. The application is written in TypeScript and runs on Node.js, which gives developers a familiar ecosystem for extending or embedding Zipline into larger stacks.

Architecture

• Runtime: Node.js 20+ running a TypeScript codebase compiled to JavaScript.
• Framework: Express‑like router with custom middleware for authentication, rate limiting, and file streaming.
• Database: PostgreSQL 16 is the sole data store; all upload metadata, user accounts, OAuth clients, and webhook configurations are stored in relational tables.
• Storage: Files are written to a local directory (/zipline/uploads by default) which can be mapped to any persistent volume. The DATASOURCE_LOCAL_DIRECTORY env var allows arbitrary paths, making it compatible with cloud block storage or network filesystems.
• Containerization: Official Docker image (ghcr.io/diced/zipline) is multi‑stage, producing a slim Alpine base. Docker Compose files are provided out of the box, and health‑checks ensure both database and API services are ready before traffic is accepted.

Core Capabilities

• API: CRUD for uploads, folders, tags; supports multipart/form‑data and resumable uploads via the Content-Range header.
• Webhooks: HTTP and Discord webhooks fire on upload events; payloads include metadata, file URLs, and optional thumbnails.
• OAuth2 & 2FA: Full OAuth2 server implementation (client credentials, authorization code) plus TOTP and WebAuthn passkeys for MFA.
• Security: Password‑protected uploads, custom per‑upload encryption keys, and a global CORE_SECRET that signs all internal tokens.
• Extras: URL shortening, custom themes (CSS/JS injection), PWA support for offline uploads, and an admin UI with quota enforcement.

Deployment & Infrastructure

Zipline’s Docker image is production‑ready; it supports environment variables for all configuration, making it easy to inject secrets via Docker secrets or Kubernetes ConfigMaps. For scaling, the stateless API can be replicated behind a load balancer while the storage volume is shared via NFS or cloud‑managed block storage. PostgreSQL can be run in HA mode (Patroni, Patroni‑Docker) or as a managed service; Zipline only requires a connection string. Because uploads are streamed directly to disk, the application can handle large files (gigabytes) without loading them into memory.

Integration & Extensibility

Developers can hook into Zipline’s event system by registering custom webhooks or writing plugins that expose additional REST endpoints. The source code is open and modular: the src/services directory contains pluggable adapters for storage (S3, GCS, MinIO) that can be swapped by overriding environment variables. The API documentation is auto‑generated via OpenAPI, enabling SDK generation in any language. Moreover, the UI can be customized by dropping CSS/JS into the /themes volume; this allows brand‑specific styling without touching the core code.

Developer Experience

Zipline ships with comprehensive documentation (https://zipline.diced.sh) that covers setup, API usage, and advanced configuration. The community is active on Discord, providing quick support for deployment questions. Configuration is declarative and minimal: a single DATABASE_URL, optional OAuth secrets, and the storage path. Error handling is verbose; logs include structured JSON for easy ingestion into ELK or Loki stacks.

Use Cases

• Internal File Sharing: Teams can deploy Zipline behind a corporate VPN to share logs, screenshots, or build artifacts securely.
• CI/CD Artifacts: CI pipelines can POST to the /api/upload endpoint, trigger Discord notifications, and expose URLs via a custom domain.
• Developer Tooling: Integrate Zipline with IDE extensions or command‑line tools to upload debug data directly from the editor.
• Event Logging: Capture screenshots or recordings during automated UI tests and publish them to a public URL with password protection.

Advantages

Zipline offers a lightweight, fully self‑hosted alternative to cloud storage services while retaining rich features like partial uploads and webhook integrations. Its TypeScript codebase makes it approachable for JavaScript/Node developers, and the PostgreSQL schema is straightforward enough to extend with custom tables. Licensing is permissive (MIT), so there are no cost or vendor‑lock‑in concerns. Performance-wise, streaming uploads directly to disk avoids memory spikes, and the stateless API can be horizontally scaled with minimal overhead.