Quick Start

Install from a package, add the first camera, and check that recording runs and the stream opens. About ten minutes.

What you need

• A Linux server: Debian or Ubuntu (.deb package), RHEL, Rocky or AlmaLinux (.rpm package)
• An IP camera with an RTSP stream address, reachable from that server
• ffmpeg — for archive export and time-lapse, and for the 720p step over HLS. Ingest, recording and restreaming work without it

1. Install the package

Download the package for your system from the download page and install it.

Debian / Ubuntu

sudo dpkg -i forgevis_*.deb

RHEL / Rocky / AlmaLinux

sudo rpm -i forgevis-*.rpm

The package puts everything in the usual places:

What	Where
Program	/usr/bin/forgevis
Main configuration	/etc/forgevis/config.yaml
Camera files	/etc/forgevis/conf.d/
Service working directory	/var/lib/forgevis
Logs	/var/log/forgevis/

2. Choose where the archive goes

Where the archive goes is set by the record_path template in /etc/forgevis/config.yaml. Point it at a directory on a disk with room for the recordings:

cameraDefaults:
  record_path: "/var/lib/forgevis/recordings/%path/%Y/%m/%d/%path_%Y-%m-%d_%H-%M-%S.mp4"

%path is the camera ID, the rest is the date and time the file starts. Directories are created as needed.

The archive is best given a disk or pool of its own. On a ZFS pool, for example, the path can look like this:

cameraDefaults:
  record_path: "/rpool/%path/%Y/%m/%d/stream-%path_%Y-%m-%d_%H-%M-%S.mp4"

The packaged configuration ships with /var/lib/forgevis/recordings/.... The service runs as the forgevis user, so give your own archive directory to it before the first start:

sudo chown forgevis:forgevis /rpool

3. Add a camera

Each camera is easiest to keep in its own file in /etc/forgevis/conf.d/. Create /etc/forgevis/conf.d/camera_001.yaml:

camera_001:
  source: "rtsp://admin:password@192.168.1.100:554/stream1"
  sub: "rtsp://admin:password@192.168.1.100:554/stream2"   # substream, optional

camera_001 is the camera ID: it appears in stream addresses and in the archive path. Latin letters, digits, _ and - are allowed.

Where to find the RTSP address

It is in the camera's documentation or its web interface. Check the address in VLC (Media → Open Network Stream) from the server itself — if VLC shows video, ForgeVis will take it too.

Files in conf.d/ are picked up on the fly: further cameras are added without restarting the service.

4. Start the service

sudo systemctl enable --now forgevis
systemctl status forgevis

The status should read active (running). If the service did not come up, the reason is in the journal: the configuration is checked at startup, and the error names the key to fix.

sudo journalctl -u forgevis -b

Readiness of the whole server — storage, recording directory, license:

curl http://localhost:9997/api/health/ready

5. Check the recording

ls -lR /var/lib/forgevis/recordings/camera_001

The file appears as soon as the camera connects and grows as recording goes on. The archive is written as fragmented MP4, so a file can be opened while it is still being written. A new file starts every 15 minutes (segmentDuration: 900 in the record section).

The camera connecting shows in the journal (resolution and codecs are whatever your camera sends):

sudo journalctl -u forgevis -f

Starting recorder for camera: camera_001
Stream parameters for camera_001: video 1920x1080 H.264, audio 8000Hz 1ch G.711 A-law

The journal is also written to /var/log/forgevis/forgevis-info-<date>.log.

6. Open the stream

On the server itself the stream opens without a password:

# RTSP — main stream and substream
ffplay rtsp://localhost:8554/camera_001
ffplay rtsp://localhost:8554/camera_001/sub

# HLS — for browsers and players
ffplay http://localhost:8888/camera_001/index.m3u8

From another computer you need an account. The packaged configuration lets in without a password only from the server itself, so add a viewing user to /etc/forgevis/config.yaml, keeping the existing entry for 127.0.0.1:

security:
  auth_method: internal
  users:
    - user: any
      pass:
      ips: ["127.0.0.1/32", "::1/128"]
      permissions:
    - user: viewer
      pass: "argon2:<password hash>"
      ips: []
      permissions:
        - action: read

The password hash:

echo -n "password" | argon2 "$(openssl rand -hex 16)" -id -t 2 -m 16 -p 1 -e

Users are read at startup, so restart the service after changing security:

sudo systemctl restart forgevis

Now the stream opens from any computer on the network:

vlc rtsp://viewer:password@server:8554/camera_001

HLS is at http://server:8888/camera_001/index.m3u8; the browser asks for the login and password. If the server has a firewall, open ports 8554 (RTSP) and 8888 (HLS).

Other ways to authenticate and access rights are in Security & Authentication.

Recording only, or restreaming only

Recording and restreaming are switched independently:

• Restreaming only, no archive — record: false on the camera
• Archive only, no RTSP server — rtsp.enabled: false in config.yaml

If something does not work

The camera does not connect. The journal shows a connection error. Check the address in VLC from the server itself, the camera's login and password, and that the camera answers ping.

No recording files. Check record_path: the directory must be on a disk that exists (df -h). Check that the camera does not have record: false, and look for write errors in the journal.

The stream does not open from another computer. Check the account, and that the service was restarted after changing security. Check the firewall ports and that rtsp.enabled is not turned off.

The service does not start. sudo journalctl -u forgevis -b — the error message names the configuration key to fix.

Next

• Configuration — every setting
• Substreams — record in full quality, show a lighter stream on screen
• Archive retention — how long recordings are kept
• Security & Authentication — users, rights, TLS
• Clustering & HA — several recording servers