Files

Daniel Legt a5d6d69be0 docs: expand configuration docs for admin and BadgerDB

Update README to explain startup config precedence (defaults/env/admin overrides),
document admin/bootstrap and feature toggles, and clarify storage locations under
WARPBOX_DATA_DIR including BadgerDB metadata. Also refresh project layout to
include new config and metastore packages.docs: expand configuration docs for admin and BadgerDB

Update README to explain startup config precedence (defaults/env/admin overrides),
document admin/bootstrap and feature toggles, and clarify storage locations under
WARPBOX_DATA_DIR including BadgerDB metadata. Also refresh project layout to
include new config and metastore packages.

2026-04-28 21:11:37 +03:00

5.1 KiB

Raw Blame History

WarpBox

WarpBox is a small, self-hosted file sharing app with temporary upload boxes, simple download links, optional passwords, ZIP downloads, and a very deliberate retro desktop mood.

It is meant to feel quick: pick files, choose how long the box should live, upload, and share the link.

flowchart LR
    A[Choose files] --> B[Create box]
    B --> C[Upload to box]
    C --> D[Share link]
    D --> E[Download files or ZIP]
    E --> F[Expire or one-time cleanup]

Features

Multi-file uploads through a browser UI.
Temporary boxes with configurable retention choices.
Optional password protection per box.
Individual file downloads or a single ZIP download.
One-time download mode for ZIP-only handoff.
Background thumbnails for image files.
Plain filesystem storage, with JSON manifests next to uploaded files.
No database required.

How It Fits Together

flowchart TB
    Browser[Browser UI]
    Server[Go HTTP server]
    Manifest[Box manifest JSON]
    Files[Uploaded files]
    Thumbs[Generated thumbnails]

    Browser -->|create box / upload / poll| Server
    Server --> Manifest
    Server --> Files
    Server --> Thumbs
    Thumbs -->|preview URLs| Browser
    Files -->|downloads / ZIP| Browser

Quick Start

Requirements:

Go 1.22 or newer.

Run the app:

go run ./cmd run

Then open:

http://localhost:8080

To listen somewhere else:

go run ./cmd run --addr :3000

Configuration

WarpBox loads defaults, applies environment variables at startup, then applies safe admin settings overrides from BadgerDB. Hard storage and global limit settings remain environment controlled.

Variable	Default	What it does
`WARPBOX_DATA_DIR`	`./data`	Root directory for uploads and metadata.
`WARPBOX_ADMIN_PASSWORD`	empty	Bootstraps the first admin when set.
`WARPBOX_ADMIN_USERNAME`	`admin`	Bootstrap admin username.
`WARPBOX_ADMIN_EMAIL`	empty	Bootstrap admin email.
`WARPBOX_ADMIN_ENABLED`	`auto`	Admin login mode: `auto`, `true`, or `false`.
`WARPBOX_ALLOW_ADMIN_SETTINGS_OVERRIDE`	`true`	Allows safe settings overrides from `/admin/settings`.
`WARPBOX_ADMIN_COOKIE_SECURE`	`false`	Sets the Secure flag on admin session cookies.
`WARPBOX_GUEST_UPLOADS_ENABLED`	`true`	Enables guest uploads.
`WARPBOX_API_ENABLED`	`true`	Enables JSON/upload endpoints used by the UI.
`WARPBOX_ZIP_DOWNLOADS_ENABLED`	`true`	Enables ZIP downloads.
`WARPBOX_ONE_TIME_DOWNLOADS_ENABLED`	`true`	Enables one-time download boxes.
`WARPBOX_RENEW_ON_ACCESS_ENABLED`	`false`	Renews expiring boxes on access.
`WARPBOX_RENEW_ON_DOWNLOAD_ENABLED`	`false`	Renews expiring boxes on download.
`WARPBOX_DEFAULT_GUEST_EXPIRY_SECONDS`	`10`	Default guest retention.
`WARPBOX_MAX_GUEST_EXPIRY_SECONDS`	`172800`	Max guest retention shown/accepted.
`WARPBOX_GLOBAL_MAX_FILE_SIZE_BYTES`	`0`	Hard per-file cap; `0` means unlimited.
`WARPBOX_GLOBAL_MAX_BOX_SIZE_BYTES`	`0`	Hard per-box cap; `0` means unlimited.
`WARPBOX_DEFAULT_USER_MAX_FILE_SIZE_BYTES`	`0`	Default user file cap.
`WARPBOX_DEFAULT_USER_MAX_BOX_SIZE_BYTES`	`0`	Default user box cap.
`WARPBOX_SESSION_TTL_SECONDS`	`86400`	Admin session lifetime.
`WARPBOX_BOX_POLL_INTERVAL_MS`	`5000`	Browser polling interval for box/file status updates.
`WARPBOX_THUMBNAIL_BATCH_SIZE`	`10`	Number of pending thumbnails processed per worker pass.
`WARPBOX_THUMBNAIL_INTERVAL_SECONDS`	`30`	Delay between thumbnail worker passes.

Example:

WARPBOX_ADMIN_PASSWORD='change-me' \
WARPBOX_BOX_POLL_INTERVAL_MS=2000 \
WARPBOX_THUMBNAIL_BATCH_SIZE=20 \
WARPBOX_THUMBNAIL_INTERVAL_SECONDS=10 \
go run ./cmd run --addr :8080

Open /admin/login after startup to sign in with the bootstrap admin.

Storage

Uploads are stored locally under:

<WARPBOX_DATA_DIR>/uploads/

Each box gets its own directory containing the uploaded files and a .warpbox.json manifest. Image thumbnails are stored inside a box-local .thumbnails directory.

Persistent app metadata lives in BadgerDB under:

<WARPBOX_DATA_DIR>/db/

data/uploads/
+-- <box-id>/
    +-- .warpbox.json
    +-- file.txt
    +-- .thumbnails/
        +-- <file-id>.jpg
data/db/

Project Layout

cmd/            CLI entrypoint
lib/server/     HTTP handlers and server setup
lib/routing/    Route registration
lib/boxstore/   Box storage, manifests, downloads, thumbnails
lib/config/     Typed environment and runtime settings config
lib/metastore/  BadgerDB metadata store for users, tags, settings, sessions
lib/helpers/    Small shared helpers
lib/models/     Shared request/response models
templates/      Server-rendered HTML
static/         CSS, JavaScript, fonts, icons, and images
docs/           Project documentation

Notes

WarpBox is intentionally simple. It uses the local filesystem as its backing store, relies on generated box IDs for share links, and keeps most behavior easy to follow from the Go handlers and the small browser scripts.

For a short implementation overview, see docs/tech.md.

5.1 KiB Raw Blame History