Daniel Legt
33d26804a0
All checks were successful
Build and Publish Docker Image / deploy (push) Successful in 1m38s
- Add a multi-stage Dockerfile for building and running the Go backend - Add .dockerignore to optimize the Docker build context - Create a Gitea Actions workflow to build and publish Docker images on tag push - Register a new `/health` endpoint for container healthchecks - Update README.md with Docker and Podman deployment instructions - Ignore local `docker-compose.yml` in .gitignore
112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
# Warpbox.dev
|
|
|
|
This repository contains the Go backend base for `warpbox.dev`, a self-hosted transfer-first file sharing application.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
cd backend
|
|
go run ./cmd/warpbox
|
|
```
|
|
|
|
## Docker / Podman
|
|
|
|
Copy the example environment file and adjust values such as `WARPBOX_BASE_URL` and
|
|
`WARPBOX_ADMIN_TOKEN` before running the container:
|
|
|
|
Copy the example [docker-compose.example.yml](./docker-compose.example.yml) to [docker-compose.yml](./docker-compose.yml), modify as need-be
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose -f docker-compose.yml up --build
|
|
```
|
|
|
|
The compose example also works with Podman compatible compose tools. Its data volume uses
|
|
`./data:/data:Z` for SELinux relabeling, and the container overrides runtime paths to use
|
|
`/data`, `/app/static`, and `/app/templates`.
|
|
|
|
The image exposes `/health`, `/healthz`, and `/api/v1/health`. Docker and compose healthchecks
|
|
use `/health`.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
# 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.
|