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-64orARM64) 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
8000and8100must 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.
-
File Station: in the shared folder
docker, create a folderfacestream. It holds all your data and is the one thing to back up. -
Container Manager → Project → Create.
-
Project name
facestream, Path/docker/facestream. -
Source: create a
compose.yamland 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 -
Skip the web portal settings, FaceStream.AI brings its own interface.
-
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, taglatest - a folder on the NAS, mounted at
/data - the ports
8000 → 8000and8100 → 8100, TCP - the variable
TZwith 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:
amd64for Intel or AMD processors.arm64for 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:
- Without Docker: follow Linux without Docker and download
the
arm64package. - With Docker already installed: follow Docker.
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:
Environmenttells FaceStream.AI where the folder is.ReadWritePathslets 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.RequiresMountsForstarts 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, andsystemctl status facestream-videosays 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.