transbeam/README.md

<p align="center">
    <img alt="transbeam logo: a laser warning sign in trans flag colors" height="128" src="https://git.xeno.science/xenofem/transbeam/raw/branch/main/static/images/site-icons/transbeam.svg">
</p>
<h3 align="center">transbeam</h3>
<p align="center">A low-latency file drop web app</p>

## features

- One-to-many transfer of large files
- Simple web UI for sender and receivers
- Word-based download codes that are easy to remember and communicate
- Receivers can begin downloading *immediately*, without needing to
  wait for the upload to finish
- Receivers can also download after the upload is complete and the
  sender has gone offline
- Easy to send multiple files at once - they're bundled into a zip
  file for receivers, with zero compression so extraction is quick
- Can also download individual files out of an uploaded collection
- Sanitises filenames, using sensible non-obnoxious defaults that
  should be safe across platforms
- Rudimentary password authentication for uploading files
- Fires a laser beam that turns you trans

## configuration

transbeam is configured with the following environment variables:
- `TRANSBEAM_ADMIN_PASSWORD_HASH`: Argon2 hash of a password for
  accessing the admin interface. To generate:
  ```bash
  echo -n 'Password: '; head -1 | tr -d '\n' | argon2 $(openssl rand -base64 32) -id -t 2 -m 14 -p 1 -e
  ```
  (If you're setting this in a `.env` file or in a shell, make sure to single-quote it to prevent text after `$` characters from being interpreted as variables.)
- `TRANSBEAM_COOKIE_SECRET`: Base64-encoded cryptographic random data
  for encrypting private session cookies. To generate:
  ```bash
  openssl rand -base64 64 | tr -d '\n'
  ```
- `TRANSBEAM_STORAGE_DIR`: path where uploaded files should be stored
  (default: `./storage`)
- `TRANSBEAM_STATIC_DIR`: path where the web app's static files live
  (default: `./static`)
- `TRANSBEAM_STATE_FILE`: path of a JSON file where transbeam will
  store file metadata and other persistent state (default:
  `$TRANSBEAM_STORAGE_DIR/files.json` if that's already an existing
  file (for backwards compatibility), `./transbeam.json` otherwise)
- `TRANSBEAM_BASE_URL`: base URL for this transbeam instance, without
  trailing `/`
- `TRANSBEAM_PORT`: port to listen on localhost for http requests
  (default: 8080)
- `TRANSBEAM_REVERSE_PROXY`: whether transbeam is running behind a
  reverse proxy (recommended), or directly exposed to the internet. If
  true, transbeam will only bind to localhost, and will use the
  `Forwarded` or `X-Forwarded-For` headers to determine client IP
  addresses for logs. If false, transbeam will bind on all interfaces,
  and will always log the peer IP address. (default: true)
- `TRANSBEAM_MAX_LIFETIME`: maximum number of days files can be kept
  for (default: 30)
- `TRANSBEAM_MAX_UPLOAD_SIZE`: maximum size of a fileset being
  uploaded (default: 16G). Size values can be a bare number of bytes,
  or a number with a suffix. (For example, "K" or "KB" for power-of-10
  kilobytes, "Ki" or "KiB" for kibibytes - suffixes are not
  case-sensitive.)
- `TRANSBEAM_MAX_STORAGE_SIZE`: maximum total size of all files being
  stored by transbeam (default: 64G)
- `TRANSBEAM_MIN_DISK_FREE`: minimum amount of free disk space on the
  filesystem where transbeam uploads are stored (default: 8G).
  transbeam will not accept uploads that would reduce free disk space
  lower than this value, even if they would otherwise be within the
  max upload size and max storage size.
- `TRANSBEAM_MNEMONIC_CODES`: generate memorable download codes using
  English words, rather than random alphanumeric strings (default:
  true)
- `TRANSBEAM_UPLOAD_PASSWORD`: password for uploading files. This
  isn't meant to be a hardcore security measure, just a defense
  against casual internet randos filling up your storage.  I strongly
  recommend setting up fail2ban to throttle password attempts;
  transbeam logs failed attempts along with IP addresses, in the form
  `Incorrect authentication attempt from 203.0.113.12`.
- `TRANSBEAM_CACHEBUSTER`: query string that will be appended to CSS
  and JS files, to force re-fetching of cached files when needed.
- `RUST_LOG`: log levels, for the app as a whole and/or for specific
  submodules/libraries. See
  [`env_logger`](https://docs.rs/env_logger/latest/env_logger/)'s
  documentation for details.

## running

### nix flakes

```
nix run git+https://git.xeno.science/xenofem/transbeam?ref=main
```

(The Nix package is wrapped with `TRANSBEAM_STATIC_DIR` set
automatically to the correct Nix store path, so it'll serve the static
files properly no matter what directory you run it
from. `TRANSBEAM_CACHEBUSTER` is set automatically to a hash of the
static files' store path, so it will change whenever the static files
change.)

### non-nix

```
git clone https://git.xeno.science/xenofem/transbeam
cd transbeam
cargo run --release
```

## user reviews

*"transbeam is the greatest invention of all time!"*

*"transbeam cured my depression!"*

*"transbeam punched me in the face once. It was awesome."*