Installation

FaceStream.AI comes as a Docker image for linux/amd64 and linux/arm64, and as a package for Linux without Docker. Both are the same software; which edition it runs as is decided by the licence you enter, not by what you download.

Everything that changes, settings, enrolled people, visits, the licence, lives in one data folder. The program itself is disposable: you can delete and recreate the container at any time, as long as the data folder stays.

Before you start

Do not forward ports 8000 or 8100 from your router to the internet. For access from outside, use a VPN into your own network, many routers and NAS systems have one built in.

Docker

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

Then open http://<address of the machine>:8000 and choose a password, there is no preset one.

Docker Compose

The same as a compose.yaml:

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:

docker compose up -d

Synology

On a Synology NAS with DSM 7.2 or later, through the NAS's own interface. A project in Container Manager is the safest way: the folder for your data is written into a file and cannot be forgotten the next time the container is rebuilt.

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 http://<address of the NAS>:8000 and choose a password.

Check once that the data folder is really used. After the first start, the folder docker/facestream in File Station contains config.json, auth.json and a folder known_faces. If it stays empty while the interface answers on port 8000, the line under volumes is missing or wrong, and the next update would lose everything.

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.

An address of its own on the network

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.

QNAP, Unraid and other NAS systems

Container Station on a QNAP, the Docker page on Unraid and most other container managers ask for the same four things:

• 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

32-bit ARM models cannot run it.

Linux without Docker

For a mini PC or a Raspberry Pi that should run nothing else. The package is built on Debian 12 (Bookworm) and needs a 64-bit system with systemd that is at least as recent: Debian 12 or later, Ubuntu 24.04, Raspberry Pi OS based on Bookworm. On an older system, use Docker.

Packages are not published at a public address. Sign in to your account on facestream-ai.com, open Downloads and download the one for your processor, amd64 for Intel and AMD, arm64 for a Raspberry Pi and other ARM boards. Then:

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

The installer puts the program in /opt/facestream, keeps all data in /var/lib/facestream, creates a user facestream without a login, and starts two services:

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

facestream-frontend is the interface on port 8000, facestream-video the recognition and the stream on port 8100. The time zone is the system's own.

Raspberry Pi

A Raspberry Pi 5 is the board to use; a Raspberry Pi 4 is the minimum, and only for the Free edition. Install the 64-bit Raspberry Pi OS, a 32-bit system cannot run FaceStream.AI. Then either install Docker and follow Docker above:

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

or use the arm64 package from Linux without Docker.

Put the data on an SSD rather than the memory card: the event database writes all the time, and a memory card wears out long before an SSD does. The figures for the Raspberry Pi on the page system requirements are planning values derived from measurements on faster machines; try your own camera and settings before relying on them.

Settings in the environment

Rarely needed beyond TZ:

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.

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.

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 starts them again; /var/lib/facestream is not touched.

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.

Backing up and moving

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.

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.