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 |
| pkg-config | Linking system libraries | Install via your system package manager |
| cmake | JPEG XL build (jpegxl-sys) | Install via your system package manager |
| nasm | AVIF encoding (rav1e) | Install via your system package manager |
| libheif | HEIC input support | Install via your system package manager |
| pdfium | PDF input support | Optional - download from pdfium-binaries |
| ffmpeg | Video thumbnail extraction | Optional - must be on PATH or set via PP_FFMPEG_PATH |
Rust, pkg-config, cmake, nasm, and libheif are required at build time. libheif, pdfium, and ffmpeg are optional at runtime - if absent, HEIC, PDF, and video support will be unavailable. pdfium and ffmpeg are optional at both build time and runtime.
Installing build dependencies
# Debian/Ubuntu
sudo apt install build-essential pkg-config cmake nasm libheif-dev ffmpeg
# macOS (Homebrew)
brew install pkgconf cmake nasm libheif ffmpeg
# Arch Linux
sudo pacman -S pkgconf cmake nasm libheif ffmpeg
Windows - requires Visual Studio Build Tools and vcpkg. Run in a Developer PowerShell:
choco install pkgconfiglite -y
vcpkg install dav1d libjxl libheif --triplet x64-windows-static-md
Then set these environment variables before building:
$env:VCPKG_ROOT = "C:\vcpkg"
$env:PKG_CONFIG_PATH = "C:\vcpkg\installed\x64-windows-static-md\lib\pkgconfig"
Installing pdfium
pdfium does not have official package manager distributions. Download the prebuilt binary for your platform from the pdfium-binaries project and place the shared library where the linker can find it.
# Example for Linux x86_64
curl -L https://github.com/bblanchon/pdfium-binaries/releases/latest/download/pdfium-linux-x64.tgz | tar xz
sudo cp lib/libpdfium.so /usr/local/lib/
sudo ldconfig
# Example for macOS (Apple Silicon)
curl -L https://github.com/bblanchon/pdfium-binaries/releases/latest/download/pdfium-mac-arm64.tgz | tar xz
sudo cp lib/libpdfium.dylib /usr/local/lib/
# Example for Windows x86_64
curl -L https://github.com/bblanchon/pdfium-binaries/releases/latest/download/pdfium-win-x64.tgz | tar xz
copy bin\pdfium.dll C:\Windows\System32\
Set the PDFIUM_DYNAMIC_LIB_PATH environment variable to the directory containing the shared library if it is not in a standard system path.
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
./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 |
|---|---|---|
| PP_PORT | --port | Server listen port |
| PP_APP_ENV | --env | Environment (development or production) |
| PP_HMAC_KEY | --hmac-key | HMAC-SHA256 signing key |
| PP_ALLOWED_HOSTS | --allowed-hosts | Comma-separated allowed upstream hostnames |
| PP_CACHE_DIR | --cache-dir | L2 disk cache directory |
| PP_FFMPEG_PATH | --ffmpeg-path | Path to the ffmpeg binary |
For the full list of flags, run:
./target/release/previewproxy serve --help
In development, environment variables are convenient. In production or scripted deployments, CLI flags make the configuration explicit and easy to audit.