ulka-vms

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: AGPL-3.0

README

Ulka VMS

Open-source video hosting you run on your own servers: upload a video once, and it plays smoothly, encrypted, on any phone or screen. For teams that want their videos, viewers and costs on infrastructure they control.

Ulka VMS is the open-source edition of the video platform behind Ulka.

Features

  • Uploads that survive bad connections: send a file whole or in parts, and resume where it stopped. Or import one from a link.
  • Encoding for every screen: each video is encoded into several qualities (HLS) in parallel pieces across your workers, with the low qualities playable first.
  • Encrypted at rest and in playback: every video gets its own AES-128 key, sealed in your database or kept by SecureDRM, a hosted key service.
  • Private videos: signed playback links that expire, limited by website, country or viewer address, with an optional watermark of the viewer's name.
  • A player to embed: adaptive quality, chapters, captions, storyboard previews and keyboard shortcuts, styled per library.
  • Libraries and folders, covers, captions, chapters, MP4 downloads and per-library encoding presets.
  • Delivery straight from your server or through any CDN: Ulka CDN, Cloudflare, CloudFront, Bunny, Fastly or Akamai, with setup steps for each.
  • Teams: workspaces, members with roles, API keys with scopes and IP allow lists, and signed webhooks.
  • Usage: minutes encoded and stored, and video delivered, per workspace and day.
  • Viewer checks: a viewer can run a playback check in their own browser and send you the result with a code.
  • The API is the product: everything the console does is in the OpenAPI spec.

Getting started

Requirements
  • Go 1.27 and Node 24
  • Docker, for Postgres and ClickHouse (development adds a local stand-in for S3-compatible storage)
  • On the path: ffmpeg and ffprobe, Shaka packager v3.9 and cwebp (package webp)
Install and configure
git clone https://github.com/ulkanetworks/ulka-vms.git && cd ulka-vms
cp .env.example .env

Fill in the blanks in .env: POSTGRES_PASSWORD, ULKA_APP_PASSWORD, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and CLICKHOUSE_PASSWORD (any long random values, openssl rand -base64 24), and SEAL_KEY (openssl rand -base64 32). SEAL_KEY encrypts video keys and other secrets: back it up and never change it once there is data.

Run
set -a; . ./.env; set +a
docker compose up -d                     # Postgres, ClickHouse, telemetry and a local stand-in storage
docker compose exec postgres psql -U postgres -c "CREATE DATABASE ulka_vms_test"   # for the tests
go run ./cmd/ulka-vms migrate
go run ./cmd/ulka-vms api                # the API on API_ADDR
go run ./cmd/ulka-vms worker             # encoding and background jobs (another terminal)
go run ./cmd/ulka-vms origin             # video segments on ORIGIN_ADDR (another terminal)
cd web && npm ci && npm run dev          # the console on http://localhost:5173

Open the console, create your account and upload a video.

Usage

The console covers everything; programs use the API with a key from API keys:

curl http://localhost:5173/v1/assets -H "Authorization: Bearer $KEY"

The guides and the API reference are in the console under Docs.

Each workspace has limits (largest upload, encoding minutes a month). go run ./cmd/ulka-vms limits lists the workspaces; to change one's limits:

go run ./cmd/ulka-vms limits <workspace id> encode_minutes_monthly=6000 max_upload_bytes=21474836480

Development

go build ./... && go vet ./...
go test ./...                    # needs the compose services; uses the ulka_vms_test database
cd web && npm run check          # type check
cd web && npm test               # console unit tests

The layout: core is the shared kernel (sign-in, permissions, errors, tenancy), accounts, video, transcoder, player, webhooks, usage and notices are the modules, origin serves segments from storage, securedrm is the client of the optional hosted key service, app assembles them, cmd/ulka-vms is the binary, migrations the Postgres schema and web the React console. ARCHITECTURE.md explains how they fit together and how to build on Ulka VMS.

Deployment

One server runs everything, with videos kept in S3-compatible storage of your choice (AWS S3, Cloudflare R2, Backblaze B2, Wasabi, MinIO); more machines can be added for encoding. Make a private bucket and a key for it, point videos., player. and origin. under your domain at an Ubuntu or Debian server, then run:

curl -fsSL https://github.com/ulkanetworks/ulka-vms/releases/latest/download/install.sh | sudo bash

It asks for your domain, email and storage details, installs everything and starts it with HTTPS; run it again to upgrade. SELF-HOSTING.md has the same steps by hand, plus backups. Service files are in deploy/systemd and the Caddy configuration in deploy/Caddyfile.

Contributing

Contributions are welcome: read CONTRIBUTING.md first. Report security problems privately as described in SECURITY.md, never in a public issue.

License

Ulka VMS is licensed under the GNU Affero General Public License v3.0. If you run a modified version as a service, you must offer its source to its users.

"Ulka" and the Ulka logo are trademarks of Ulka Networks. The licence covers the code, not the name: a fork must use its own name and logo.

Directories

Path Synopsis
Package api holds the OpenAPI description of Ulka's public API.
Package api holds the OpenAPI description of Ulka's public API.
Package app assembles the modules into the API handler and the worker's River client, with what an application built on ulka-vms adds (Extension).
Package app assembles the modules into the API handler and the worker's River client, with what an application built on ulka-vms adds (Extension).
cmd
ulka-vms command
Command ulka-vms is the API, the worker and the migrations of ulka-vms, an open-source video platform.
Command ulka-vms is the API, the worker and the migrations of ulka-vms, an open-source video platform.
db
Package notices tells a workspace what needs its attention, worked out from its current state each time it's asked: nothing is stored, so a notice goes away when its cause is fixed.
Package notices tells a workspace what needs its attention, worked out from its current state each time it's asked: nothing is stored, so a notice goes away when its cause is fixed.
Package origin serves videos' encrypted segments from storage to viewers and CDNs, reading the bucket with this server's own storage key, so the bucket itself stays private.
Package origin serves videos' encrypted segments from storage to viewers and CDNs, reading the bucket with this server's own storage key, so the bucket itself stays private.
Package player is Ulka's video player: the look and controls a library chooses (settings), and what the embedded player fetches to render itself.
Package player is Ulka's video player: the look and controls a library chooses (settings), and what the embedded player fetches to render itself.
Package securedrm is the client of SecureDRM, Ulka Networks' hosted key service: it keeps each video's key and hands it only to players carrying a token this server signed.
Package securedrm is the client of SecureDRM, Ulka Networks' hosted key service: it keeps each video's key and hands it only to players carrying a token this server signed.
Package transcoder turns an uploaded file into a ladder of encrypted HLS renditions: it reads the source, plans the ladder, hands the pieces to the nodes that ask for them (the scheduler), joins and packages what they make, and reports back.
Package transcoder turns an uploaded file into a ladder of encrypted HLS renditions: it reads the source, plans the ladder, hands the pieces to the nodes that ask for them (the scheduler), joins and packages what they make, and reports back.
db
Package usage reports what a tenant consumed per calendar month (UTC).
Package usage reports what a tenant consumed per calendar month (UTC).
db
db

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL