ddidderr
996ad5c4c8
Add clap-powered --bind, --static-dir, and --data-dir flags for human-run server configuration. The merge order is now explicit: command-line arguments win over UPL_* environment variables, which still fall back to the existing repository-local defaults. Document the new flags and allow just run to forward arguments to cargo so the help text can be checked through the normal task runner. Test Plan: - just check - cargo run -- --help Refs: none
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# upl
|
|
|
|
`upl` is a small personal resumable upload service. The intended deployment is:
|
|
|
|
```text
|
|
browser -> nginx -> upl Rust server -> local filesystem
|
|
```
|
|
|
|
The first implementation milestone provides the Rust server shell and static
|
|
browser UI. Upload metadata, chunk persistence, resume state, and completion
|
|
assembly are tracked in `PLAN.md` and will be added in later coherent slices.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
upl
|
|
Rust server
|
|
src/main.rs binary entrypoint and listener setup
|
|
src/app.rs Axum router, shared state, static file service
|
|
src/api.rs HTTP handlers and API error responses
|
|
src/model.rs JSON request, response, and metadata shapes
|
|
src/storage.rs local filesystem layout, chunks, and assembly
|
|
src/lib.rs library surface used by integration tests
|
|
Browser UI
|
|
static/index.html upload tool markup
|
|
static/styles.css responsive tool styling
|
|
static/app.js upload scheduler, retries, and browser resume state
|
|
Deployment
|
|
deploy/nginx/ nginx reverse proxy example
|
|
scripts/ reusable local smoke tests
|
|
Validation
|
|
tests/ integration tests for server behavior
|
|
TESTS.md reusable manual and automated test checklist
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- `--bind` sets the listen address. It overrides `UPL_BIND` and defaults to
|
|
`127.0.0.1:3000`.
|
|
- `--static-dir` sets the static asset directory. It overrides `UPL_STATIC_DIR`
|
|
and defaults to `static/` inside this repository.
|
|
- `--data-dir` sets the upload data directory. It overrides `UPL_DATA_DIR` and
|
|
defaults to `data/` inside this repository.
|
|
- `upl --help` prints the full argument help text.
|
|
- The server accepts request bodies up to 64 MiB, which leaves room for the
|
|
planned 16 MiB upload chunks and matches the nginx example in `PLAN.md`.
|
|
|
|
## Common Commands
|
|
|
|
Use the `justfile` for routine tasks:
|
|
|
|
```sh
|
|
just check
|
|
just run
|
|
```
|
|
|
|
`just check` also syntax-checks the static browser JavaScript with `node`.
|
|
|
|
## nginx
|
|
|
|
Run `upl` on localhost and put nginx in front of it for TLS and access control:
|
|
|
|
```sh
|
|
UPL_BIND=127.0.0.1:3000 UPL_DATA_DIR=/srv/upl/data upl
|
|
```
|
|
|
|
Use `deploy/nginx/upl.conf.example` as the starting point for the nginx site.
|
|
Before exposing the service, replace the certificate paths and add a protection
|
|
layer such as HTTP basic auth, an IP allowlist, or VPN-only access.
|
|
|
|
For a local Docker-based reverse-proxy smoke test:
|
|
|
|
```sh
|
|
just nginx-smoke
|
|
```
|
|
|
|
The smoke test binds the Rust server to `0.0.0.0` so the nginx container can
|
|
reach it through Docker's host gateway. The production nginx example keeps the
|
|
server bound to localhost.
|