Skip to content

FaceStream.AI

Documentation

Getting started

Installation

Choose the installation steps for Docker, Synology, another NAS or Linux. Start FaceStream, then add your camera. Optional maintenance and advanced settings follow.

On this page

Choose your system below and follow that section only. Once FaceStream is running, continue with Getting started to add your camera and recognise a person.

Your setup Follow this guide
Docker is already installed Docker — one command
You manage containers with Compose Docker Compose
Synology NAS with DSM 7.2 or later Synology — use Container Manager
QNAP, Unraid or another NAS Other NAS systems
Raspberry Pi Raspberry Pi
64-bit Linux, without Docker Linux without Docker

All methods install the same software. Your licence determines the edition; you do not need a different download for Pro or Business.

Before you start

  • Check your hardware: a supported 64-bit system (x86-64 or ARM64) is required. See the system requirements for your camera count. Recognition uses the CPU; no graphics card is needed.
  • Know your machine's local IP address. You will use it to open FaceStream in your browser, for example http://192.168.1.20:8000.
  • Keep it on your local network. Ports 8000 and 8100 must be reachable by the devices that use FaceStream. Do not forward them to the internet; use a VPN for remote access.

The examples use Europe/Berlin. Replace it with your time zone so messages show the correct local time.


Docker

1. Run this command on the machine where Docker is installed:

docker run -d --name facestream \
  -p 8000:8000 -p 8100:8100 \
  -v facestream-data:/data \
  -e TZ=Europe/Berlin \
  --restart unless-stopped \
  kumkju/facestream:latest

2. Open FaceStream: http://<your machine's IP address>:8000.

3. Continue with Getting started to choose a password and add your first camera.

The command creates facestream-data to keep your settings, photos and visits between container restarts and updates. Keep this volume when replacing the container.

Docker Compose

1. Create a file named compose.yaml with this content:

services:
  facestream:
    image: kumkju/facestream:latest
    container_name: facestream
    ports:
      - "8000:8000"   # the interface
      - "8100:8100"   # the video stream and the trigger address
    volumes:
      - facestream-data:/data
    environment:
      TZ: Europe/Berlin
    restart: unless-stopped

volumes:
  facestream-data:

2. Start it from the folder containing that file:

docker compose up -d

3. Open http://<your machine's IP address>:8000, then follow Getting started.

Keep the facestream-data volume: it contains your settings, photos and visits.


Synology

Use Container Manager on DSM 7.2 or later. You will create one project with a folder that keeps your data.

  1. File Station: in the shared folder docker, create a folder facestream. It holds all your data and is the one thing to back up.

  2. Container Manager → Project → Create.

  3. Project name facestream, Path /docker/facestream.

  4. Source: create a compose.yaml and paste:

    services:
      facestream:
        image: kumkju/facestream:latest
        container_name: facestream
        restart: unless-stopped
        ports:
          - "8000:8000"
          - "8100:8100"
        volumes:
          - /volume1/docker/facestream:/data
        environment:
          TZ: Europe/Berlin
    
  5. Skip the web portal settings, FaceStream.AI brings its own interface.

  6. Confirm. DSM downloads the image and starts the container.

Open FaceStream: http://<your NAS IP address>:8000. Continue with Getting started.

Check that your data is saved: after the first start, open docker/facestream in File Station. It should contain config.json, auth.json and known_faces. If it is empty, check the volumes line before continuing: this folder keeps your data during updates.

Port 8000 already taken? Change only the left-hand side, for example "18000:8000" and "18100:8100", and open http://<address of the NAS>:18000.

QNAP, Unraid and other NAS systems

Open Container Station on QNAP or Docker on Unraid. Create a container with these settings:

  • the image kumkju/facestream, tag latest
  • a folder on the NAS, mounted at /data
  • the ports 8000 → 8000 and 8100 → 8100, TCP
  • the variable TZ with your time zone, and automatic restart switched on

Start the container, then open http://<your NAS IP address>:8000 and follow Getting started.

32-bit ARM models cannot run FaceStream.


Linux without Docker

Use a supported 64-bit Linux with systemd: Debian 12 or later, Ubuntu 24.04, or Raspberry Pi OS based on Bookworm. Use Docker on an older system.

1. Download your package from Downloads in your account:

  • amd64 for Intel or AMD processors.
  • arm64 for Raspberry Pi or other ARM boards.

2. Extract it and run the installer. Replace the example filename and folder below with those of your downloaded package:

tar xzf facestream-2.4.0-linux-arm64.tar.gz
cd facestream-2.4.0-linux-arm64
sudo ./install.sh

3. Open http://<your machine's IP address>:8000 and continue with Getting started.

The installer starts FaceStream automatically. It stores the program in /opt/facestream and your data in /var/lib/facestream, using a dedicated facestream user without a login. It uses your system's time zone.

If it does not start, check the services and log:

systemctl status facestream-frontend facestream-video
journalctl -u facestream-video -f

facestream-frontend serves the interface on port 8000; facestream-video handles recognition and the stream on port 8100. For custom folders or other service settings, see Settings on Linux without Docker.


Raspberry Pi

Use a Raspberry Pi 5 with 64-bit Raspberry Pi OS. A Pi 4 is the minimum and is only suitable for Free. A 32-bit system cannot run FaceStream.

Choose one route:

If you choose Docker and still need to install it, run:

curl -fsSL https://get.docker.com | sh

Then follow Docker.

Use an SSD for the data rather than the memory card because the event database writes frequently. Raspberry Pi sizing figures in the system requirements are planning estimates; test your own camera and settings before relying on them.


Installation complete

You can now add your camera and recognise a person. The remaining sections are for later maintenance or custom setups.


Updating

When a newer version is published, a button Update 2.x.y appears at the bottom left, next to the version number. It shows what changed and the commands for your installation. FaceStream.AI never installs anything by itself.

Your update period. A licence includes the versions published until the date shown under Updates until on the licence card. A version published after that date runs as the Free edition with that licence. The update button only offers versions your licence covers; if you update by hand after your update period has ended, use the version number instead of latest, kumkju/facestream:2.4.0, or extend the update period in your account first.

Version tags such as 2.4.0 never change; latest moves with every release.

Docker:

docker pull kumkju/facestream:latest
docker stop facestream && docker rm facestream

then the same docker run as before, with the same volume. With Docker Compose: docker compose pull && docker compose up -d.

Synology: in Container Manager, update the image under Image, then stop the project and build it again. The menu entries differ slightly between DSM versions, you want the one that rebuilds the project from its compose.yaml, not the one that deletes it.

Linux without Docker: download the new package and run the same three commands as for the installation. The installer stops the services, replaces the program and the two service files, and starts them again. /var/lib/facestream and your own settings in /etc/systemd/system/facestream-.service.d are not touched, see Settings on Linux without Docker. If you had changed a service file itself, the installer keeps your version next to it as .old and lists the lines that no longer apply.


Backing up and moving

The program uses well under a gigabyte of storage. Allow extra space for visit images; retention settings control how long they are kept.

Back up the data folder and nothing else: the volume facestream-data, the folder you chose on the NAS, or /var/lib/facestream. Stop FaceStream.AI while you copy it, so the event database is not in the middle of a write.

In the data folder
config.json Cameras, connections, rules and all other settings
auth.json The password and the key that signs sessions
events.db The visits and the delivery log
known_faces/ The photos of enrolled people
saved_faces/ The pictures kept for each visit
machine-id The identity of this installation, which the licence is bound to
licence.key, activation.json The licence and, if it needs one, its activation
encodings.npz, updates.json Caches that rebuild themselves

To move to another machine, copy the whole folder and start FaceStream.AI there with it. Because machine-id moves along, the licence stays with the installation. If you start from scratch on new hardware instead, the new installation has a new device ID; release the old device in your account first, see Editions and licence.

Forgot the password? Troubleshooting explains how to set a new one without losing anything.


Optional configuration

Skip this section for a standard installation. Use it only if you need custom data folders, environment settings or a separate network address on Synology.

Settings in the environment

For Docker, TZ is the only setting most installations need. Ports 8000 and 8100 are already mapped in the examples above. Additional variables are listed here for custom setups:

Variable Default What it does
TZ UTC Set this. The time zone for times in messages, e-mails and syslog lines, for example Europe/Berlin or Europe/London
DATA_FOLDER /data Where everything that changes is kept
FACES_FOLDER inside the data folder The photos of enrolled people, if they should live elsewhere, a network share, for example
EVENT_IMAGES_FOLDER inside the data folder The pictures kept for each visit, if they should live elsewhere. This is the folder that grows
CONFIG_SERVER_PORT 8000 The port of the interface inside the container
STREAMING_SERVER_PORT 8100 The port of the video stream inside the container

To move FaceStream.AI to other ports, change the host side of the port mapping, not these variables: -p 18000:8000 -p 18100:8100. The two port variables are for host networking or a NAS that already uses port 8000 itself, and then the interface and the video stream both need to know, set both.

Settings on Linux without Docker

The two services get these variables from their service files in /etc/systemd/system. Do not change those files: every update replaces them. Put your settings in a file of your own instead, which applies to both services and which no update touches:

sudo mkdir -p /etc/systemd/system/facestream-.service.d
sudo nano /etc/systemd/system/facestream-.service.d/local.conf

To keep the photos of enrolled people and the pictures of visits on a network share, for example:

[Unit]
RequiresMountsFor=/mnt/nas/faces /mnt/nas/images

[Service]
Environment=FACES_FOLDER=/mnt/nas/faces
Environment=EVENT_IMAGES_FOLDER=/mnt/nas/images
ReadWritePaths=/mnt/nas/faces /mnt/nas/images

Name every folder you move in all three places:

  • Environment tells FaceStream.AI where the folder is.
  • ReadWritePaths lets it write there. Otherwise it may only write to /var/lib/facestream: it could read the share, but neither enrol anyone nor keep a picture there.
  • RequiresMountsFor starts FaceStream.AI only once the share is mounted, so it never works with an empty folder in place of your people. If the share cannot be mounted, FaceStream.AI does not start, and systemctl status facestream-video says why; start it with the second command below once the share is back.

The share has to be mounted when the machine starts, an entry in /etc/fstab does that. Both folders have to exist, and the user facestream needs to be able to write to them. Then:

sudo systemctl daemon-reload
sudo systemctl restart facestream-frontend facestream-video

systemctl status facestream-video now lists the file under Drop-In. Other variables from the table go into the same file, as further Environment= lines under [Service]. Do not call it override.conf: that is the name systemctl edit gives a file for a single service, and a file of that name there would replace this one for that service. The data folder with the event database stays in /var/lib/facestream, it must not be on a network share.

An address of its own on the network

On Synology, if you would rather give FaceStream.AI its own address in your home network, no port conflicts, and cameras see an ordinary device, use a macvlan network. Container Manager cannot create one, so this takes one command over SSH (Control Panel → Terminal & SNMP → Enable SSH service):

sudo docker network create -d macvlan --subnet=192.168.1.0/24 --gateway=192.168.1.1 --ip-range=192.168.1.240/28 -o parent=eth0 lan

Adjust the network and the router to yours, and choose an --ip-range outside the range your router hands out by DHCP. parent is the NAS's network interface, eth0 usually, ovs_eth0 if Virtual Machine Manager is installed; sudo ip -br link lists them.

In the project, replace ports: with:

    networks:
      lan:
        ipv4_address: 192.168.1.242

networks:
  lan:
    external: true
    name: lan

The interface is then at http://192.168.1.242:8000. One limitation comes with it: the NAS itself cannot reach a container on a macvlan network, and the container cannot reach the NAS. Every other device in your network can.