Build from Source
If you prefer to build PreviewProxy yourself rather than use the Docker image, follow these steps.
Prerequisites
| Dependency | Required for | Notes |
|---|---|---|
| Rust (stable) | Core build | Install via rustup |
| libheif | HEIC input support | Optional; install via your system package manager |
| ffmpeg | Video thumbnail extraction | Optional; must be available on PATH or configured via FFMPEG_PATH |
| pdfium | PDF input support | Optional; download from the pdfium-binaries project |
info
If you do not need HEIC, video, or PDF support, you can build without those dependencies. The relevant features will simply be unavailable at runtime.
Installing libheif
# Debian/Ubuntu
sudo apt install libheif-dev
# macOS (Homebrew)
brew install libheif
# Arch Linux
sudo pacman -S libheif
Installing ffmpeg
# Debian/Ubuntu
sudo apt install ffmpeg
# macOS (Homebrew)
brew install ffmpeg
Build
Clone the repository and build in release mode:
git clone https://github.com/ViGrise/previewproxy.git
cd previewproxy
cargo build --release
The compiled binary will be placed at:
./target/release/previewproxy
Run
PORT=8080 APP_ENV=development ./target/release/previewproxy serve
PreviewProxy will start and listen on port 8080.
CLI Flags
Every configuration option can be provided either as an environment variable or as a CLI flag. Flags take precedence over environment variables.
| Environment Variable | CLI Flag | Description |
|---|---|---|
| PORT | --port | Server listen port |
| APP_ENV | --env | Environment (development or production) |
| HMAC_KEY | --hmac-key | HMAC-SHA256 signing key |
| ALLOWED_HOSTS | --allowed-hosts | Comma-separated allowed upstream hostnames |
| CACHE_DIR | --cache-dir | L2 disk cache directory |
| FFMPEG_PATH | --ffmpeg-path | Path to the ffmpeg binary |
For the full list of flags, run:
./target/release/previewproxy serve --help
tip
In development, environment variables are convenient. In production or scripted deployments, CLI flags make the configuration explicit and easy to audit.