warpbox-dev/README.md

Warpbox.dev

This repository contains the Go backend base for warpbox.dev, a self-hosted transfer-first file sharing application.

Run

./scripts/run/dev.sh

The default server listens on :8080.

Upload size limits are configured in megabytes through WARPBOX_MAX_UPLOAD_SIZE_MB. Fractions are supported, so 0.5Mb is 512 KiB and 1.5Mb is 1536 KiB.

Runtime data is configured with WARPBOX_DATA_DIR and defaults to ./data in the dev environment. The dev script resolves that path from the repository root.

Background jobs are enabled with WARPBOX_JOBS_ENABLED=true. Individual jobs can be toggled with WARPBOX_CLEANUP_ENABLED and WARPBOX_THUMBNAIL_ENABLED, and their schedules are configured with WARPBOX_CLEANUP_EVERY and WARPBOX_THUMBNAIL_EVERY.

The basic admin console is available at /admin. Set WARPBOX_ADMIN_TOKEN and use that value to sign in.

For one-off Go commands, run them from the backend module:

cd backend
go run ./cmd/warpbox

Layout

• backend/cmd/warpbox - main application entry point.
• backend/libs/config - environment-backed configuration.
• backend/libs/httpserver - server construction and route composition.
• backend/libs/handlers - HTTP handlers for pages, API, health, static files.
• backend/libs/jobs - background job registration and job loop definitions.
• backend/libs/middleware - request logging, recovery, security headers, gzip, request IDs.
• backend/libs/services - business logic boundaries, starting with upload limits.
• backend/libs/helpers - small reusable helpers.
• backend/libs/web - Go template renderer.
• backend/templates - server-rendered Go templates.
• backend/static/css, backend/static/js, backend/static/img, backend/static/fonts - public assets served from /static/.
• scripts/run/dev.sh - local development runner.
• scripts/env/dev.env.example - tracked development environment template.
• scripts/env/dev.env - local development environment, ignored by git.

Stage 2 Operator Tools

• /admin/login - token-based admin login.
• /admin - overview metrics: boxes, files, storage, recent uploads, protected/expired boxes.
• /admin/files - recent upload table with view and delete actions.
• Expired boxes and boxes that have reached their download limit are cleaned on startup and then every WARPBOX_CLEANUP_EVERY when WARPBOX_CLEANUP_ENABLED=true.
• Missing image/video thumbnails are generated in a background worker every WARPBOX_THUMBNAIL_EVERY when WARPBOX_THUMBNAIL_ENABLED=true.

Stage 3 Anonymous Integrations

Anonymous uploads now return a private management link at creation time. Keep that link secret: anyone with it can delete the entire upload box. The raw delete token is not stored and cannot be recovered later.

Browser uploads still show Open box and Copy URL as the primary actions, with a smaller Manage or delete this upload link in the completion panel.

Curl and custom uploaders can use the same endpoint:

# Terminal-friendly output: one plain box URL.
curl -F file=@./report.pdf http://localhost:8080/api/v1/upload

# JSON output with boxUrl, manageUrl, deleteUrl, zipUrl, and file entries.
curl -F sharex=@./screenshot.png \
  -H 'Accept: application/json' \
  http://localhost:8080/api/v1/upload

The upload endpoint accepts multipart fields named file and sharex. ShareX users can start from examples/sharex/warpbox-anonymous.sxcu; update RequestURL to match your instance URL.

Runtime Data

Warpbox keeps local runtime data under the configured data directory:

• data/files/{box_id}/@each@{file_id}.ext - uploaded file contents.
• data/files/{box_id}/@thumb@{file_id}.jpg - generated previews where available.
• data/db/warpbox.bbolt - bbolt metadata database for boxes and file records.
• data/logs/{YYYY-MM-DD}.log - JSONL logs, one event per line.

Static Asset Policy

The static handler sets long-lived immutable caching for images, video, audio, and fonts, shorter caching for CSS/JS, and gzip compression for compressible responses.