Installation
Docker, or Node.js with systemd.

01How it fits together

Kinetica is one Node.js server. It renders videos on the same machine with Chrome (the frames) and ffmpeg (encoding and sound), and keeps everything it stores in one folder, DATA_DIR: the two SQLite databases, uploads, music and rendered videos (docs/guide/install.md, docs/guide/backups.md). It listens on port 8787 by default. Caddy (or nginx) in front of it serves https on your domain.

02Option A: Docker

1. Install Docker Follow docs.docker.com/engine/install/ubuntu.
2. Unpack Kinetica into a folder, for example /opt/kinetica, and go there.
3. Create .env from the template and edit it (values below).
4. Build and start the container.
5. Read the setup code from the log.
6. Put https in front (https with Caddy), then continue with First steps.

cd /opt/kinetica
cp .env.example .env
nano .env                     # set PUBLIC_URL, ADMIN_SECRET_KEY, TRUST_PROXY_HOPS=1
docker build -t kinetica .
docker volume create kinetica-data
docker run -d --name kinetica --restart unless-stopped \
  -p 127.0.0.1:8787:8787 --env-file .env \
  -v kinetica-data:/app/data kinetica
docker logs kinetica          # the one-time setup code for /admin is here

The values to set in .env:

• PUBLIC_URL: the https address people will use, for example https://video.your-agency.com.
• ADMIN_SECRET_KEY: run openssl rand -hex 32 and paste the result. It encrypts the API keys you save in the console. Keep a copy somewhere safe: without it the saved keys cannot be read after a restore.
• TRUST_PROXY_HOPS=1 when Caddy or nginx is in front (it almost always is).

The image is built in two stages (Dockerfile): the first compiles the server and the studio app, the second runs plain node on node:22-bookworm-slim with Debian's chromium, ffmpeg and fonts-noto-color-emoji. It runs as the unprivileged node user, sets DATA_DIR=/app/data and CHROME_PATH=/usr/bin/chromium, and keeps all data in the kinetica-data volume.

Commands inside the container run with docker exec, for example docker exec kinetica npm run backup.

03Option B: Node.js on Ubuntu 22.04 / 24.04

1. Node.js 22 (22.12 or newer)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

2. ffmpeg, the emoji font and build tools

sudo apt install -y ffmpeg fonts-noto-color-emoji python3 make g++

The build tools are only used when no prebuilt database driver fits your system.

3. Google Chrome (amd64 servers)

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb

The server looks for Chrome at /usr/bin/google-chrome-stable, /usr/bin/google-chrome, /usr/bin/chromium and /usr/bin/chromium-browser (packages/render/src/render.ts). Anywhere else, set CHROME_PATH in .env. ffmpeg and ffprobe are looked up on the PATH; set FFMPEG_PATH (and FFPROBE_PATH) if they live elsewhere.

4. Install and build Kinetica

cd /opt/kinetica
npm ci
cp .env.example .env          # then edit it as in Option A
npm run build
npm start

npm run build compiles the server into dist/ and the studio app into web/dist/. npm start runs node dist/src/server/index.js. The log prints the address and the console's one-time setup code. Once it works, stop it with Ctrl+C and run it as a service.

5. A systemd service

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

[Unit]
Description=Kinetica
After=network.target

[Service]
WorkingDirectory=/opt/kinetica
ExecStart=/usr/bin/node dist/src/server/index.js
Restart=always
User=studio
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

sudo useradd --system --home /opt/kinetica studio
sudo chown -R studio:studio /opt/kinetica
sudo systemctl daemon-reload
sudo systemctl enable --now kinetica
journalctl -u kinetica -f     # the log, with the setup code

The server reads .env from its own folder by itself (src/server/index.ts), so the unit file needs no EnvironmentFile.

04https with Caddy

sudo apt install -y caddy

/etc/caddy/Caddyfile (use your own domain):

video.your-agency.com {
    request_body {
        max_size 250MB
    }
    reverse_proxy 127.0.0.1:8787
}

sudo systemctl reload caddy

Caddy gets the certificate by itself once the domain points at the server. The 250 MB body limit lets video clip uploads through (the studio accepts clips up to 200 MB, src/server/routes/workspace.ts). Keep TRUST_PROXY_HOPS=1 in .env so rate limits see the visitor's address, not Caddy's.

05Check the installation

• curl http://127.0.0.1:8787/healthz on the server answers {"ok":true,"version":"1.0.0"}.
• https://your-domain/admin opens the console's "Create the owner" screen.
• After you sign in: the console's System health page shows Chrome and ffmpeg as found, free disk in DATA_DIR and the keys that are still missing.

Continue with First steps.