OmniLux Docs

Appearance

Bare Metal Installation ​

Run OmniLux directly on your server without Docker.

When to use this path ​

Choose bare metal when you want direct process control, native systemd integration, or a host environment where Docker is not the right operational fit. If you want the simplest supported path, use Docker Installation instead.

Prerequisites ​

  • Node.js 22+ (LTS recommended)
  • pnpm (10.x or later)
  • FFmpeg (6.0+ for transcoding and streaming)
  • SQLite (bundled via better-sqlite3, no separate install needed)
  • Git
  • Ubuntu 22.04+, Debian 12+, or comparable Linux distribution

Installation ​

1. Install system dependencies ​

bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y git ffmpeg curl build-essential

# Install Node.js 22 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install pnpm
corepack enable
corepack prepare pnpm@latest --activate

2. Clone the repository ​

bash
git clone https://github.com/omnilux-tv/omnilux.git
cd omnilux

Private repository access

If the canonical omnilux-tv/omnilux repository is still private for your rollout, use the access-granted clone URL provided by the OmniLux team.

3. Install dependencies ​

bash
pnpm install

4. Build ​

bash
pnpm build

5. Run ​

bash
NODE_ENV=production PORT=4000 pnpm start

OmniLux will start on port 4000 and create its SQLite database at data/omnilux.db.

Use a dedicated service user and keep runtime state separate from the source checkout:

  • App checkout: /opt/omnilux
  • Database and downloads: /var/lib/omnilux
  • Media library: /srv/media

Environment variables ​

Set these before starting or add them to a .env file:

bash
export NODE_ENV=production
export PORT=4000
export OMNILUX_DB_PATH=/var/lib/omnilux/omnilux.db
export OMNILUX_LIBRARY_ROOT=/srv/media
export OMNILUX_DOWNLOAD_PATH=/var/lib/omnilux/downloads

See Environment Variables for the full reference.

systemd service ​

Create /etc/systemd/system/omnilux.service:

ini
[Unit]
Description=OmniLux Media Platform
After=network.target

[Service]
Type=simple
User=omnilux
Group=omnilux
WorkingDirectory=/opt/omnilux
ExecStart=/usr/bin/node apps/server/dist/index.js
Restart=on-failure
RestartSec=5

Environment=NODE_ENV=production
Environment=PORT=4000
Environment=OMNILUX_DB_PATH=/var/lib/omnilux/omnilux.db
Environment=OMNILUX_LIBRARY_ROOT=/srv/media
Environment=OMNILUX_DOWNLOAD_PATH=/var/lib/omnilux/downloads

# Hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/omnilux /srv/media

[Install]
WantedBy=multi-user.target

Enable and start:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now omnilux

Then verify the process and API are reachable before you move on to reverse proxy or remote access.

Updating ​

bash
cd /opt/omnilux
git pull
pnpm install
pnpm build
sudo systemctl restart omnilux

Database migrations run automatically on startup.

After updates, use Updating OmniLux for the safer operational checklist.

Backup

Before updating, back up your database: cp /var/lib/omnilux/omnilux.db /var/lib/omnilux/omnilux.db.bak