Expand description
§Gulfstream
Gulfstream is a configurable Rust video API and responsive management application for account management, direct uploads, protected URL imports, durable FFmpeg processing, adaptive HLS playback, and persisted analytics.
- Repository: https://github.com/gulfstream-rs/gulfstream
- Documentation: https://gulfstream-rs.github.io/gulfstream/
- OpenAPI: served by each running instance at its configured OpenAPI route
- Rustdoc: https://gulfstream-rs.github.io/gulfstream/rustdoc/gulfstream/
- Changelog: CHANGELOG.md
§Features
- Email/password account registration and login
- Configurable open, administrator-token, or disabled registration
- HttpOnly browser sessions with CSRF protection, absolute expiry, idle expiry, and session limits
- Revocable bearer API keys stored as Argon2id verifiers
- Streaming multipart uploads with size, content-type, filename, checksum, and quota enforcement
- Protected remote imports with DNS/redirect revalidation, SSRF controls, bounded timeouts, byte limits, and optional proxy use
- Durable SQLite-backed jobs with leasing, renewal, retries, cancellation, and publication fencing
- Real FFprobe inspection and FFmpeg adaptive HLS conversion
- Configurable renditions, codecs, bitrates, GOP alignment, segment duration, fMP4 or MPEG-TS output, retention, and extra arguments
- Public, unlisted, and private media with short-lived signed playback authorization
- HTML5 playback, HLS assets, original-source streaming, and HTTP byte ranges
- Embeddable player (
/embed/{id}) with autoplay, loop, and start options, apostMessageAPI, and oEmbed discovery - Playback protection: per-client request, session, and concurrency limits, bandwidth pacing, a global egress cap, and hotlink blocking
- Persisted views, qualified (monetizable) views, unique viewers, play starts, completed views, watch time, and bytes actually emitted
- Country analytics from a CDN header or a free MaxMind DB country database (DB-IP Lite, GeoLite2, IPinfo Lite)
- Configurable analytics retention and reporting windows
- Responsive, accessible, dependency-free management dashboard for every operator workflow
- Runtime-resolved OpenAPI 3.1 contract
- Docker, Docker Compose, GitHub Actions, crates.io release automation, VitePress documentation, Rustdoc, and Dependabot
§Quick start
Docker Compose is the fastest supported launch path. FFmpeg and FFprobe are included in the runtime image.
The container’s bundled media tools and runtime retain their own licenses as documented in THIRD_PARTY_NOTICES.md.
git clone https://github.com/gulfstream-rs/gulfstream.git
cd gulfstream
cp config/gulfstream.example.toml config/gulfstream.toml
{
printf '%s\n' 'GULFSTREAM_CONFIG=config/gulfstream.toml'
./scripts/generate-secrets.sh
} > .env
docker compose up --buildOpen:
- Web application:
http://localhost:8080/app - OpenAPI:
http://localhost:8080/openapi.yaml - Readiness:
http://localhost:8080/health/ready
The example configuration uses administrator-token registration. Enter the GULFSTREAM_ADMIN_TOKEN value from .env on the registration page.
For unrestricted registration, set:
[registration]
mode = "open"For complete installation, configuration, production, and API instructions, read the documentation.
§Run from source
Requirements:
- Rust 1.97.1
- FFmpeg and FFprobe
- a C/C++ build environment required by the selected Rust target
cp config/gulfstream.example.toml config/gulfstream.toml
./scripts/generate-secrets.sh > .env
set -a
. ./.env
set +a
cargo run --release -- --config config/gulfstream.tomlGULFSTREAM_CONFIG=config/gulfstream.toml cargo run --release is equivalent.
§First API request
Register and sign in through the web interface, create an API key under Account, and copy it immediately. The plaintext key is not stored and cannot be shown again.
export GULFSTREAM_API_KEY='gfs_…'
curl \
-H "Authorization: Bearer $GULFSTREAM_API_KEY" \
http://localhost:8080/api/dashboardUpload one video:
curl -X POST http://localhost:8080/api/media \
-H "Authorization: Bearer $GULFSTREAM_API_KEY" \
-F 'file=@video.mp4;type=video/mp4' \
-F 'title=Example video' \
-F 'description=Uploaded through the API' \
-F 'visibility=private'The source is durably stored before a transcode job is queued. Poll the returned media resource or processing jobs until the media status becomes ready or failed.
§Web application
The web application uses no frontend framework or separate backend. A server-rendered shell loads modular CSS and ES modules that call the same public API used by external clients. Available pages cover:
- registration and login
- dashboard metrics, storage usage, status breakdowns, and automatic refresh
- drag-and-drop upload with progress and protected URL import
- responsive media search, filters, configurable pagination, details, editing, playback, retry, and safe deletion
- durable processing jobs with status filters and automatic refresh
- analytics totals, completion metrics, and daily charts
- account profile, one-time API-key display/copy, revocation, and logout
Routes, branding, external links, feature flags, limits, registration policy, and CSRF header names are injected from validated server configuration.
§Configuration
Copy config/gulfstream.example.toml and modify it for the environment. Gulfstream has no hidden runtime defaults: every required field must be present and valid. Configuration covers:
- listener, public URL, CORS, request limits, and shutdown
- every public route prefix
- web templates, assets, branding, links, and cache policy
- SQLite pool and durability settings
- durable, temporary, stream, original, and trash storage
- registration, passwords, sessions, cookies, CSRF, API keys, and playback tokens
- upload and protected import controls
- worker concurrency, leases, retries, and polling
- FFmpeg/FFprobe commands, rendition profiles, codecs, HLS packaging, and retention
- analytics cookies, heartbeat limits, reporting, and retention
- player template and optional hls.js URL
- tracing filters and JSON logs
${VARIABLE} placeholders inside TOML strings are resolved from the environment. Missing variables fail startup.
§Documentation development
The documentation site uses VitePress 2.0.0-alpha.19 and Node.js 22 or newer.
cd docs
npm ci
npm run docs:devBuild it with:
npm run docs:build§Quality commands
Run the complete local gate:
make verifyOr run each step directly:
cargo fmt --all -- --check
cargo check --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo build --release
cargo publish --dry-run
node scripts/validate-web.mjsContributor workflow and review expectations are documented in CONTRIBUTING.md.
§Release automation
ci.ymlvalidates web assets, formats, checks, lints, tests, builds Rustdoc and release artifacts, performs a crates.io dry run, and builds VitePress.docs.ymlpublishes VitePress and generated Rustdoc to GitHub Pages frommain.publish-crates.ymlvalidates a published GitHub release tag and publishes the matching package to crates.io using theCARGO_REGISTRY_TOKENsecret.security.ymlenforces license, source, ban, and advisory policy with cargo-deny.- Dependabot checks Cargo, npm, and GitHub Actions dependencies weekly.
Before enabling documentation deployment, select GitHub Actions as the Pages source. Before automated crates.io releases, complete the one-time package bootstrap described in the release guide and store the crates.io token in the repository’s CARGO_REGISTRY_TOKEN secret (or the crates-io environment).
§Storage and database
SQLite stores accounts, hashed credentials, media metadata, renditions, durable jobs, browser sessions, playback sessions, raw events, exact unique-viewer rows, and daily aggregates. Filesystem storage contains originals and generated HLS assets.
Back up the database and storage tree as one consistency unit. The worker publication path uses staging directories and state/lease checks so incomplete or stale work is not exposed as ready media.
§Security
Read SECURITY.md before production deployment. At minimum, terminate HTTPS, enable secure cookies, use independent high-entropy secrets, restrict CORS to exact origins, keep private-network imports disabled unless explicitly required, and run the service as an unprivileged user.
§License
MIT
Re-exports§
pub use config::Config;pub use config::configured_path;
Modules§
Functions§
- run
- Runs Gulfstream until the process receives a shutdown signal.