Skip to content

Self-hosting

Network mode and login

Run the server for other people: bind address, TLS, users, roles, sessions and the fail-closed start-up checks.

Last updated:

You will learn#

  • when the server is in network mode and what it requires;
  • how to create users and what a role may do;
  • which configuration errors stop the server, and the fix for each.

The idea#

Network mode is any bind address that is not loopback, with VUKEM_VIDEO_MODE=network. A non-loopback address with the mode local is a start-up error, never a silent exposure. The local token is not accepted in this mode.

  • Login is mandatory. There is no open registration, no social login and no email. The operator creates the users.
  • TLS is required. Either the process terminates it (TLS_CERT_FILE and TLS_KEY_FILE, TLS 1.2 or newer) or a reverse proxy does, with TRUSTED_PROXIES and TRUST_FORWARDED_PROTO=true (see Put Caddy in front). APP_URL must be the public https address, and the server accepts only that host and origin. The one exception is a container used on its own machine: APP_URL=http://localhost:<port> or http://127.0.0.1:<port> is served over plain HTTP, and only to that name.
  • APP_KEY is required, 32 bytes or more in base64.
  • Not as root. Running as root or Administrator is refused unless VUKEM_VIDEO_INSECURE_ALLOW_ROOT=true.
  • Import by path is confined to the directories in VUKEM_VIDEO_IMPORT_ROOTS (absolute paths of existing directories, outside the workspace).

Users and roles#

An admin has the five scopes read, edit, media, render and admin. A member has read, edit, media and render. A user sees and changes only the projects they created; an administrator manages users, keys and the trash but does not gain access to other users' projects. A password has 12 to 1,024 characters.

Create the first administrator at start-up, from the environment, when no user exists yet:

Terminal
VUKEM_VIDEO_ADMIN_EMAIL=admin@example.com
VUKEM_VIDEO_ADMIN_PASSWORD=@file:/run/secrets/admin_password

Create or change users with the commands below. They run in process and need the workspace lock, so stop the server first. The password is read from a terminal prompt (twice, without echo) or from the first line of standard input, never from an argument.

Terminal
vukem-video user:create ana@example.com
vukem-video user:create admin2@example.com --admin
echo "a-new-long-password" | vukem-video user:passwd ana@example.com

A password change ends the sessions and revokes the API keys of that user.

Manage users while the server runs#

An administrator who is signed in in the browser can manage users through the HTTP API without stopping the server. The routes exist in network mode only and need the admin scope on a browser session: an API key is refused here, whatever its scopes. There is no editor page for it yet.

RouteDoes
GET /api/v1/userslists every user, oldest first, disabled ones included
POST /api/v1/userscreates a user from email, password and an optional role (admin or member, default member)
PATCH /api/v1/users/{user_id}sets role and, or, disabled in one statement
Terminal
APP=https://video.example.com
curl -fsS -b jar.txt -H "Content-Type: application/json" -H "Origin: $APP" \
  -d '{"email": "ana@example.com", "password": "a-long-password-here"}' "$APP/api/v1/users"
curl -fsS -b jar.txt -X PATCH -H "Content-Type: application/json" -H "Origin: $APP" \
  -d '{"disabled": true}' "$APP/api/v1/users/<user_id>"

jar.txt is the cookie file of a login, as in API keys and scopes. A user is shown with user_id, email, role, disabled and created_ms; the password never appears. Changing a role, or disabling a user, ends their sessions at the next request and narrows or stops their keys. The last enabled administrator cannot be demoted or disabled: the answer is E_INVALID_STATE with the hint to make another administrator first. A used email, a bad role and a short password are E_VALIDATION.

Sessions and login#

The browser session cookie is __Host-vukem_video_session (the plain-HTTP container case uses the local cookie name). A session ends after 8 hours idle or 7 days in all. Login is POST /auth/login with email and password; a wrong email and a wrong password give the same E_UNAUTHORIZED. Failed logins are throttled per email and per address before the password is checked.

Start-up errors#

The process exits with status 1 and a message that names the variable.

ConditionFix
Non-loopback address in local modeset VUKEM_VIDEO_MODE=network
Network mode without an https APP_URLset APP_URL to the public https address
https without TLS files or a trusted proxyset TLS_CERT_FILE and TLS_KEY_FILE, or TRUSTED_PROXIES and TRUST_FORWARDED_PROTO=true
APP_KEY missing or shortopenssl rand -base64 32
Running as rootrun as an ordinary user
Invalid import rootan absolute, existing directory outside the workspace
Unsafe transcription endpointhttps, or http to a loopback address, with no user name in the URL
A limit set to zero or lessgive a positive number
VUKEM_VIDEO_FFMPEG not an absolute path to a filegive the full path

Common mistakes#

  • Setting APP_URL to one name and browsing by another: the host and the origin must match APP_URL exactly.
  • Running user:create while the server runs: E_WORKSPACE_LOCKED. Stop the server, or use the first-administrator variables.
  • Forgetting that every project belongs to its creator: an agent key sees only its owner's projects.

Next steps#