kato/WarpBox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand configuration docs for admin and BadgerDB

Browse Source 
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.
This commit is contained in:
Daniel Legt
2026-04-28 21:11:37 +03:00
parent fc3de58b5b
commit a5d6d69be0
27 changed files with 3499 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
README.md
View File

@@ -71,36 +71,66 @@ go run ./cmd run --addr :3000
## Configuration
WarpBox mostly works with defaults. These environment variables tune polling
and thumbnail generation.
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 | Minimum | What it does |
| --- | ---: | ---: | --- |
| `WARPBOX_BOX_POLL_INTERVAL_MS` | `5000` | `1000` | Browser polling interval for box/file status updates. |
| `WARPBOX_THUMBNAIL_BATCH_SIZE` | `10` | `1` | Number of pending thumbnails processed per worker pass. |
| `WARPBOX_THUMBNAIL_INTERVAL_SECONDS` | `30` | `1` | Delay between thumbnail worker passes. |
| 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:
```bash
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:
```text
data/uploads/
<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:
```text
<WARPBOX_DATA_DIR>/db/
```
```text
data/uploads/
+-- <box-id>/
@@ -108,6 +138,7 @@ data/uploads/
+-- file.txt
+-- .thumbnails/
+-- <file-id>.jpg
data/db/
```
## Project Layout
@@ -117,6 +148,8 @@ 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