Skip to main content

Run VideoQ on-premises

Start with a single server to evaluate video processing, Q&A, backups and updates. Use the results to decide whether services need separate hosts.

EnvironmentGuide
One Linux server, with database, storage and queue includedSingle-server installation
Existing Kubernetes cluster and site-managed backing servicesThe Helm instructions below
Existing or separately provisioned local AILocal inference
Download and verify application imagesSigned releases

Both installation paths use production Node.js images and administrator-issued accounts. The root development Compose stack has its own local setup guide.

The following sections describe the Kubernetes deployment.

VideoQ can run its Web UI, Node.js API and Python workers on an existing Kubernetes cluster. For an initial small installation, a single-node K3s cluster is an option. The application is distributed through the repository's Helm chart, which contains installation, upgrade and rollback instructions, example values, and the external infrastructure requirements.

Runtime layout​

The chart manages application workloads. PostgreSQL, S3 storage, queue durability, inference services, cluster administration, DNS and TLS are managed by the site. Configure their addresses instead of installing duplicate infrastructure in the application release. A GPU inference server can run in the same cluster or on a separate machine; API and video workers call its endpoint.

For a concrete CPU or NVIDIA GPU deployment of local chat, embeddings and Whisper, see local inference. The default application values use hosted OpenRouter; the local overlay is an explicit opt-in.

How it differs from Cloudflare​

FunctionCloud deploymentOn-prem deployment
HTTP and chatWorkers / ChatExecution DOHono Node.js server with the same HTTP pipeline
Database connectionsHyperdriveDirect PostgreSQL, with a process-owned pool
Shared rate limitsRateLimiter DOPostgreSQL rows with transactional locking
Outbox / abandoned upload recoveryTaskScheduler DO alarmsCronJob reading the same persisted DB state every minute
RetentionWorkers daily cronDaily UTC CronJob
Media operationsR2 binding and signed URLsS3 API and signed URLs
Video jobsLambda SQS triggerLong-polling Python Deployment

The Node entrypoint does not load Durable Object classes or run wrangler dev. It enforces production authentication and validates required secrets on startup. The two chat transports keep their normal authentication, permissions, quota checks and streaming behavior. No inference service is called by the built-in HTTP smoke test.

First installation​

  1. Prepare PostgreSQL 17 with pgvector, a private S3 bucket and a persistent SQS-compatible queue with dead-letter delivery. Configure bucket CORS and ensure browsers can reach the S3 public endpoint.
  2. Follow signed releases to obtain verified public application images and charts. Building and publishing your own images is an alternative described in the chart README.
  3. Create the namespace and operator-owned Secret described in the chart README. API and worker must share the same user-secret encryption key.
  4. Copy charts/videoq/examples/site.yaml outside the repository, replace all site-specific values, and merge the generated verified-images.json last as shown in the release guide. Run Helm lint/template before installation.
  5. Install the chart. Its pre-install migration Job must complete before the application workloads are created.
  6. Confirm /ready, create the first administrator with node dist/provision-user.mjs --admin --username site_admin --email admin@example.com inside the API Pod, and privately open the returned single-use setup link. Then upload a short video and test Q&A and timestamp playback.

The repository does not publish images at the registry.example.edu addresses; these are placeholders for site-built images. For a disconnected network, transfer all images and the packaged chart ahead of time. Point chat, embeddings and transcription at validated local services. The on-prem edition disables Stripe, Google sign-in, YouTube/SearchAPI and Mailgun.

The chat adapter requires a nonempty OPENAI_API_KEY for local OpenAI-compatible servers too. Use a placeholder such as local-inference if that server has no authentication. Embeddings reuse it unless EMBEDDING_API_KEY is set.

For internet-connected sites, see signed releases and updates for artifact verification, automatic staging rehearsals and promotion.

Operations​

The API and worker scale independently. Size the database connection budget for all API replicas, vector-search connections, workers and maintenance Jobs. Changing the embedding model requires a planned reindex of existing data; dimensions alone do not make models interchangeable.

Set api.trustedProxyHops only after configuring the site's trusted ingress chain. Without it, IP rate limiting uses the TCP peer. Disable SSE buffering and configure an adequate response timeout on the ingress controller.

The worker stops taking new messages on SIGTERM and acknowledges completed work before exiting. Its default 840-second processing deadline stays below the 900-second execution lease. Unfinished work is retried through the existing persisted checkpoints. Monitor CronJob failures, queue age and dead letters.

Keep database, object data and encryption-key backups. A Helm rollback restores application manifests; SQL migration rollback and data restoration need their own tested procedure. Pre-upgrade migrations must remain compatible with the old application while its Pods are still running. See the chart README for breaking migrations, Secret rotation and recovery details.

Application pages and account provisioning​

The on-prem web image and Node API use the on-prem edition by default. It omits SaaS billing, the LP/pricing/commercial legal pages and public registration. Signed-out users enter at login. Administrators add users and issue short-lived, single-use setup/recovery links; no external mail service is needed. Course invitation links can also be shared privately with existing local accounts. New users have administrator-managed operational quotas instead of SaaS free plan caps. Existing user quotas are preserved until an administrator changes them. See the edition and bootstrap instructions. Core video/course/search/chat, API keys/MCP and intranet sharing remain available.

Web security headers and storage access​

The nginx image generates security headers from the same public/_headers policy as the Cloudflare Web Worker. CSP, frame protection, nosniff, Referrer-Policy, Permissions-Policy and COOP apply to HTML, assets, HEAD/304 replies and errors. nginx hides its version. HTML is revalidated (no-cache); immutable assets keep their one-year cache policy.

Helm adds the origin of storage.endpoint to CSP's connect-src, media-src and img-src, without exposing storage.internalEndpoint. This permits signed uploads, media redirects and thumbnails without allowing arbitrary HTTP(S) destinations. Bucket CORS must still allow publicUrl. Docker Compose supplies both local Garage origins automatically, including GARAGE_S3_PORT. Standalone web containers accept a space-separated VIDEOQ_CSP_STORAGE_ORIGINS list, for example https://s3.example.edu:9443. Paths, credentials, wildcards and non-HTTP(S) sources are rejected at startup. An absolute VITE_API_URL adds its origin at build time; rebuild the image if it changes.

COEP and CORP are deliberately not enabled globally: VideoQ does not require cross-origin isolation, and imposing it can block third-party frames, images or media. The shared policy retains YouTube and Google Fonts compatibility for SaaS builds; on-prem builds exclude those integrations. COOP is same-origin, and camera, microphone and geolocation are disabled. Configure TLS/HSTS at the site's HTTPS ingress rather than the plain-HTTP local nginx listener.

After building the image, check its headers and cache/error behavior:

node --test apps/web/scripts/test-nginx-headers.mjs
node apps/web/scripts/test-nginx.mjs videoq-web:onprem-ci

Run a passive ZAP baseline against your local test installation on Linux:

mkdir -p /tmp/videoq-zap-reports
docker run --rm --network host --user "$(id -u):$(id -g)" \
-v /tmp/videoq-zap-reports:/zap/wrk:rw \
ghcr.io/zaproxy/zaproxy@sha256:030d3df57735dacbb83464854758e674dd9ad01d79d12a129a8e58b1fd384238 \
zap-baseline.py -t http://localhost/ -m 1 -T 5 \
-r baseline.html -J baseline.json

Exit 0 is success, 1 is a configured FAIL, 2 means WARNs, and 3 is a scan error. Inspect the JSON/HTML and the URLs reached: a public-page baseline does not cover authenticated APIs. Classify residual alerts rather than hiding them. Cached public assets and library comments are not proof of disclosure. CSP's style-src 'unsafe-inline' supports runtime UI styles without allowing inline JavaScript; missing COEP/CORP reflects the compatibility decision above. Check authenticated access separately in a disposable deployment, keeping cookies and signed URLs out of shared reports.